Implementēšana: JSON shēma un apstrādātāji
Šajā lapā
Atjaunināts 2026. gada 2. novembrī — MCP Python SDK v2. Šis kurss tagad seko
mcpSDK 2. versijai (2.3.0 versija, sākot no 2026. gada 2. oktobra):MCPServeraizstājFastMCP, transporta iestatījumi tiek pārvietoti uzrun()vaistreamable_http_app(), un lietojumprogrammai, kas eksponēta zem reāla resursdatora nosaukuma, ir jādeklarē šis nosaukums (transport_security). Tā ir arī versija, ko pieprasa Mistral SDK: papildinājumsmistralai[agents]prasamcp>=2.2.0,<3.0. Avoti: Kas jauns v2 · Migrācijas ceļvedis · Izvietošana un mērogošana.
MCP rīka uzbūve
MCP rīks izskatās kā Python funkcija, bet modeļa skatījumā tas tāds nav. Tas ir četru daļu līgums: nosaukums, apraksts, JSON ievades shēma un apstrādātājs, kas izpilda loģiku. Models nekad neredz tavu kodu — tas redz tikai šo līgumu. Ideāli implementēts rīks, kas ir slikti aprakstīts, nekad netiks izsaukts vai tiks izsaukts nepareizajā brīdī. Tāpēc līguma kvalitāte nosaka servera efektivitāti daudz vairāk nekā implementācijas kvalitāte.
Ko dekors tev uzbūvē
MCPServer automātiski uzbūvē šo līgumu, balstoties uz tavas funkcijas signatūru un dokumentācijas virkni (docstring). Tu raksti standarta Python kodu:
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
...
Un models saņem šo:
{
"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"]
}
}
Salīdzini abus blokus rindu pa rundai: katrs tipa anotācija kļūst par JSON tipu, katra noklusējuma vērtība kļūst par lauku default, katra rinda sadaļā Args kļūst par parametra aprakstu, un vienīgais arguments bez noklusējuma vērtības nonāk sadaļā required. Citiem vārdiem sakot, viss, ko tu izlaidi dokumentācijas virknē, pilnībā pazūd no līguma.
Nosaukums un pēc tam apraksts
Rīka nosaukums ir funkcijas nosaukums, un models to izmanto kā savu pirmo pavedienu. Darbības darbības vārds, kam seko skaidrs objekts, neatstāj nekādu neskaidrību, savukārt vispārīgs vai tehnisks nosaukums liek modelam minēt:
# Labi: darbības vārds + skaidrs objekts
@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: ...
# Slikti: neskaidrs, divdomīgs, tehnisks
@app.tool()
def process(data: str) -> str: ... # Pārāk neskaidrs
@app.tool()
def handle_request(req: str) -> str: ... # LLM nesaprotams
@app.tool()
def db_query(sql: str) -> str: ... # Pārāk tehnisks
Dokumentācijas virkne (docstring) tad pārņem vadību un veido vissvarīgāko visu tava servera daļu. Tai ir jāatbild uz trim jautājumiem šādā secībā: kad izmantot šo rīku, kurus parametrus norādīt kopā ar to formātu un ierobežojumiem, un ko sagaidīt atbildē. Tālāk redzamais piemērs parāda, kā tas izskatās reālā situācijā:
@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
"""
...
Rindkopa, kas seko pirmajai rindai, ir tas, ko amatieru serveriem visbiežāk trūkst. Bez tās models zina, ko rīks dara, bet nezina, kurā situācijā to aktivizēt. Un ISO 8601 datuma piemērs ietaupīs tev desmitiem izsaukumu ar formātu „15. aprīlis plkst. 19:30”.
Tipi, asinhronie apstrādātāji un validācija
MCPServer pārvērš parastās Python anotācijas to JSON shēmas ekvivalentos.
| Python | JSON shēma | Piemērs |
|---|---|---|
str | string | "teksts" |
int | integer | 42 |
float | number | 3.14 |
bool | boolean | true |
list[str] | array no string | ["a", "b"] |
dict | object | {"atslēga": "vērtība"} |
Optional[str] | string (nullable) | "teksts" vai null |
Tiklīdz rīks iziet ārpus sava procesa — tīkla zvans, datubāzes vaicājums, attālināta faila lasīšana — deklarē to kā async. Sinhrons apstrādātājs, kas gaida HTTP atbildi, bloķē visu serveri un līdz ar to arī pārējos lietotājus:
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 shēma ierobežo tipus, nevis vērtības: nekas neliedz modelam nosūtīt 3000 zīmju garu nosaukumu vai izdomātu lomu. Tāpēc vienmēr validē ievadi apstrādātāja sākumpunktā un atgriez ziņojumu, kas norāda nepieciešamo labojumu:
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}})
Trešais ziņojums uzskaita atļautās vērtības. Models tad var sevi labot un atkārtoti izsaukt rīku, tā vietā, lai padotos priekšā kļūdai „Nederīga loma” bez paskaidrojuma.
Atgrieztās vērtības slīpēšana
MCP rīks vienmēr atgriež tekstu, taču šis teksts var būt strukturēts JSON, ko models interpretē ļoti labi. Kontrasts starp šiem diviem atgriešanas veidiem apkopo būtisko:
# Labi: strukturēts, lasāms JSON
return json.dumps({
"success": True,
"user": {
"name": "Alice Dupont",
"email": "[email protected]",
"role": "editor",
},
"message": "User created successfully"
}, ensure_ascii=False)
# Slikti: neapstrādāti dati, kurus grūti izmantot
return "OK:user_id=abc123:status=created"
Vienmēr dod priekšroku cilvēkam lasāmām vērtībām, nevis iekšējiem identifikatoriem: models var nekavējoties izmantot „Alice Dupont” savā atbildē, savukārt UUID liek veikt papildu izsaukumu, lai noskaidrotu, par ko ir runa. Turpretī uzmanies no pārpildītām atbildēm — piecdesmit lauki uz ierakstu piepilda kontekstu, nepievienojot vērtību. Pareizā pieeja, rakstot rīku, ir pajautāt sev, kas modelam būs nepieciešams, lai pastāstītu lietotājam, un atgriezt tikai to.
Galvenās atziņas
- Dekors
@app.tool()automātiski ģenerē parametru JSON shēmu - Funkcijas nosaukums = rīka nosaukums (darbības vārds + objekts)
- Dokumentācijas virkne (docstring) ir izšķiroša: tā vada modeli, kad un kā izsaukt rīku
- Izmanto Python tipa anotācijas shēmai (str, int, float, bool, list, dict)
- Vienmēr validē ievadi un atgriez izpildāmas kļūdas
- Atgriez strukturētu JSON ar cilvēkam lasāmām vērtībām