Implementacija orodij: shema JSON in ročaji
Na tej strani
Posodobljeno 2. novembra 2026 — MCP Python SDK v2. Ta tečaj zdaj sledi različici 2 paketa SDK
mcp(2.3.0 z dne 2. oktobra 2026):MCPServernadomeščaFastMCP, nastavitve prenosa se premaknejo vrun()alistreamable_http_app(), aplikacija, izpostavljena pod realnim gostiteljskim imenom, pa mora to ime navesti (transport_security). To je tudi različica, ki jo zahteva Mistral SDK: dodatni paketmistralai[agents]zahtevamcp>=2.2.0,<3.0. Viri: Kaj je novega v različici v2 · Vodnik za selitev · Namestitev in skaliranje.
Anatomija orodja MCP
Orodje MCP je videti kot funkcija Python, vendar z vidika modela to ni. Gre za štiridelno pogodbo: ime, opis, vhodno shemo JSON in ročaj, ki izvaja logiko. Model nikoli ne vidi tvoje kode – vidi le to pogodbo. Popolnoma implementirano orodje, ki je slabo opisano, nikoli ne bo klicano ali pa bo klicano ob napačnem času. Kakovost pogodbe torej določa učinkovitost strežnika veliko bolj kot kakovost same implementacije.
Kaj dekorator zgradi zate
MCPServer to pogodbo samodejno zgradi na podlagi podpisa tvoje funkcije in niza dokumentacije (docstring). Napišeš standardni 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
...
Model pa prejme tole:
{
"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"]
}
}
Oba bloka primerjaj vrstico za vrstico: vsaka anotacija tipa postane tip JSON, vsaka privzeta vrednost postane polje default, vsaka vrstica v razdelku Args postane opis parametra, edini argument brez privzete vrednosti pa konča v required. Z drugimi besedami: vse, kar izpustiš iz niza dokumentacije, iz pogodbe popolnoma izgine.
Poimenovanje in nato opisovanje
Ime orodja je ime funkcije in model ga uporabi kot prvi namig. Glagol, ki označuje dejanje, ki mu sledi jasen predmet, ne pušča prostora za dvoumnost, medtem ko splošno ali tehnično ime modela prisili v ugibanje:
# Dobro: glagol dejanja + jasen predmet
@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: ...
# Slabo: nejasno, dvoumno, tehnično
@app.tool()
def process(data: str) -> str: ... # Preveč nejasno
@app.tool()
def handle_request(req: str) -> str: ... # Za LLM nerazumljivo
@app.tool()
def db_query(sql: str) -> str: ... # Preveč tehnično
Niz dokumentacije nato prevzame vajeti in predstavlja najpomembnejši del celotnega tvojega strežnika. Odgovoriti mora na tri vprašanja v tem vrstnem redu: kdaj uporabiti to orodje, katere parametre navesti z njihovo obliko in omejitvami ter kaj pričakovati kot rezultat. Naslednji primer prikazuje, kako to izgleda v praksi:
@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
"""
...
Odstavek, ki sledi prvi vrstici, je tisto, kar amaterskim strežnikom najpogosteje manjka. Brez njega model ve, kaj orodje počne, ne pa tudi, v katerem položaju naj ga sproži. Primer datuma ISO 8601 ti bo prihranil na desetine klicev z vnosi, kot je "April 15 at 7:30 PM".
Tipi, asinhroni ročaji in preverjanje veljavnosti
MCPServer prevede običajne anotacije Python v njihove ekvivalente v shemi JSON.
| Python | Shema JSON | Primer |
|---|---|---|
str | string | "text" |
int | integer | 42 |
float | number | 3.14 |
bool | boolean | true |
list[str] | array tipa string | ["a", "b"] |
dict | object | {"key": "val"} |
Optional[str] | string (lahko ničelna) | "text" ali null |
Takoj ko orodje stopi izven svojega procesa – klic omrežja, poizvedba v bazo podatkov, branje oddaljene datoteke – ga razglasi za async. Sinhroni ročaj, ki čaka na odgovor HTTP, blokira celoten strežnik in s tem tudi vse tvoje druge uporabnike:
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
Shema JSON omejuje tipe, nikoli vrednosti: nič ne preprečuje modelu, da bi poslal ime z 3000 znaki ali izmišljeno vlogo. Zato vedno preveri veljavnost na vstopni točki ročaja in vrni sporočilo, ki kaže na potreben popravek:
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}})
Tretje sporočilo našteje dovoljene vrednosti. Model se lahko nato popravi in ponovno pokliče orodje, namesto da bi obupal pred napako „Neveljavna vloga” brez razlage.
Izpopolnjevanje povratne vrednosti
Orodje MCP vedno vrne besedilo, vendar je to besedilo lahko strukturiran JSON, ki ga model zelo dobro razume. Kontrast med tema dvema vrnjenima vrednostma povzema bistvo:
# Dobro: strukturiran, berljiv JSON
return json.dumps({
"success": True,
"user": {
"name": "Alice Dupont",
"email": "[email protected]",
"role": "editor",
},
"message": "User created successfully"
}, ensure_ascii=False)
# Slabo: surovi podatki, ki jih je težko uporabiti
return "OK:user_id=abc123:status=created"
Vedno raje izberi vrednosti, berljive za človeka, namesto notranjih identifikatorjev: model lahko "Alice Dupont" takoj uporabi v svojem odgovoru, medtem ko UUID zahteva dodaten klic, da ugotovi, o kom govori. Po drugi strani se pazi preobsežnih vrnjenih vrednosti – petdeset polj na zapis zapolni kontekst, ne da bi dodalo vrednost. Pravi refleks pri pisanju orodja je, da se vprašaš, kaj bo model potreboval, da pove uporabniku, in vrneš samo to.
Ključne ugotovitve
- Dekorator
@app.tool()samodejno ustvari shemo JSON za parametre - Ime funkcije = ime orodja (glagol + predmet)
- Niz dokumentacije je ključen: vodi model pri tem, kdaj in kako poklicati orodje
- Uporabi anotacije tipov Python za shemo (str, int, float, bool, list, dict)
- Vedno preveri veljavnost vhodov in vrni napake, ki omogočajo ukrepanje
- Vrni strukturiran JSON z vrednostmi, berljivimi za človeka