Preskok na glavno vsebino
Slovenščina— Izberite jezik
Meni

Implementacija orodij: shema JSON in ročaji

Lekcija 11 od 14 Posodobljeno 2. november 2026 Razvijalec
Na tej strani
  1. Anatomija orodja MCP
  2. Kaj dekorator zgradi zate
  3. Poimenovanje in nato opisovanje
  4. Tipi, asinhroni ročaji in preverjanje veljavnosti
  5. Izpopolnjevanje povratne vrednosti
  6. Ključne ugotovitve

Posodobljeno 2. novembra 2026 — MCP Python SDK v2. Ta tečaj zdaj sledi različici 2 paketa SDK mcp (2.3.0 z dne 2. oktobra 2026): MCPServer nadomešča FastMCP, nastavitve prenosa se premaknejo v run() ali streamable_http_app(), aplikacija, izpostavljena pod realnim gostiteljskim imenom, pa mora to ime navesti (transport_security). To je tudi različica, ki jo zahteva Mistral SDK: dodatni paket mistralai[agents] zahteva mcp>=2.2.0,<3.0. Viri: Kaj je novega v različici v2 · Vodnik za selitev · Namestitev in skaliranje.

Anatomija orodja MCP

Orodje MCP je videti kot funkcija Python, vendar z vidika modela to ni. Gre za štiridelno pogodbo: ime, opis, vhodno shemo JSON in ročaj, ki izvaja logiko. Model nikoli ne vidi tvoje kode – vidi le to pogodbo. Popolnoma implementirano orodje, ki je slabo opisano, nikoli ne bo klicano ali pa bo klicano ob napačnem času. Kakovost pogodbe torej določa učinkovitost strežnika veliko bolj kot kakovost same implementacije.

Kaj dekorator zgradi zate

MCPServer to pogodbo samodejno zgradi na podlagi podpisa tvoje funkcije in niza dokumentacije (docstring). Napiš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
    ...

Model pa prejme tole:

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

Oba bloka primerjaj vrstico za vrstico: vsaka anotacija tipa postane tip JSON, vsaka privzeta vrednost postane polje default, vsaka vrstica v razdelku Args postane opis parametra, edini argument brez privzete vrednosti pa konča v required. Z drugimi besedami: vse, kar izpustiš iz niza dokumentacije, iz pogodbe popolnoma izgine.

Poimenovanje in nato opisovanje

Ime orodja je ime funkcije in model ga uporabi kot prvi namig. Glagol, ki označuje dejanje, ki mu sledi jasen predmet, ne pušča prostora za dvoumnost, medtem ko splošno ali tehnično ime modela prisili v ugibanje:

# Dobro: glagol dejanja + jasen predmet
@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: ...

# Slabo: nejasno, dvoumno, tehnično
@app.tool()
def process(data: str) -> str: ...        # Preveč nejasno

@app.tool()
def handle_request(req: str) -> str: ...   # Za LLM nerazumljivo

@app.tool()
def db_query(sql: str) -> str: ...         # Preveč tehnično

Niz dokumentacije nato prevzame vajeti in predstavlja najpomembnejši del celotnega tvojega strežnika. Odgovoriti mora na tri vprašanja v tem vrstnem redu: kdaj uporabiti to orodje, katere parametre navesti z njihovo obliko in omejitvami ter kaj pričakovati kot rezultat. Naslednji primer prikazuje, kako to izgleda v praksi:

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

Odstavek, ki sledi prvi vrstici, je tisto, kar amaterskim strežnikom najpogosteje manjka. Brez njega model ve, kaj orodje počne, ne pa tudi, v katerem položaju naj ga sproži. Primer datuma ISO 8601 ti bo prihranil na desetine klicev z vnosi, kot je "April 15 at 7:30 PM".

Tipi, asinhroni ročaji in preverjanje veljavnosti

MCPServer prevede običajne anotacije Python v njihove ekvivalente v shemi JSON.

PythonShema JSONPrimer
strstring"text"
intinteger42
floatnumber3.14
boolbooleantrue
list[str]array tipa string["a", "b"]
dictobject{"key": "val"}
Optional[str]string (lahko ničelna)"text" ali null

Takoj ko orodje stopi izven svojega procesa – klic omrežja, poizvedba v bazo podatkov, branje oddaljene datoteke – ga razglasi za async. Sinhroni ročaj, ki čaka na odgovor HTTP, blokira celoten strežnik in s tem tudi vse tvoje druge uporabnike:

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

Shema JSON omejuje tipe, nikoli vrednosti: nič ne preprečuje modelu, da bi poslal ime z 3000 znaki ali izmišljeno vlogo. Zato vedno preveri veljavnost na vstopni točki ročaja in vrni sporočilo, ki kaže na potreben popravek:

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

Tretje sporočilo našteje dovoljene vrednosti. Model se lahko nato popravi in ponovno pokliče orodje, namesto da bi obupal pred napako „Neveljavna vloga” brez razlage.

Izpopolnjevanje povratne vrednosti

Orodje MCP vedno vrne besedilo, vendar je to besedilo lahko strukturiran JSON, ki ga model zelo dobro razume. Kontrast med tema dvema vrnjenima vrednostma povzema bistvo:

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

# Slabo: surovi podatki, ki jih je težko uporabiti
return "OK:user_id=abc123:status=created"

Vedno raje izberi vrednosti, berljive za človeka, namesto notranjih identifikatorjev: model lahko "Alice Dupont" takoj uporabi v svojem odgovoru, medtem ko UUID zahteva dodaten klic, da ugotovi, o kom govori. Po drugi strani se pazi preobsežnih vrnjenih vrednosti – petdeset polj na zapis zapolni kontekst, ne da bi dodalo vrednost. Pravi refleks pri pisanju orodja je, da se vprašaš, kaj bo model potreboval, da pove uporabniku, in vrneš samo to.

Ključne ugotovitve

  • Dekorator @app.tool() samodejno ustvari shemo JSON za parametre
  • Ime funkcije = ime orodja (glagol + predmet)
  • Niz dokumentacije je ključen: vodi model pri tem, kdaj in kako poklicati orodje
  • Uporabi anotacije tipov Python za shemo (str, int, float, bool, list, dict)
  • Vedno preveri veljavnost vhodov in vrni napake, ki omogočajo ukrepanje
  • Vrni strukturiran JSON z vrednostmi, berljivimi za človeka