Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Implementace nástrojů: JSON Schema a obslužné rutiny

Lekce 11 z 14 Aktualizováno 2. listopadu 2026 Vývojář
Na této stránce
  1. Anatomie nástroje MCP
  2. Co pro tebe dekorátor vytvoří
  3. Pojmenování a následný popis
  4. Typy, asynchronní obslužné rutiny a validace
  5. Vylepšení návratové hodnoty
  6. Klíčové poznatky

Aktualizováno 2. listopadu 2026 — MCP Python SDK v2. Tento kurz nyní vychází z verze 2 SDK mcp (konkrétně 2.3.0 k 2. říjnu 2026): MCPServer nahrazuje FastMCP, nastavení transportu se přesouvá do run() nebo streamable_http_app() a aplikace vystavená pod skutečným hostname musí tento hostname deklarovat (transport_security). Toto je také verze požadovaná Mistral SDK: extra balíček mistralai[agents] vyžaduje mcp>=2.2.0,<3.0. Zdroje: Co je nového ve v2 · Průvodce migrací · Nasazení a škálování.

Anatomie nástroje MCP

Nástroj MCP vypadá jako funkce v Pythonu, ale z pohledu modelu jím není. Je to čtyřdílná smlouva: název, popis, vstupní schéma JSON a obslužná rutina (handler), která provádí logiku. Model nikdy nevidí tvůj kód – vidí pouze tuto smlouvu. Dokonale implementovaný nástroj, který je špatně popsaný, nikdy nebude zavolán, nebo bude spuštěn ve špatnou chvíli. Kvalita smlouvy tedy určuje efektivitu serveru daleko více než kvalita samotné implementace.

Co pro tebe dekorátor vytvoří

MCPServer tuto smlouvu vytvoří automaticky na základě signatury funkce a docstringu. Píšeš standardní 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 obdrží toto:

{
  "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"]
  }
}

Porovnej si oba bloky řádek po řádku: každá typová anotace se stane typem JSON, každá výchozí hodnota se stane polem default, každý řádek v sekci Args se stane popisem parametru a jediný argument bez výchozí hodnoty skončí v poli required. Jinými slovy, cokoli vynecháš z docstringu, ze smlouvy zcela zmizí.

Pojmenování a následný popis

Název nástroje je název funkce a model jej používá jako první vodítko. Sloveso vyjadřující akci následované jasným objektem nenechává prostor pro nejistotu, zatímco obecný nebo technický název nutí model hádat:

# Dobře: sloveso akce + jasný 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: ...

# Špatně: vágní, nejednoznačné, technické
@app.tool()
def process(data: str) -> str: ...        # Příliš vágní

@app.tool()
def handle_request(req: str) -> str: ...   # Pro LLM nepochopitelné

@app.tool()
def db_query(sql: str) -> str: ...         # Příliš technické

Docstring pak přebírá otěže a představuje nejdůležitější část celého tvého serveru. Musí odpovědět na tři otázky v tomto pořadí: kdy tento nástroj použít, jaké parametry poskytnout včetně jejich formátu a omezení a co očekávat na výstupu. Následující příklad ukazuje, jak to vypadá v reálném případě:

@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
    """
    ...

Odstavec následující po prvním řádku je to, co amatérským serverům nejčastěji chybí. Bez něj model ví, co nástroj dělá, ale neví, v jaké situaci jej spustit. A příklad data ve formátu ISO 8601 ti ušetří desítky volání s údaji typu "15. dubna v 19:30".

Typy, asynchronní obslužné rutiny a validace

MCPServer převádí běžné pythonovské anotace na jejich ekvivalenty v JSON Schema.

PythonJSON SchemaPříklad
strstring"text"
intinteger42
floatnumber3.14
boolbooleantrue
list[str]array typu string["a", "b"]
dictobject{"key": "val"}
Optional[str]string (nullable)"text" nebo null

Jakmile nástroj vykročí mimo svůj proces – volání sítě, dotaz do databáze, čtení vzdáleného souboru – deklaruj jej jako async. Synchronní obslužná rutina čekající na HTTP odpověď zablokuje celý server a s ním i všechny ostatní uživatele:

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

Schéma JSON omezuje typy, nikdy však hodnoty: nic nebrání modelu poslat jméno o délce 3000 znaků nebo vymyšlenou roli. Vždy proto validuj vstup hned na začátku obslužné rutiny a vrať zprávu indikující potřebnou opravu:

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}})

Třetí zpráva vypisuje povolené hodnoty. Model se pak může opravit a nástroj zavolat znovu, místo aby se vzdal tváří v tvář chybě „Neplatná role“ bez jakéhokoli vysvětlení.

Vylepšení návratové hodnoty

Nástroj MCP vždy vrací text, ale tento text může být strukturované JSON, které model interpretuje velmi dobře. Kontrast mezi těmito dvěma návratovými hodnotami shrnuje to podstatné:

# Dobře: strukturované, čitelné JSON
return json.dumps({
    "success": True,
    "user": {
        "name": "Alice Dupont",
        "email": "[email protected]",
        "role": "editor",
    },
    "message": "User created successfully"
}, ensure_ascii=False)

# Špatně: syrová data, která se špatně používají
return "OK:user_id=abc123:status=created"

Vždy upřednostňuj hodnoty čitelné pro člověka před interními identifikátory: model může okamžitě použít "Alice Dupont" ve své odpovědi, zatímco UUID ho nutí k dalšímu volání, aby zjistil, o koho jde. Naopak se vyhýbej nafouklým návratům – padesát polí na záznam zaplní kontext, aniž by přineslo hodnotu. Správný reflex při psaní nástroje je zeptat se sám sebe, co bude model potřebovat sdělit uživateli, a vrátit pouze toto.

Klíčové poznatky

  • Dekorátor @app.tool() automaticky generuje JSON Schema pro parametry
  • Název funkce = název nástroje (sloveso + objekt)
  • Docstring je zásadní: vede model k tomu, kdy a jak nástroj zavolat
  • Používej pythonovské typové anotace pro schéma (str, int, float, bool, list, dict)
  • Vždy validuj vstupy a vracej chyby, které lze řešit
  • Vracej strukturované JSON s hodnotami čitelnými pro člověka