Implementacja narzędzi: schemat JSON i obsługa
Na tej stronie
Zaktualizowano 2 listopada 2026 — MCP Python SDK v2. Kurs opiera się teraz na wersji 2 SDK
mcp(2.3.0 na dzień 2 października 2026):MCPServerzastępujeFastMCP, ustawienia transportu przeniesiono dorun()lubstreamable_http_app(), a aplikacja udostępniana pod rzeczywistą nazwą hosta musi ją jawnie zadeklarować (transport_security). To także wersja wymagana przez Mistral SDK: dodatkowy pakietmistralai[agents]wymagamcp>=2.2.0,<3.0. Źródła: Co nowego w v2 · Przewodnik migracyjny · Wdrażanie i skalowanie.
Anatomia narzędzia MCP
Narzędzie MCP wygląda jak funkcja Pythona, ale z perspektywy modelu nim nie jest. To czteroczęściowa umowa: nazwa, opis, schemat wejściowy JSON oraz handler wykonujący logikę. Model nigdy nie widzi Twojego kodu — widzi tylko tę umowę. Nawet perfekcyjnie zaimplementowane narzędzie, które jest źle opisane, nigdy nie zostanie wywołane albo zostanie użyte w złym momencie. Dlatego jakość umowy decyduje o skuteczności serwera znacznie bardziej niż jakość samej implementacji.
Co dekorator robi za Ciebie
MCPServer buduje tę umowę automatycznie na podstawie sygnatury funkcji i docstringa. Piszesz standardowy kod Pythona:
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 otrzymuje to:
{
"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-200, 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"]
}
}
Porównaj oba bloki linia po linii: każda adnotacja typu staje się typem JSON, każda wartość domyślna zamienia się w pole default, każda linijka w sekcji Args staje się opisem parametru, a jedyny argument bez wartości domyślnej trafia do required. Innymi słowy, wszystko, co pominiesz w docstringu, znika całkowicie z umowy.
Najpierw nazwa, potem opis
Nazwa narzędzia to nazwa funkcji i model używa jej jako pierwszej wskazówki. Czasownik akcji połączony z jasnym obiektem nie pozostawia miejsca na niejednoznaczność, podczas gdy nazwa ogólna lub techniczna zmusza model do zgadywania:
# Dobrze: czasownik akcji + jasny obiekt
@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: ...
# Źle: niejasne, dwuznaczne, techniczne
@app.tool()
def process(data: str) -> str: ... # Zbyt ogólnie
@app.tool()
def handle_request(req: str) -> str: ... # Niezrozumiałe dla LLM
@app.tool()
def db_query(sql: str) -> str: ... # Zbyt techniczne
Docstring przejmuje pałeczkę i stanowi najważniejszy element całego Twojego serwera. Musi odpowiedzieć na trzy pytania w tej kolejności: kiedy użyć tego narzędzia, jakie parametry podać wraz z ich formatem i ograniczeniami oraz czego spodziewać się w odpowiedzi. Poniższy przykład pokazuje, jak wygląda to w praktyce:
@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
"""
...
Akapit następujący po pierwszej linii to właśnie to, czego najczęściej brakuje w amatorskich serwerach. Bez niego model wie, co narzędzie robi, ale nie wie, w jakiej sytuacji je uruchomić. Przykład daty w formacie ISO 8601 zaoszczędzi Ci dziesiątek wywołań z błędami typu "15 kwietnia o 19:30".
Typy, handlery asynchroniczne i walidacja
MCPServer tłumaczy powszechne adnotacje Pythona na ich odpowiedniki w schemacie JSON.
| Python | Schemat JSON | Przykład |
|---|---|---|
str | string | "tekst" |
int | integer | 42 |
float | number | 3.14 |
bool | boolean | true |
list[str] | array typu string | ["a", "b"] |
dict | object | {"klucz": "wartość"} |
Optional[str] | string (nullable) | "tekst" lub null |
Gdy tylko narzędzie wykracza poza swój proces — wywołanie sieciowe, zapytanie do bazy danych, odczyt zdalnego pliku — zadeklaruj je jako async. Synchroniczny handler oczekujący na odpowiedź HTTP blokuje cały serwer, a wraz z nim wszystkich innych użytkowników:
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
Schemat JSON ogranicza typy, nigdy wartości: nic nie阻止 modelu wysłania 3000-znakowej nazwy czy wymyślonej roli. Dlatego zawsze waliduj dane na wejściu handlera i zwracaj komunikat wskazujący niezbędną korektę:
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
"""
# Walidacja
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)}"})
# Tworzenie...
return json.dumps({"success": True, "user": {"name": name, "email": email, "role": role}})
Trzeci komunikat wymienia dozwolone wartości. Model może wtedy się poprawić i wywołać narzędzie ponownie, zamiast rezygnować w obliczu błędu „Nieprawidłowa rola“ bez żadnego wyjaśnienia.
Dopracowanie wartości zwracanej
Narzędzie MCP zawsze zwraca tekst, ale może to być strukturalny JSON, który model interpretuje bardzo dobrze. Kontrast między tymi dwoma zwrotami podsumowuje sedno sprawy:
# Dobrze: strukturalny, czytelny JSON
return json.dumps({
"success": True,
"user": {
"name": "Alice Dupont",
"email": "[email protected]",
"role": "editor",
},
"message": "User created successfully"
}, ensure_ascii=False)
# Źle: surowe dane trudne do wykorzystania
return "OK:user_id=abc123:status=created"
Zawsze preferuj wartości czytelne dla człowieka zamiast wewnętrznych identyfikatorów: model może natychmiast użyć "Alice Dupont" w swojej odpowiedzi, podczas gdy UUID wymusi dodatkowe wywołanie, aby ustalić, kogo dotyczy sprawa. Z drugiej strony, strzeż się rozwlekłych odpowiedzi — pięćdziesiąt pól na rekord wypełnia kontekst, nie dodając wartości. Właściwym odruchem przy pisaniu narzędzia jest zadanie sobie pytania, czego model będzie potrzebował, aby poinformować użytkownika, i zwrócenie tylko tego.
Kluczowe wnioski
- Dekorator
@app.tool()automatycznie generuje schemat JSON dla parametrów - Nazwa funkcji = nazwa narzędzia (czasownik + obiekt)
- Docstring jest kluczowy: prowadzi model, wskazując, kiedy i jak wywołać narzędzie
- Używaj adnotacji typów Pythona dla schematu (str, int, float, bool, list, dict)
- Zawsze waliduj dane wejściowe i zwracaj błędy wskazujące działanie naprawcze
- Zwracaj strukturalny JSON z wartościami czytelnymi dla człowieka