Lähe põhisisu juurde
Eesti— Vali keel
Menüü

Tööriistade rakendamine: JSON Schema ja käitlejad

Õppetund 11 / 14 Värskendatud 2. november 2026 Arendajatele
Sellel lehel
  1. MCP tööriista anatoomia
  2. Mida dekorator sinu eest teeb
  3. Nime andmine ja seejärel kirjeldamine
  4. Tüübid, asünkroonsed käitlejad ja valideerimine
  5. Tagastusväärtuse lihvimine
  6. Peamised punktid

Uuendatud 2. novembril 2026 — MCP Python SDK v2. See kursus järgib nüüd mcp SDK versiooni 2 (seisuga 2. oktoober 2026 on see 2.3.0): MCPServer asendab FastMCP-i, transpordi seaded liiguvad meetoditesse run() või streamable_http_app() ning reaalse hostinime all avaldatud rakendus peab selle hostinime deklareerima (transport_security). See on ka versioon, mida nõuab Mistral SDK: lisapakett mistralai[agents] eeldab mcp>=2.2.0,<3.0. Allikad: Mis on uut v2-s · Migratsioonijuhend · Kasutuselevõtt ja skaleerimine.

MCP tööriista anatoomia

MCP tööriist näeb välja nagu Pythoni funktsioon, kuid mudeli seisukohalt see seda ei ole. See on neljaosaline leping: nimi, kirjeldus, JSON-i sisendskeem ja käitleja, mis viib loogika täide. Mudel ei näe kunagi sinu koodi – ta näeb ainult seda lepingut. Ideaalselt teostatud, kuid halvasti kirjeldatud tööriista ei kutsuta kunagi välja või tehakse seda valel ajal. Seetõttu määrab lepingu kvaliteet serveri tõhususe palju rohkem kui rakenduse kvaliteet.

Mida dekorator sinu eest teeb

MCPServer loob selle lepingu automaatselt sinu funktsiooni signatuuri ja dokumendistringi põhjal. Sa kirjutad tavalist Pythonit:

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

Ja mudel saab vastu selle:

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

Võrdle neid kahte plokki rida-realt: iga tüübimärge muutub JSON-i tüübiks, iga vaikimisi väärtus muutub väljaks default, iga rida sektsioonis Args muutub parameetri kirjelduseks ja ainus argument ilma vaikimisi väärtuseta satub loendisse required. Teisisõnu, kõik, mida sa dokumendistringist välja jätad, kaob lepingust täielikult.

Nime andmine ja seejärel kirjeldamine

Tööriista nimi on funktsiooni nimi ja mudel kasutab seda esmase vihjena. Tegevust väljendav tegusõna koos selge objektiga jätab ruumi tõlgendustele, samas kui üldine või tehniline nimi sunnib mudelit arvama:

# Hea: tegevust väljendav tegusõna + selge 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: ...

# Halb: ebamäärane, mitmetähenduslik, tehniline
@app.tool()
def process(data: str) -> str: ...        # Liiga ebamäärane

@app.tool()
def handle_request(req: str) -> str: ...   # LLM-ile arusaamatu

@app.tool()
def db_query(sql: str) -> str: ...         # Liiga tehniline

Dokumendistring võtab seejärel ohjad enda kätte ja moodustab kogu sinu serveri kriitilisima osa. See peab vastama kolmele küsimusele järgmises järjekorras: millal seda tööriista kasutada, milliseid parameetreid koos nende vormingu ja piirangutega esitada ning mida vastuseks oodata. Järgnev näide illustreerib, kuidas see reaalses olukorras välja näeb:

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

Lõik, mis järgneb esimesele reale, on see, mida amatöörserveritel kõige sagedamini napib. Ilma selleta teab mudel, mida tööriist teeb, kuid mitte millises olukorras seda käivitada. Ja ISO 8601 kuupäeva näide säästab sind kümnetest kõnedest vormingus „15. aprill kell 19.30“.

Tüübid, asünkroonsed käitlejad ja valideerimine

MCPServer tõlgib levinud Pythoni annotatsioonid nende JSON Schema ekvivalentideks.

PythonJSON SchemaNäide
strstring"tekst"
intinteger42
floatnumber3.14
boolbooleantrue
list[str]array tüübist string["a", "b"]
dictobject{"võti": "väärtus"}
Optional[str]string (võib olla null)"tekst" või null

Niipea kui tööriist astub oma protsessist välja – võrgukõne, andmebaasipäring, kaugfaili lugemine – deklareeri see async-ina. Sünkroonne käitleja, mis ootab HTTP vastust, blokeerib kogu serveri ja koos sellega ka teised kasutajad:

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 skeem piirab tüüpe, mitte kunagi väärtusi: miski ei takista mudelit saatmast 3000-märgilist nime või väljamõeldud rolli. Seetõttu valideeri alati sisendit käitleja sisenemispunktis ja tagasta sõnum, mis näitab vajalikku parandust:

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
    """
    # Valideerimine
    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)}"})

    # Loome...
    return json.dumps({"success": True, "user": {"name": name, "email": email, "role": role}})

Kolmas sõnum loetleb lubatud väärtused. Mudel saab seejärel ennast parandada ja tööriista uuesti välja kutsuda, selle asemel et loobuda ebaselge vea „Invalid role“ ees ilma selgituseta.

Tagastusväärtuse lihvimine

MCP tööriist tagastab alati teksti, kuid see tekst võib olla struktureeritud JSON, mida mudel tõlgendab väga hästi. Kontrast nende kahe tagastuse vahel võtab kokku olulise:

# Hea: struktureeritud, loetav JSON
return json.dumps({
    "success": True,
    "user": {
        "name": "Alice Dupont",
        "email": "[email protected]",
        "role": "editor",
    },
    "message": "User created successfully"
}, ensure_ascii=False)

# Halb: toored andmed, mida on raske kasutada
return "OK:user_id=abc123:status=created"

Eelista alati inimesele loetavaid väärtusi sisemiste identifikaatorite asemel: mudel saab kohe kasutada nime „Alice Dupont“ oma vastuses, samas kui UUID sunnib tegema täiendava kõne, et teada saada, kellest juttu on. Samas hoia tagasi ülepaisunud tagastustest – viiskümmend välja kirje kohta täidavad konteksti väärtust lisamata. Õige refleks tööriista kirjutamisel on küsida endalt, mida mudel vajab kasutajale ütlemiseks, ja tagastada ainult seda.

Peamised punktid

  • Dekorator @app.tool() genereerib parameetrite jaoks automaatselt JSON Schema
  • Funktsiooni nimi = tööriista nimi (tegevust väljendav tegusõna + objekt)
  • Dokumendistring on kriitilise tähtsusega: see juhendab mudelit, millal ja kuidas tööriista kutsuda
  • Kasuta skeemi jaoks Pythoni tüübimärkeid (str, int, float, bool, list, dict)
  • Valideeri alati sisendeid ja tagasta tegevust võimaldavad veateated
  • Tagasta struktureeritud JSON inimesele loetavate väärtustega