Ugrás a főtartalomra
Magyar— Nyelv kiválasztása
Menü

Eszközök megvalósítása: JSON Schema és kezelők

11. lecke 14 közül Frissítve 2026. november 2. Fejlesztő
Ezen az oldalon
  1. Egy MCP eszköz felépítése
  2. Mit épít fel neked a dekorátor?
  3. Először a elnevezés, aztán a leírás
  4. Típusok, aszinkron kezelők és validálás
  5. A visszatérési érték csiszolása
  6. Főbb megállapítások

Frissítve: 2026. november 2. — MCP Python SDK v2. Ez a tanfolyam az mcp SDK 2-es verzióját követi (2026. október 2-i állapot szerint 2.3.0): az MCPServer leváltja a FastMCP-t, a transzportbeállítások a run() vagy a streamable_http_app() függvényekbe kerültek, és egy valós hosztnév alatt elérhető alkalmazásnak deklarálnia kell ezt a hosztnevet (transport_security). Ez az a verzió, amelyet a Mistral SDK is megkövetel: a mistralai[agents] extra függőségéhez mcp>=2.2.0,<3.0 szükséges. Források: Újdonságok a v2-ben · Migrációs útmutató · Telepítés és méretezés.

Egy MCP eszköz felépítése

Egy MCP eszköz Python függvénynek tűnik, de a modell szemszögéből nem az. Ez egy négyrészes szerződés: egy név, egy leírás, egy JSON bemeneti séma és egy logikát végrehajtó kezelő. A modell sosem látja a kódodat – csak ezt a szerződést ismeri. Egy tökéletesen megvalósított, de rosszul leírt eszközt sosem hívnak meg, vagy rossz időpontban aktiválódik. Ezért a szerver hatékonyságát sokkal inkább a szerződés minősége határozza meg, mint a megvalósításé.

Mit épít fel neked a dekorátor?

Az MCPServer automatikusan felépíti ezt a szerződést a függvény aláírása és a docstringje alapján. Te szabványos Pythont írsz:

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 modell pedig ezt kapja:

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

Hasonlítsd össze soronként a két blokkot: minden típusannotáció JSON típussá válik, minden alapértelmezett érték egy default mezővé, az Args szakasz minden sora egy paraméterleírássá, és csak az az argumentum kerül a required listába, amelynek nincs alapértelmezett értéke. Más szóval: amit kihagysz a docstringből, az teljesen eltűnik a szerződésből.

Először a elnevezés, aztán a leírás

Az eszköz neve megegyezik a függvény nevével, és a modell ezt használja első támpontként. Egy cselekvést kifejező ige, amelyet egy egyértelmű tárgy követ, nem hagy teret a félreértésnek, míg egy általános vagy technikai név találgatásra kényszeríti a modellt:

# Jó: cselekvőige + egyértelmű tárgy
@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: ...

# Rossz: bizonytalan, kétértelmű, technikai
@app.tool()
def process(data: str) -> str: ...        # Túl bizonytalan

@app.tool()
def handle_request(req: str) -> str: ...   # Az LLM számára érthetetlen

@app.tool()
def db_query(sql: str) -> str: ...         # Túl technikai

Ezután jön a docstring, amely a teljes szervered legkritikusabb eleme. Három kérdésre kell választ adnia, ebben a sorrendben: mikor használd ezt az eszközt, milyen paramétereket adj meg (formátummal és korlátozásokkal), és mit várj visszaként. A következő példa bemutatja, hogyan néz ez ki a valóságban:

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

Az első sort követő bekezdés az, ami a kezdő szerverekből leggyakrabban hiányzik. Enélkül a modell tudja, mit csinál az eszköz, de azt nem, milyen helyzetben kellene aktiválnia. Az ISO 8601 dátumpélda pedig tucatnyi olyan hívást spórol meg neked, ahol a modell "April 15 at 7:30 PM" formátumban küldene dátumot.

Típusok, aszinkron kezelők és validálás

Az MCPServer lefordítja a gyakori Python annotációkat a megfelelő JSON Schema típusokra.

PythonJSON SchemaPélda
strstring"text"
intinteger42
floatnumber3.14
boolbooleantrue
list[str]array of string["a", "b"]
dictobject{"key": "val"}
Optional[str]string (nullable)"text" vagy null

Amint egy eszköz kilép a saját folyamatából – hálózati hívás, adatbázis-lekérdezés, távoli fájl olvasása –, deklarálnod kell async-ként. Egy szinkron kezelő, amely HTTP-válaszra vár, blokkolja az egész szervert, és vele együtt a többi felhasználót is:

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

A JSON séma csak a típusokat korlátozza, az értékeket nem: semmi sem akadályozza meg a modellt abban, hogy 3000 karakteres nevet vagy kitalált szerepkört küldjön. Ezért mindig validálj a kezelő belépési pontjánál, és adj vissza egy üzenetet, amely jelzi a szükséges javítást:

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

A harmadik üzenet felsorolja az engedélyezett értékeket. Így a modell kijavíthatja magát, és újra meghívhatja az eszközt, ahelyett, hogy feladná a magyarázat nélküli „Érvénytelen szerepkör“ hiba miatt.

A visszatérési érték csiszolása

Egy MCP eszköz mindig szöveget ad vissza, de ez a szöveg lehet strukturált JSON is, amelyet a modell nagyon jól értelmez. E két visszatérési érték közötti kontraszt összefoglalja a lényeget:

# Jó: strukturált, olvasható JSON
return json.dumps({
    "success": True,
    "user": {
        "name": "Alice Dupont",
        "email": "[email protected]",
        "role": "editor",
    },
    "message": "User created successfully"
}, ensure_ascii=False)

# Rossz: nyers, nehezen használható adat
return "OK:user_id=abc123:status=created"

Mindig részesítsd előnyben az ember által olvasható értékeket a belső azonosítókkal szemben: a modell azonnal felhasználhatja a "Alice Dupont" nevet a válaszában, míg egy UUID miatt további hívásra lenne szükség, hogy kiderítse, kiről van szó. Ezzel szemben óvakodj a túlbővített válaszoktól – rekordonként ötven mező megtölti a kontextust anélkül, hogy értéket adna hozzá. A helyes reflex egy eszköz írásakor, ha felteszed magadnak a kérdést: mire lesz szüksége a modellnek, hogy tájékoztassa a felhasználót, és csak azt add vissza.

Főbb megállapítások

  • Az @app.tool() dekorátor automatikusan generálja a paraméterek JSON Schema leírását
  • A függvény neve = az eszköz neve (ige + tárgy)
  • A docstring kritikus fontosságú: ez útmutatást ad a modellnek, mikor és hogyan hívja meg az eszközt
  • Használj Python típusannotációkat a sémához (str, int, float, bool, list, dict)
  • Mindig validáld a bemeneteket, és adj vissza cselekvésre ösztönző hibákat
  • Strukturált JSON-t adj vissza, ember által olvasható értékekkel