Implementácia nástrojov: JSON Schema a obslužné rutiny
Na tejto strane
Aktualizované 2. novembra 2026 — MCP Python SDK v2. Tento kurz teraz nasleduje verziu 2 SDK
mcp(2.3.0 k 2. októbru 2026):MCPServernahrádzaFastMCP, nastavenia transportu sa presúvajú dorun()alebostreamable_http_app()a aplikácia vystavená pod skutočným hostname musí tento hostname deklarovať (transport_security). Toto je tiež verzia požadovaná Mistral SDK: extra balíkmistralai[agents]vyžadujemcp>=2.2.0,<3.0. Zdroje: Čo je nové vo v2 · Sprievodca migráciou · Nasadenie a škálovanie.
Anatómia nástroja MCP
Nástroj MCP vyzerá ako funkcia v Pythone, ale z pohľadu modelu ňou nie je. Je to zmluva skladajúca sa zo štyroch častí: názov, popis, vstupná schéma JSON a obslužná rutina (handler), ktorá vykonáva logiku. Model nikdy nevidí tvoj kód – vidí iba túto zmluvu. Dokonale implementovaný nástroj, ktorý je však zle popísaný, sa nikdy nespustí, alebo sa spustí v nesprávny čas. Kvalita zmluvy preto určuje efektivitu servera oveľa viac než kvalita samotnej implementácie.
Čo pre teba vytvorí dekorátor
MCPServer zostaví túto zmluvu automaticky na základe signatúry tvojej funkcie a jej docstringu. Píšeš štandardný 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
...
A model dostane toto:
{
"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"]
}
}
Porovnaj si tieto dva bloky riadok po riadku: každá typová anotácia sa stane typom JSON, každá predvolená hodnota sa stane poľom default, každý riadok v sekcii Args sa stane popisom parametra a jediný argument bez predvolenej hodnoty sa ocitne v poli required. Inými slovami, všetko, čo vynecháš z docstringu, úplne zmizne zo zmluvy.
Pomenovanie a následne popis
Názov nástroja je názov funkcie a model ho používa ako prvú nápovedu. Sloveso vyjadrujúce akciu nasledované jasným objektom nezanecháva žiadnu nejasnosť, zatiaľ čo všeobecný alebo technický názov núti model hádať:
# Dobré: sloveso vyjadrujúce akciu + jasný 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: ...
# Zlé: vágne, nejednoznačné, technické
@app.tool()
def process(data: str) -> str: ... # Príliš vágne
@app.tool()
def handle_request(req: str) -> str: ... # Pre LLM nepochopiteľné
@app.tool()
def db_query(sql: str) -> str: ... # Príliš technické
Docstring potom preberá štafetu a predstavuje najdôležitejšiu časť celého tvojho servera. Musí odpovedať na tri otázky v tomto poradí: kedy použiť tento nástroj, aké parametre poskytnúť vrátane ich formátu a obmedzení a čo očakávať späť. Nasledujúci príklad ukazuje, ako to vyzerá v reálnom prípade:
@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
"""
...
Odsek nasledujúci hneď po prvom riadku je to, čo amatérskym serverom najčastejšie chýba. Bez neho model vie, čo nástroj robí, ale nevie, v akej situácii ho má spustiť. A príklad dátumu vo formáte ISO 8601 ti ušetrí desiatky volaní s údajmi typu "15. apríla o 19:30".
Typy, asynchrónne handlery a validácia
MCPServer prekladá bežné Python anotácie do ich ekvivalentov v JSON Schema.
| Python | JSON Schema | Príklad |
|---|---|---|
str | string | "text" |
int | integer | 42 |
float | number | 3.14 |
bool | boolean | true |
list[str] | array typu string | ["a", "b"] |
dict | object | {"key": "val"} |
Optional[str] | string (nullable) | "text" alebo null |
Akonáhle nástroj vykročí mimo svoj proces – volanie siete, dopyt do databázy, čítanie vzdialeného súboru – deklaruj ho ako async. Synchronný handler čakajúci na HTTP odpoveď zablokuje celý server a spolu s ním aj ostatných používateľov:
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
Schéma JSON obmedzuje typy, nikdy nie hodnoty: nič nebráni modelu poslať meno s 3 000 znakmi alebo vymyslenú rolu. Preto vždy validuj vstupy hneď na začiatku handlera a vráť správu označujúcu potrebnú opravu:
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}})
Tretia správa vymenúva povolené hodnoty. Model sa tak môže opraviť a nástroj zavolať znova, namiesto toho, aby to vzdal tvárou v tvár chybe „Neplatná rola“ bez vysvetlenia.
Vylepšenie návratovej hodnoty
Nástroj MCP vždy vracia text, ale tento text môže byť štruktúrované JSON, ktoré model interpretuje veľmi dobre. Kontrast medzi týmito dvoma návratmi zhrňuje to podstatné:
# Dobré: štruktúrované, čitateľné JSON
return json.dumps({
"success": True,
"user": {
"name": "Alice Dupont",
"email": "[email protected]",
"role": "editor",
},
"message": "User created successfully"
}, ensure_ascii=False)
# Zlé: surové dáta, ktoré sa ťažko používajú
return "OK:user_id=abc123:status=created"
Vždy uprednostni hodnoty čitateľné pre človeka pred internými identifikátormi: model môže okamžite použiť "Alice Dupont" vo svojej odpovedi, zatiaľ čo UUID si vyžiada ďalšie volanie, aby zistil, o koho ide. Naopak, pozor na nafúknuté návraty – päťdesiat polí na záznam zaplní kontext bez pridania hodnoty. Správnym reflexom pri písaní nástroja je opýtať sa sám seba, čo bude model potrebovať, aby to povedal používateľovi, a vrátiť iba toto.
Kľúčové poznatky
- Dekorátor
@app.tool()automaticky generuje JSON Schema pre parametre - Názov funkcie = názov nástroja (sloveso + objekt)
- Docstring je kľúčový: vedie model, kedy a ako nástroj zavolať
- Používaj Python typové anotácie pre schému (str, int, float, bool, list, dict)
- Vždy validuj vstupy a vráť chyby, ktoré umožňujú akciu
- Vracaj štruktúrované JSON s hodnotami čitateľnými pre človeka