Tööriistade rakendamine: JSON Schema ja käitlejad
Sellel lehel
Uuendatud 2. novembril 2026 — MCP Python SDK v2. See kursus järgib nüüd
mcpSDK versiooni 2 (seisuga 2. oktoober 2026 on see 2.3.0):MCPServerasendabFastMCP-i, transpordi seaded liiguvad meetoditesserun()võistreamable_http_app()ning reaalse hostinime all avaldatud rakendus peab selle hostinime deklareerima (transport_security). See on ka versioon, mida nõuab Mistral SDK: lisapakettmistralai[agents]eeldabmcp>=2.2.0,<3.0. Allikad: Mis on uut v2-s · Migratsioonijuhend · Kasutuselevõtt ja skaleerimine.
MCP tööriista anatoomia
MCP tööriist näeb välja nagu Pythoni funktsioon, kuid mudeli seisukohalt see seda ei ole. See on neljaosaline leping: nimi, kirjeldus, JSON-i sisendskeem ja käitleja, mis viib loogika täide. Mudel ei näe kunagi sinu koodi – ta näeb ainult seda lepingut. Ideaalselt teostatud, kuid halvasti kirjeldatud tööriista ei kutsuta kunagi välja või tehakse seda valel ajal. Seetõttu määrab lepingu kvaliteet serveri tõhususe palju rohkem kui rakenduse kvaliteet.
Mida dekorator sinu eest teeb
MCPServer loob selle lepingu automaatselt sinu funktsiooni signatuuri ja dokumendistringi põhjal. Sa kirjutad tavalist Pythonit:
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
...
Ja mudel saab vastu selle:
{
"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"]
}
}
Võrdle neid kahte plokki rida-realt: iga tüübimärge muutub JSON-i tüübiks, iga vaikimisi väärtus muutub väljaks default, iga rida sektsioonis Args muutub parameetri kirjelduseks ja ainus argument ilma vaikimisi väärtuseta satub loendisse required. Teisisõnu, kõik, mida sa dokumendistringist välja jätad, kaob lepingust täielikult.
Nime andmine ja seejärel kirjeldamine
Tööriista nimi on funktsiooni nimi ja mudel kasutab seda esmase vihjena. Tegevust väljendav tegusõna koos selge objektiga jätab ruumi tõlgendustele, samas kui üldine või tehniline nimi sunnib mudelit arvama:
# Hea: tegevust väljendav tegusõna + selge 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: ...
# Halb: ebamäärane, mitmetähenduslik, tehniline
@app.tool()
def process(data: str) -> str: ... # Liiga ebamäärane
@app.tool()
def handle_request(req: str) -> str: ... # LLM-ile arusaamatu
@app.tool()
def db_query(sql: str) -> str: ... # Liiga tehniline
Dokumendistring võtab seejärel ohjad enda kätte ja moodustab kogu sinu serveri kriitilisima osa. See peab vastama kolmele küsimusele järgmises järjekorras: millal seda tööriista kasutada, milliseid parameetreid koos nende vormingu ja piirangutega esitada ning mida vastuseks oodata. Järgnev näide illustreerib, kuidas see reaalses olukorras välja näeb:
@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
"""
...
Lõik, mis järgneb esimesele reale, on see, mida amatöörserveritel kõige sagedamini napib. Ilma selleta teab mudel, mida tööriist teeb, kuid mitte millises olukorras seda käivitada. Ja ISO 8601 kuupäeva näide säästab sind kümnetest kõnedest vormingus „15. aprill kell 19.30“.
Tüübid, asünkroonsed käitlejad ja valideerimine
MCPServer tõlgib levinud Pythoni annotatsioonid nende JSON Schema ekvivalentideks.
| Python | JSON Schema | Näide |
|---|---|---|
str | string | "tekst" |
int | integer | 42 |
float | number | 3.14 |
bool | boolean | true |
list[str] | array tüübist string | ["a", "b"] |
dict | object | {"võti": "väärtus"} |
Optional[str] | string (võib olla null) | "tekst" või null |
Niipea kui tööriist astub oma protsessist välja – võrgukõne, andmebaasipäring, kaugfaili lugemine – deklareeri see async-ina. Sünkroonne käitleja, mis ootab HTTP vastust, blokeerib kogu serveri ja koos sellega ka teised kasutajad:
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 skeem piirab tüüpe, mitte kunagi väärtusi: miski ei takista mudelit saatmast 3000-märgilist nime või väljamõeldud rolli. Seetõttu valideeri alati sisendit käitleja sisenemispunktis ja tagasta sõnum, mis näitab vajalikku parandust:
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
"""
# Valideerimine
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)}"})
# Loome...
return json.dumps({"success": True, "user": {"name": name, "email": email, "role": role}})
Kolmas sõnum loetleb lubatud väärtused. Mudel saab seejärel ennast parandada ja tööriista uuesti välja kutsuda, selle asemel et loobuda ebaselge vea „Invalid role“ ees ilma selgituseta.
Tagastusväärtuse lihvimine
MCP tööriist tagastab alati teksti, kuid see tekst võib olla struktureeritud JSON, mida mudel tõlgendab väga hästi. Kontrast nende kahe tagastuse vahel võtab kokku olulise:
# Hea: struktureeritud, loetav JSON
return json.dumps({
"success": True,
"user": {
"name": "Alice Dupont",
"email": "[email protected]",
"role": "editor",
},
"message": "User created successfully"
}, ensure_ascii=False)
# Halb: toored andmed, mida on raske kasutada
return "OK:user_id=abc123:status=created"
Eelista alati inimesele loetavaid väärtusi sisemiste identifikaatorite asemel: mudel saab kohe kasutada nime „Alice Dupont“ oma vastuses, samas kui UUID sunnib tegema täiendava kõne, et teada saada, kellest juttu on. Samas hoia tagasi ülepaisunud tagastustest – viiskümmend välja kirje kohta täidavad konteksti väärtust lisamata. Õige refleks tööriista kirjutamisel on küsida endalt, mida mudel vajab kasutajale ütlemiseks, ja tagastada ainult seda.
Peamised punktid
- Dekorator
@app.tool()genereerib parameetrite jaoks automaatselt JSON Schema - Funktsiooni nimi = tööriista nimi (tegevust väljendav tegusõna + objekt)
- Dokumendistring on kriitilise tähtsusega: see juhendab mudelit, millal ja kuidas tööriista kutsuda
- Kasuta skeemi jaoks Pythoni tüübimärkeid (str, int, float, bool, list, dict)
- Valideeri alati sisendeid ja tagasta tegevust võimaldavad veateated
- Tagasta struktureeritud JSON inimesele loetavate väärtustega