Įgyvendinami įrankiai: JSON Schema ir apdorotojai
Šiame puslapyje
Atnaujinta 2026 m. lapkričio 2 d. — MCP Python SDK v2. Šis kursas dabar remiasi 2 versija (
mcpSDK 2.3.0, pagal 2026 m. spalio 2 d. duomenis):MCPServerpakeičiaFastMCP, transporto nustatymai perkeliami įrun()arbastreamable_http_app(), o programa, eksponuojama tikru prievardu (hostname), privalo deklaruoti tą prievardą (transport_security). Tai taip pat yra versija, kurios reikalauja Mistral SDK:mistralai[agents]papildinys reikalaujamcp>=2.2.0,<3.0. Šaltiniai: Kas naujo v2 · Migracijos gidas · Diegimas ir mastelio keitimas.
MCP įrankio anatomija
MCP įrankis atrodo kaip Python funkcija, tačiau modelio požiūriu juo nėra. Tai keturių dalių sutartis: pavadinimas, aprašymas, JSON įvesties schema ir apdorotojas (handler), vykdantis logiką. Modelis niekada nemato tavo kodo – jis mato tik šią sutartį. Puikiai įgyvendintas, bet prastai aprašytas įrankis niekada nebus iškviestas arba bus iškviestas netinkamu metu. Todėl serverio efektyvumą lemia ne tiek įgyvendinimo kokybė, kiek sutarties kokybė.
Ką dekoratorius sukuria už tave
MCPServer automatiškai sukuria šią sutartį iš tavo funkcijos parašo ir dokumentacijos eilutės (docstring). Tu rašai standartinį Python kodą:
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
...
O modelis gauna tai:
{
"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"]
}
}
Palygink abu blokus eilutė po eilutės: kiekvienas tipo anotavimas tampa JSON tipu, kiekviena numatytoji reikšmė tampa lauku default, kiekviena Args skyriaus eilutė tampa parametro aprašymu, o vienintelis argumentas be numatytosios reikšmės atsiduria sąraše required. Kitaip tariant, viskas, ką praleidi dokumentacijos eilutėje, visiškai išnyksta iš sutarties.
Pavadinimas, tada aprašymas
Įrankio pavadinimas yra funkcijos pavadinimas, ir modelis jį naudoja kaip pirmąją užuominą. Veiksmažodis, po kurio eina aiškus objektas, nepalieka dviprasmybių, tuo tarpu bendras ar techninis pavadinimas verčia modelį spėlioti:
# Gerai: veiksmo veiksmažodis + aiškus objektas
@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: ...
# Blogai: neaišku, dviprasmiška, techniška
@app.tool()
def process(data: str) -> str: ... # Per daug neaišku
@app.tool()
def handle_request(req: str) -> str: ... # LLM nesuprantama
@app.tool()
def db_query(sql: str) -> str: ... # Per daug techniška
Tada į žaidimą įstoja dokumentacijos eilutė (docstring), kuri yra svarbiausia viso tavo serverio dalis. Ji turi atsakyti į tris klausimus tokia tvarka: kada naudoti šį įrankį, kokius parametrus pateikti su jų formatu ir apribojimais bei ko tikėtis grįžtant. Toliau pateiktame pavyzdyje matyti, kaip tai atrodo realiame scenarijuje:
@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
"""
...
Pastraipa, einanti iškart po pirmosios eilutės, yra tai, ko dažniausiai trūksta mėgėjiškiems serveriams. Be jos modelis žino, ką įrankis daro, bet nežino, kokioje situacijoje jį suaktyvinti. O ISO 8601 datos pavyzdys sutaupys dešimtis kvietimų su užklausomis „Balandžio 15 d. 19:30 val.“.
Tipai, asinchroniniai apdorotojai ir validavimas
MCPServer paverčia įprastas Python anotacijas jų JSON Schema ekvivalentais.
| Python | JSON Schema | Pavyzdys |
|---|---|---|
str | string | "text" |
int | integer | 42 |
float | number | 3.14 |
bool | boolean | true |
list[str] | array iš string | ["a", "b"] |
dict | object | {"key": "val"} |
Optional[str] | string (galima null) | "text" arba null |
Kai tik įrankis išeina už savo proceso ribų – tinklo užklausa, duomenų bazės užklausa, nuotolinio failo skaitymas – deklaruok jį kaip async. Sinchroninis apdorotojas, laukiantis HTTP atsakymo, užblokuoja visą serverį ir kartu visus kitus naudotojus:
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 schema riboja tipus, bet ne reikšmes: niekas neleidžia modeliui siųsti 3000 simbolių vardo arba sugalvoto vaidmens. Todėl visada validuok duomenis apdorotojo įėjimo taške ir grąžink žinutę, nurodančią, ką reikia taisyt:
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čioji žinutė išvardija leistinas reikšmes. Tuomet modelis gali pasitaisyti ir vėl iškviesti įrankį, užuot pasiduodamas prieš klaidą „Neteisingas vaidmuo“ be jokio paaiškinimo.
Grąžinamosios reikšmės tobulinimas
MCP įrankis visada grąžina tekstą, tačiau tas tekstas gali būti struktūruotas JSON, kurį modelis interpretuoja labai gerai. Kontrastas tarp šių dviejų grąžinamųjų reikšmių apibendrina esmę:
# Gerai: struktūruotas, skaitomas JSON
return json.dumps({
"success": True,
"user": {
"name": "Alice Dupont",
"email": "[email protected]",
"role": "editor",
},
"message": "User created successfully"
}, ensure_ascii=False)
# Blogai: neapdoroti duomenys, kuriuos sunku naudoti
return "OK:user_id=abc123:status=created"
Visada teik pirmenybę žmogui suprantamoms reikšmėms, o ne vidiniams identifikatoriams: modelis gali iškart panaudoti „Alice Dupont“ savo atsakyme, tuo tarpu UUID verčia atlikti papildomą užklausą, norint sužinoti, apie ką kalbama. Kita vertus, saugokis perteklinių grąžinamųjų reikšmių – penkiasdešimt laukų vienam įrašui pripildo kontekstą nepridėdami vertės. Tinkamas refleksas kuriant įrankį yra paklausti savęs, ko modeliui reikės norint pasakyti naudotojui, ir grąžinti tik tai.
Svarbiausi punktai
- Dekoratorius
@app.tool()automatiškai sugeneruoja parametrų JSON Schema - Funkcijos pavadinimas = įrankio pavadinimas (veiksmažodis + objektas)
- Docstring yra kritiškai svarbus: jis nukreipia modelį, kada ir kaip iškviesti įrankį
- Naudok Python tipo anotacijas schemai kūrti (str, int, float, bool, list, dict)
- Visada validuok įvestis ir grąžink veiksmingas klaidas
- Grąžink struktūruotą JSON su žmogui suprantamomis reikšmėmis