Implementering av verktyg: JSON Schema och hanterare
På denna sida
Uppdaterad 2 november 2026 — MCP Python SDK v2. Denna kurs följer nu version 2 av
mcp-SDK:t (2.3.0 per den 2 oktober 2026):MCPServerersätterFastMCP, transportinställningar flyttas tillrun()ellerstreamable_http_app(), och en applikation som exponeras under ett riktigt värdnamn måste deklarera detta värdnamn (transport_security). Detta är också den version som krävs av Mistral SDK: extra-paketetmistralai[agents]krävermcp>=2.2.0,<3.0. Källor: Vad är nytt i v2 · Migreringsguide · Distribuera och skala.
Anatomin hos ett MCP-verktyg
Ett MCP-verktyg ser ut som en Python-funktion, men ur modellens perspektiv är det inte det. Det är ett kontrakt i fyra delar: ett namn, en beskrivning, ett JSON-indataschema och en hanterare som exekverar logiken. Modellen ser aldrig din kod – den ser bara detta kontrakt. Ett perfekt implementerat verktyg som är dåligt beskrivet kommer aldrig att anropas, eller så kommer det att anropas vid fel tillfälle. Därför avgör kvaliteten på kontraktet serverns effektivitet långt mer än kvaliteten på implementationen.
Vad dekoratorn bygger åt dig
MCPServer bygger detta kontrakt automatiskt utifrån din funktionssignatur och docstring. Du skriver vanlig Python:
from mcp.server.mcpserver import MCPServer
app = MCPServer("My Server")
@app.tool()
def search_documents(
query: str,
max_results: int = 10,
language: str = "fr",
include_archived: bool = False,
) -> str:
"""Searches for documents in the knowledge base.
Args:
query: Search terms (2-500 characters)
max_results: Maximum number of results (1-100, default: 10)
language: ISO 639-1 language code (default: fr)
include_archived: Include archived documents (default: false)
Returns:
JSON with the list of found documents and the total count
"""
# Search logic
...
Och modellen får detta:
{
"name": "search_documents",
"description": "Searches for documents in the knowledge base.",
"inputSchema": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Search terms (2-500 characters)"
},
"max_results": {
"type": "integer",
"description": "Maximum number of results (1-100, default: 10)",
"default": 10
},
"language": {
"type": "string",
"description": "ISO 639-1 language code (default: fr)",
"default": "fr"
},
"include_archived": {
"type": "boolean",
"description": "Include archived documents (default: false)",
"default": false
}
},
"required": ["query"]
}
}
Jämför de två blocken rad för rad: varje typannotering blir en JSON-typ, varje standardvärde blir ett default-fält, varje rad i Args-sektionen blir en parameterbeskrivning, och det enda argumentet utan standardvärde hamnar i required. Med andra ord försvinner allt du utelämnar från docstringen helt från kontraktet.
Namngivning och sedan beskrivning
Verktygets namn är funktionsnamnet, och modellen använder det som sin första ledtråd. Ett actionsverb följt av ett tydligt objekt lämnar inget utrymme för tvetydighet, medan ett generiskt eller tekniskt namn tvingar modellen att gissa:
# Bra: actionsverb + tydligt objekt
@app.tool()
def create_issue(title: str, body: str) -> str: ...
@app.tool()
def search_repositories(query: str) -> str: ...
@app.tool()
def get_user_profile(username: str) -> str: ...
# Dåligt: vagt, tvetydigt, tekniskt
@app.tool()
def process(data: str) -> str: ... # För vagt
@app.tool()
def handle_request(req: str) -> str: ... # Obegripligt för LLM:n
@app.tool()
def db_query(sql: str) -> str: ... # För tekniskt
Docstringen tar sedan över och utgör den viktigaste delen av hela din server. Den måste svara på tre frågor i denna ordning: när verktyget ska användas, vilka parametrar som ska anges med deras format och begränsningar, och vad som kan förväntas som svar. Följande exempel visar hur detta ser ut i ett verkligt scenario:
@app.tool()
def book_restaurant(
restaurant_name: str,
date: str,
party_size: int,
special_requests: str = "",
) -> str:
"""Books a table at a restaurant.
Performs a complete reservation including email
confirmation. Use this tool when the user wants
to book a specific restaurant.
Args:
restaurant_name: Exact name of the restaurant
date: Date and time in ISO 8601 format (e.g., 2026-04-15T19:30:00)
party_size: Number of guests (1-20)
special_requests: Special requests (allergies, occasion, etc.)
Returns:
JSON with the reservation number, confirmation,
and restaurant details
"""
...
Stycket efter den första raden är det som amatörserver oftast saknar. Utan det vet modellen vad verktyget gör, men inte i vilken situation det ska trigga. Och exemplet med datum i ISO 8601-format sparar dig dussintals anrop med "April 15 at 7:30 PM".
Typer, asynkrona hanterare och validering
MCPServer översätter vanliga Python-annoteringar till deras JSON Schema-motsvarigheter.
| Python | JSON Schema | Exempel |
|---|---|---|
str | string | "text" |
int | integer | 42 |
float | number | 3.14 |
bool | boolean | true |
list[str] | array av string | ["a", "b"] |
dict | object | {"key": "val"} |
Optional[str] | string (nullable) | "text" eller null |
Så snart ett verktyg kliver utanför sin egen process – nätverksanrop, databasfråga, läsning av fjärrfil – deklarera det som async. En synkron hanterare som väntar på ett HTTP-svar blockerar hela servern, och dina andra användare tillsammans med den:
import httpx
@app.tool()
async def fetch_api_data(endpoint: str) -> str:
"""Retrieves data from an external API.
Args:
endpoint: The API endpoint path (e.g., /users/123)
Returns:
JSON data from the API
"""
async with httpx.AsyncClient() as client:
response = await client.get(f"https://api.example.com{endpoint}")
response.raise_for_status()
return response.text
JSON-schemat begränsar typer, aldrig värden: inget hindrar modellen från att skicka ett namn på 3 000 tecken eller en påhittad roll. Validera därför alltid vid hanterarens ingångspunkt och returnera ett meddelande som anger vilken korrigering som behövs:
import json
@app.tool()
def create_user(name: str, email: str, role: str = "viewer") -> str:
"""Creates a new user.
Args:
name: Full name (2-100 characters)
email: Valid email address
role: Role: viewer, editor, admin (default: viewer)
Returns:
JSON with the created user details
"""
# Validation
if len(name) < 2 or len(name) > 100:
return json.dumps({"error": "Name must be between 2 and 100 characters"})
if "@" not in email or "." not in email:
return json.dumps({"error": "Invalid email address"})
valid_roles = ("viewer", "editor", "admin")
if role not in valid_roles:
return json.dumps({"error": f"Invalid role. Choices: {', '.join(valid_roles)}"})
# Creation...
return json.dumps({"success": True, "user": {"name": name, "email": email, "role": role}})
Det tredje meddelandet listar de tillåtna värdena. Modellen kan då korrigera sig själv och anropa verktyget igen, istället för att ge upp inför ett felmeddelande om “Invalid role” utan förklaring.
Polera returvärdet
Ett MCP-verktyg returnerar alltid text, men den texten kan vara strukturerad JSON, vilket modellen tolkar mycket väl. Kontrasten mellan dessa två returer sammanfattar det väsentliga:
# Bra: strukturerad, läsbar JSON
return json.dumps({
"success": True,
"user": {
"name": "Alice Dupont",
"email": "[email protected]",
"role": "editor",
},
"message": "User created successfully"
}, ensure_ascii=False)
# Dåligt: rådata som är svår att använda
return "OK:user_id=abc123:status=created"
Föredrag alltid värden som är läsbara för en människa framför interna identifierare: modellen kan omedelbart använda "Alice Dupont" i sitt svar, medan en UUID tvingar fram ett ytterligare anrop för att ta reda på vem det handlar om. Akta dig å andra sidan för uppblåsta returer – femtio fält per post fyller kontexten utan att tillföra värde. Den rätta reflexen när du skriver ett verktyg är att fråga dig själv vad modellen behöver för att berätta för användaren, och returnera endast det.
Viktiga punkter
- Dekoratorn
@app.tool()genererar automatiskt JSON Schema för parametrar - Funktionsnamnet = verktygsnamn (verb + objekt)
- Docstringen är avgörande: den guidar modellen om när och hur verktyget ska anropas
- Använd Python-typannoteringar för schemat (str, int, float, bool, list, dict)
- Validera alltid indata och returnera åtgärdbara felmeddelanden
- Returnera strukturerad JSON med människoläsbara värden