Eszközök megvalósítása: JSON Schema és kezelők
Ezen az oldalon
Frissítve: 2026. november 2. — MCP Python SDK v2. Ez a tanfolyam az
mcpSDK 2-es verzióját követi (2026. október 2-i állapot szerint 2.3.0): azMCPServerleváltja aFastMCP-t, a transzportbeállítások arun()vagy astreamable_http_app()függvényekbe kerültek, és egy valós hosztnév alatt elérhető alkalmazásnak deklarálnia kell ezt a hosztnevet (transport_security). Ez az a verzió, amelyet a Mistral SDK is megkövetel: amistralai[agents]extra függőségéhezmcp>=2.2.0,<3.0szükséges. Források: Újdonságok a v2-ben · Migrációs útmutató · Telepítés és méretezés.
Egy MCP eszköz felépítése
Egy MCP eszköz Python függvénynek tűnik, de a modell szemszögéből nem az. Ez egy négyrészes szerződés: egy név, egy leírás, egy JSON bemeneti séma és egy logikát végrehajtó kezelő. A modell sosem látja a kódodat – csak ezt a szerződést ismeri. Egy tökéletesen megvalósított, de rosszul leírt eszközt sosem hívnak meg, vagy rossz időpontban aktiválódik. Ezért a szerver hatékonyságát sokkal inkább a szerződés minősége határozza meg, mint a megvalósításé.
Mit épít fel neked a dekorátor?
Az MCPServer automatikusan felépíti ezt a szerződést a függvény aláírása és a docstringje alapján. Te szabványos Pythont írsz:
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
...
A modell pedig ezt kapja:
{
"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"]
}
}
Hasonlítsd össze soronként a két blokkot: minden típusannotáció JSON típussá válik, minden alapértelmezett érték egy default mezővé, az Args szakasz minden sora egy paraméterleírássá, és csak az az argumentum kerül a required listába, amelynek nincs alapértelmezett értéke. Más szóval: amit kihagysz a docstringből, az teljesen eltűnik a szerződésből.
Először a elnevezés, aztán a leírás
Az eszköz neve megegyezik a függvény nevével, és a modell ezt használja első támpontként. Egy cselekvést kifejező ige, amelyet egy egyértelmű tárgy követ, nem hagy teret a félreértésnek, míg egy általános vagy technikai név találgatásra kényszeríti a modellt:
# Jó: cselekvőige + egyértelmű tárgy
@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: ...
# Rossz: bizonytalan, kétértelmű, technikai
@app.tool()
def process(data: str) -> str: ... # Túl bizonytalan
@app.tool()
def handle_request(req: str) -> str: ... # Az LLM számára érthetetlen
@app.tool()
def db_query(sql: str) -> str: ... # Túl technikai
Ezután jön a docstring, amely a teljes szervered legkritikusabb eleme. Három kérdésre kell választ adnia, ebben a sorrendben: mikor használd ezt az eszközt, milyen paramétereket adj meg (formátummal és korlátozásokkal), és mit várj visszaként. A következő példa bemutatja, hogyan néz ez ki a valóságban:
@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
"""
...
Az első sort követő bekezdés az, ami a kezdő szerverekből leggyakrabban hiányzik. Enélkül a modell tudja, mit csinál az eszköz, de azt nem, milyen helyzetben kellene aktiválnia. Az ISO 8601 dátumpélda pedig tucatnyi olyan hívást spórol meg neked, ahol a modell "April 15 at 7:30 PM" formátumban küldene dátumot.
Típusok, aszinkron kezelők és validálás
Az MCPServer lefordítja a gyakori Python annotációkat a megfelelő JSON Schema típusokra.
| Python | JSON Schema | Példa |
|---|---|---|
str | string | "text" |
int | integer | 42 |
float | number | 3.14 |
bool | boolean | true |
list[str] | array of string | ["a", "b"] |
dict | object | {"key": "val"} |
Optional[str] | string (nullable) | "text" vagy null |
Amint egy eszköz kilép a saját folyamatából – hálózati hívás, adatbázis-lekérdezés, távoli fájl olvasása –, deklarálnod kell async-ként. Egy szinkron kezelő, amely HTTP-válaszra vár, blokkolja az egész szervert, és vele együtt a többi felhasználót is:
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
A JSON séma csak a típusokat korlátozza, az értékeket nem: semmi sem akadályozza meg a modellt abban, hogy 3000 karakteres nevet vagy kitalált szerepkört küldjön. Ezért mindig validálj a kezelő belépési pontjánál, és adj vissza egy üzenetet, amely jelzi a szükséges javítást:
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}})
A harmadik üzenet felsorolja az engedélyezett értékeket. Így a modell kijavíthatja magát, és újra meghívhatja az eszközt, ahelyett, hogy feladná a magyarázat nélküli „Érvénytelen szerepkör“ hiba miatt.
A visszatérési érték csiszolása
Egy MCP eszköz mindig szöveget ad vissza, de ez a szöveg lehet strukturált JSON is, amelyet a modell nagyon jól értelmez. E két visszatérési érték közötti kontraszt összefoglalja a lényeget:
# Jó: strukturált, olvasható JSON
return json.dumps({
"success": True,
"user": {
"name": "Alice Dupont",
"email": "[email protected]",
"role": "editor",
},
"message": "User created successfully"
}, ensure_ascii=False)
# Rossz: nyers, nehezen használható adat
return "OK:user_id=abc123:status=created"
Mindig részesítsd előnyben az ember által olvasható értékeket a belső azonosítókkal szemben: a modell azonnal felhasználhatja a "Alice Dupont" nevet a válaszában, míg egy UUID miatt további hívásra lenne szükség, hogy kiderítse, kiről van szó. Ezzel szemben óvakodj a túlbővített válaszoktól – rekordonként ötven mező megtölti a kontextust anélkül, hogy értéket adna hozzá. A helyes reflex egy eszköz írásakor, ha felteszed magadnak a kérdést: mire lesz szüksége a modellnek, hogy tájékoztassa a felhasználót, és csak azt add vissza.
Főbb megállapítások
- Az
@app.tool()dekorátor automatikusan generálja a paraméterek JSON Schema leírását - A függvény neve = az eszköz neve (ige + tárgy)
- A docstring kritikus fontosságú: ez útmutatást ad a modellnek, mikor és hogyan hívja meg az eszközt
- Használj Python típusannotációkat a sémához (str, int, float, bool, list, dict)
- Mindig validáld a bemeneteket, és adj vissza cselekvésre ösztönző hibákat
- Strukturált JSON-t adj vissza, ember által olvasható értékekkel