Implementierung von Tools: JSON-Schema und Handler
Auf dieser Seite
Aktualisiert am 2. November 2026 — MCP Python SDK v2. Dieser Kurs folgt nun Version 2 des
mcpSDKs (Stand 2.3.0 vom 2. Oktober 2026):MCPServerersetztFastMCP, Transport-Einstellungen werden inrun()oderstreamable_http_app()verlegt, und eine Anwendung, die unter einem echten Hostnamen ausgesetzt ist, muss diesen Hostnamen deklarieren (transport_security). Dies ist auch die Version, die vom Mistral SDK erforderlich ist: Diemistralai[agents]-Zusatzfunktion benötigtmcp>=2.2.0,<3.0. Quellen: Neuigkeiten in v2 · Migrationsanleitung · Bereitstellen und skalieren.
Die Anatomie eines MCP-Tools
Ein MCP-Tool sieht aus wie eine Python-Funktion, ist es aber aus Sicht des Modells nicht. Es handelt sich um einen vierseitigen Vertrag: einen Namen, eine Beschreibung, ein JSON-Eingabeschema und einen Handler, der die Logik ausführt. Das Modell sieht Ihren Code nie – es sieht nur diesen Vertrag. Ein perfekt implementiertes Tool, das schlecht beschrieben ist, wird niemals aufgerufen oder wird zum falschen Zeitpunkt aufgerufen. Daher bestimmt die Qualität des Vertrags die Effektivität des Servers weitaus stärker als die Qualität der Implementierung.
Was der Dekorator für Sie aufbaut
MCPServer baut diesen Vertrag automatisch aus Ihrem Funktions-Signatur und Ihrer Docstring auf. Sie schreiben Standard-Python:
from mcp.server.mcpserver import MCPServer
app = MCPServer("Mein Server")
@app.tool()
def search_documents(
query: str,
max_results: int = 10,
language: str = "fr",
include_archived: bool = False,
) -> str:
"""Sucht Dokumente in der Wissensdatenbank.
Args:
query: Suchbegriffe (2–500 Zeichen)
max_results: Maximale Anzahl der Ergebnisse (1–100, Standard: 10)
language: ISO 639-1-Sprachcode (Standard: fr)
include_archived: Archivdokumente einschließen (Standard: false)
Returns:
JSON mit der Liste der gefundenen Dokumente und der Gesamtzahl
"""
# Suchlogik
...
Und das Modell erhält dies:
{
"name": "search_documents",
"description": "Sucht Dokumente in der Wissensdatenbank.",
"inputSchema": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "Suchbegriffe (2–500 Zeichen)"
},
"max_results": {
"type": "integer",
"description": "Maximale Anzahl der Ergebnisse (1–100, Standard: 10)",
"default": 10
},
"language": {
"type": "string",
"description": "ISO 639-1-Sprachcode (Standard: fr)",
"default": "fr"
},
"include_archived": {
"type": "boolean",
"description": "Archivdokumente einschließen (Standard: false)",
"default": false
}
},
"required": ["query"]
}
}
Vergleichen Sie die beiden Blöcke Zeile für Zeile: Jede Typ-Annotierung wird zu einem JSON-Typ, jeder Standardwert wird zu einem default-Feld, jede Zeile im Args-Abschnitt wird zu einer Parameterbeschreibung, und das einzige Argument ohne Standardwert landet in required. Mit anderen Worten: Alles, was Sie aus der Docstring weglassen, verschwindet vollständig aus dem Vertrag.
Benennen, dann Beschreiben
Der Toolname ist der Funktionsname, und das Modell nutzt ihn als ersten Hinweis. Ein Tätigkeitsverb gefolgt von einem klaren Objekt lässt keine Mehrdeutigkeit zu, wohingegen ein generischer oder technischer Name das Modell zwingt, zu raten:
# Gut: Tätigkeitsverb + klares 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: ...
# Schlecht: vage, mehrdeutig, technisch
@app.tool()
def process(data: str) -> str: ... # Zu vage
@app.tool()
def handle_request(req: str) -> str: ... # Für LLMs unverständlich
@app.tool()
def db_query(sql: str) -> str: ... # Zu technisch
Die Docstring übernimmt dann die Führung und stellt den kritischsten Teil Ihres gesamten Servers dar. Sie muss drei Fragen in dieser Reihenfolge beantworten: wann dieses Tool verwendet werden soll, welche Parameter mit ihrem Format und ihren Einschränkungen bereitgestellt werden müssen und was als Ergebnis erwartet werden kann. Das folgende Beispiel zeigt, wie dies in einem realen Fall aussieht:
@app.tool()
def book_restaurant(
restaurant_name: str,
date: str,
party_size: int,
special_requests: str = "",
) -> str:
"""Bucht einen Tisch in einem Restaurant.
Führt eine vollständige Reservierung einschließlich
E-Mail-Bestätigung durch. Verwenden Sie dieses Tool,
wenn der Nutzer einen bestimmten Restaurantbesuch
buchen möchte.
Args:
restaurant_name: Exakter Name des Restaurants
date: Datum und Uhrzeit im ISO 8601-Format (z. B. 2026-04-15T19:30:00)
party_size: Anzahl der Gäste (1–20)
special_requests: Besondere Wünsche (Allergien, Anlass usw.)
Returns:
JSON mit der Reservierungsnummer, der Bestätigung
und den Restaurantdetails
"""
...
Der Absatz nach der ersten Zeile ist das, was Amateur-Server am häufigsten vermissen. Ohne ihn weiß das Modell, was das Tool tut, aber nicht in welcher Situation es ausgelöst werden soll. Und das ISO 8601-Datum-Beispiel wird Ihnen Dutzende von Aufrufen mit "15. April um 19:30 Uhr" ersparen.
Typen, asynchrone Handler und Validierung
MCPServer übersetzt gängige Python-Annotierungen in ihre JSON-Schema-Äquivalente.
| Python | JSON Schema | Beispiel |
|---|---|---|
str | string | "Text" |
int | integer | 42 |
float | number | 3,14 |
bool | boolean | true |
list[str] | array von string | ["a", "b"] |
dict | object | {"key": "val"} |
Optional[str] | string (nullable) | "Text" oder null |
Sobald ein Tool seinen Prozess verlässt – Netzwerkanruf, Datenbankabfrage, Lesen einer Remote-Datei – deklarieren Sie es als async. Ein synchroner Handler, der auf eine HTTP-Antwort wartet, blockiert den gesamten Server, und alle anderen Nutzer ebenfalls:
import httpx
@app.tool()
async def fetch_api_data(endpoint: str) -> str:
"""Ruft Daten von einer externen API ab.
Args:
endpoint: Der API-Endpunkt-Pfad (z. B. /users/123)
Returns:
JSON-Daten von der API
"""
async with httpx.AsyncClient() as client:
response = await client.get(f"https://api.example.com{endpoint}")
response.raise_for_status()
return response.text
Das JSON-Schema begrenzt Typen, niemals Werte: Es hindert das Modell nicht daran, einen 3.000-Zeichen-Namen oder eine erfundene Rolle zu senden. Daher validieren Sie immer am Eintrittspunkt des Handlers und geben Sie eine Nachricht zurück, die die erforderliche Korrektur angibt:
import json
@app.tool()
def create_user(name: str, email: str, role: str = "viewer") -> str:
"""Erstellt einen neuen Benutzer.
Args:
name: Vollständiger Name (2–100 Zeichen)
email: Gültige E-Mail-Adresse
role: Rolle: viewer, editor, admin (Standard: viewer)
Returns:
JSON mit den Details des erstellten Benutzers
"""
# Validierung
if len(name) < 2 or len(name) > 100:
return json.dumps({"error": "Name muss zwischen 2 und 100 Zeichen lang sein"})
if "@" not in email or "." not in email:
return json.dumps({"error": "Ungültige E-Mail-Adresse"})
valid_roles = ("viewer", "editor", "admin")
if role not in valid_roles:
return json.dumps({"error": f"Ungültige Rolle. Auswahl: {', '.join(valid_roles)}"})
# Erstellung...
return json.dumps({"success": True, "user": {"name": name, "email": email, "role": role}})
Die dritte Nachricht listet die erlaubten Werte auf. Das Modell kann sich dann korrigieren und das Tool erneut aufrufen, anstatt bei einer “Ungültige Rolle”-Fehlermeldung ohne Erklärung aufzugeben.
Verfeinerung des Rückgabewerts
Ein MCP-Tool gibt immer Text zurück, aber dieser Text kann strukturiertes JSON sein, das das Modell sehr gut interpretiert. Der Kontrast zwischen diesen beiden Rückgaben fasst das Wesentliche zusammen:
# Gut: strukturiertes, lesbares JSON
return json.dumps({
"success": True,
"user": {
"name": "Alice Dupont",
"email": "[email protected]",
"role": "editor",
},
"message": "Benutzer erfolgreich erstellt"
}, ensure_ascii=False)
# Schlecht: rohe Daten, die schwer zu verwenden sind
return "OK:user_id=abc123:status=created"
Bevorzugen Sie immer Werte, die für Menschen lesbar sind, gegenüber internen Identifikatoren: Das Modell kann "Alice Dupont" sofort in seiner Antwort verwenden, wohingegen eine UUID einen zusätzlichen Aufruf erfordert, um herauszufinden, wem es spricht. Umgekehrt: Achten Sie auf aufgeblähte Rückgaben – fünfzig Felder pro Datensatz füllen den Kontext, ohne Mehrwert zu bieten. Die richtige Reflexion beim Schreiben eines Tools besteht darin, sich zu fragen, was das Modell dem Nutzer mitteilen muss, und nur dies zurückzugeben.
Kernaussagen
- Der
@app.tool()-Dekorator generiert automatisch das JSON-Schema für Parameter - Der Funktionsname = Toolname (Verb + Objekt)
- Die Docstring ist entscheidend: Sie leitet das Modell darin, wann und wie das Tool aufgerufen wird
- Verwenden Sie Python-Typ-Annotierungen für das Schema (str, int, float, bool, list, dict)
- Validieren Sie immer Eingaben und geben Sie handlungsorientierte Fehlermeldungen zurück
- Geben Sie strukturiertes JSON mit menschenlesbaren Werten zurück