Implementacija alata: JSON Schema i rukovatelji
Na ovoj stranici
Ažurirano 2. studenoga 2026. — MCP Python SDK v2. Ovaj tečaj sada prati verziju 2 SDK-a
mcp(2.3.0 od 2. listopada 2026.):MCPServerzamjenjujeFastMCP, postavke transporta prelaze urun()ilistreamable_http_app(), a aplikacija izložena pod stvarnim imenom hosta mora deklarirati to ime hosta (transport_security). Ovo je također verzija koju zahtijeva Mistral SDK: dodatakmistralai[agents]zahtijevamcp>=2.2.0,<3.0. Izvori: Što je novo u v2 · Vodič za migraciju · Implementacija i skaliranje.
Anatomija MCP alata
MCP alat izgleda kao Python funkcija, ali s perspektive modela to nije. To je ugovor od četiri dijela: naziv, opis, JSON shema ulaza i rukovatelj koji izvršava logiku. Model nikada ne vidi tvoj kod — vidi samo taj ugovor. Savršeno implementiran alat koji je loše opisan nikada neće biti pozvan ili će biti pozvan u pogrešno vrijeme. Stoga kvaliteta ugovora određuje učinkovitost poslužitelja daleko više nego kvaliteta same implementacije.
Što dekorator gradi za tebe
MCPServer automatski gradi ovaj ugovor na temelju potpisa tvoje funkcije i docstringa. Piš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
...
A model prima ovo:
{
"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"]
}
}
Usporedi ova dva bloka redak po redak: svaka anotacija tipa postaje JSON tip, svaka zadana vrijednost postaje polje default, svaki redak u odjeljku Args postaje opis parametra, a jedini argument bez zadane vrijednosti završava u required. Drugim riječima, sve što izostaviš iz docstringa potpuno nestaje iz ugovora.
Imenovanje, zatim opisivanje
Naziv alata je naziv funkcije i model ga koristi kao prvu indiciju. Glagol koji označava radnju praćen jasnim objektom ne ostavlja mjesta dvosmislenosti, dok općenit ili tehnički naziv prisiljava model na nagađanje:
# Dobro: glagol radnje + jasan 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: ...
# Loše: neodređeno, dvosmisleno, tehnički
@app.tool()
def process(data: str) -> str: ... # Previše neodređeno
@app.tool()
def handle_request(req: str) -> str: ... # Neshvatljivo za LLM
@app.tool()
def db_query(sql: str) -> str: ... # Previše tehnički
Docstring zatim preuzima ulogu i predstavlja najkritičniji dio cijelog tvog poslužitelja. Mora odgovoriti na tri pitanja ovim redoslijedom: kada koristiti ovaj alat, koje parametre dostaviti s njihovim formatom i ograničenjima te što očekivati kao povratnu vrijednost. Sljedeći primjer pokazuje kako to izgleda u stvarnom slučaju:
@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
"""
...
Odlomak koji slijedi nakon prvog retka ono je što amaterskim poslužiteljima najčešće nedostaje. Bez njega model zna što alat radi, ali ne i u kojoj situaciji ga treba pokrenuti. A primjer datuma u ISO 8601 formatu uštedjet će ti desetke poziva s porukama poput „15. travnja u 19:30“.
Tipovi, asinkroni rukovatelji i validacija
MCPServer prevodi uobičajene Python anotacije u njihove ekvivalente u JSON Shemi.
| Python | JSON Schema | Primjer |
|---|---|---|
str | string | "text" |
int | integer | 42 |
float | number | 3.14 |
bool | boolean | true |
list[str] | array od string | ["a", "b"] |
dict | object | {"key": "val"} |
Optional[str] | string (nullable) | "text" ili null |
Čim alat izađe iz svog procesa — mrežni poziv, upit bazi podataka, čitanje udaljene datoteke — deklariraj ga kao async. Sinkroni rukovatelj koji čeka HTTP odgovor blokira cijeli poslužitelj, a time i tvoje ostale korisnike:
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 shema ograničava tipove, nikada vrijednosti: ništa ne sprječava model da pošalje ime od 3000 znakova ili izmišljenu ulogu. Stoga uvijek validiraj ulazne podatke na samom početku rukovatelja i vrati poruku koja ukazuje na potrebnu ispravku:
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ća poruka navodi dopuštene vrijednosti. Model se tada može ispraviti i ponovno pozvati alat, umjesto da odustane suočen s pogreškom „Neispravna uloga“ bez ikakvog objašnjenja.
Poliranje povratne vrijednosti
MCP alat uvijek vraća tekst, ali taj tekst može biti strukturirani JSON koji model vrlo dobro interpretira. Kontrast između ova dva povrata sažima bit stvari:
# Dobro: strukturirani, čitljivi JSON
return json.dumps({
"success": True,
"user": {
"name": "Alice Dupont",
"email": "[email protected]",
"role": "editor",
},
"message": "User created successfully"
}, ensure_ascii=False)
# Loše: sirovi podaci teški za korištenje
return "OK:user_id=abc123:status=created"
Uvijek daj prednost vrijednostima čitljivim čovjeku naspram internih identifikatora: model može odmah upotrijebiti „Alice Dupont“ u svom odgovoru, dok UUID prisiljava na dodatni poziv kako bi se saznalo o kome je riječ. Suprotno tome, čuvaj se preopširnih povrata — pedeset polja po zapisu puni kontekst bez dodane vrijednosti. Ispravan refleks pri pisanju alata je zapitati se što će modelu trebati da bi obavijestio korisnika i vratiti samo to.
Ključne točke
- Dekorator
@app.tool()automatski generira JSON Shemu za parametre - Naziv funkcije = naziv alata (glagol + objekt)
- Docstring je ključan: vodi model kada i kako pozvati alat
- Koristi Python anotacije tipova za shemu (str, int, float, bool, list, dict)
- Uvijek validiraj ulaze i vraćaj pogreške koje se mogu riješiti
- Vraćaj strukturirani JSON s vrijednostima čitljivim čovjeku