Salt la conținutul principal
Română— Alege o limbă
Meniu

Implementarea instrumentelor: JSON Schema și handler-e

Lecția 11 din 14 Actualizată 2 noiembrie 2026 Dezvoltator
Pe această pagină
  1. Anatomia unui instrument MCP
  2. Ce construiește decoratorul pentru dumneavoastră
  3. Denumirea, apoi descrierea
  4. Tipuri, handler-e asincrone și validare
  5. Perfecționarea valorii de returnare
  6. Puncte cheie

Actualizat la 2 noiembrie 2026 — MCP Python SDK v2. Acest curs urmează acum versiunea 2 a SDK-ului mcp (2.3.0 la data de 2 octombrie 2026): MCPServer înlocuiește FastMCP, setările de transport se mută în run() sau streamable_http_app(), iar o aplicație expusă sub un nume de gazdă real trebuie să declare acel nume de gazdă (transport_security). Aceasta este, de asemenea, versiunea cerută de Mistral SDK: extra-ul mistralai[agents] necesită mcp>=2.2.0,<3.0. Surse: Ce este nou în v2 · Ghid de migrare · Deploy & scale.

Anatomia unui instrument MCP

Un instrument MCP seamănă cu o funcție Python, dar din perspectiva modelului, nu este una. Este un contract compus din patru părți: un nume, o descriere, o schemă de intrare JSON și un handler care execută logica. Modelul nu vede niciodată codul dumneavoastră – vede doar acest contract. Un instrument perfect implementat, dar descris prost, nu va fi niciodată apelat sau va fi apelat la momentul nepotrivit. Prin urmare, calitatea contractului determină eficacitatea serverului mult mai mult decât calitatea implementării.

Ce construiește decoratorul pentru dumneavoastră

MCPServer construiește acest contract automat pe baza semnăturii funcției și a docstring-ului dumneavoastră. Scrieți Python standard:

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

Iar modelul primește ceci:

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

Comparați cele două blocuri linie cu linie: fiecare anotare de tip devine un tip JSON, fiecare valoare implicită devine un câmp default, fiecare linie din secțiunea Args devine o descriere de parametru, iar singurul argument fără valoare implicită ajunge în required. Cu alte cuvinte, orice omiteți din docstring dispare complet din contract.

Denumirea, apoi descrierea

Numele instrumentului este numele funcției, iar modelul îl folosește ca prim indiciu. Un verb de acțiune urmat de un obiect clar nu lasă loc de ambiguitate, în timp ce un nume generic sau tehnic forțează modelul să ghicească:

# Bun: verb de acțiune + obiect clar
@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: ...

# Rău: vag, ambiguu, tehnic
@app.tool()
def process(data: str) -> str: ...        # Prea vag

@app.tool()
def handle_request(req: str) -> str: ...   # De neînțeles pentru LLM

@app.tool()
def db_query(sql: str) -> str: ...         # Prea tehnic

Docstring-ul preia apoi ștafeta și constituie cea mai critică piesă a întregului dumneavoastră server. Acesta trebuie să răspundă la trei întrebări, în această ordine: când să utilizați acest instrument, ce parametri să furnizați cu formatul și constrângerile lor și ce să vă așteptați ca rezultat. Următorul exemplu arată cum arată acest lucru într-un caz real:

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

Paragraful care urmează după prima linie este ceea ce lipsește cel mai adesea serverelor amatoare. Fără el, modelul știe ce face instrumentul, dar nu în ce situație să îl declanșeze. Iar exemplul de dată ISO 8601 vă va economisi zeci de apeluri cu „15 aprilie la 19:30“.

Tipuri, handler-e asincrone și validare

MCPServer traduce anotările Python comune în echivalentele lor JSON Schema.

PythonJSON SchemaExemplu
strstring"text"
intinteger42
floatnumber3.14
boolbooleantrue
list[str]array de string["a", "b"]
dictobject{"key": "val"}
Optional[str]string (nullable)"text" sau null

De îndată ce un instrument iese din procesul său – apel de rețea, interogare de bază de date, citire de fișier la distanță – declarați-l async. Un handler sincron care așteaptă un răspuns HTTP blochează întregul server și, odată cu el, și ceilalți utilizatori ai dumneavoastră:

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

Schema JSON constrânge tipurile, niciodată valorile: nimic nu împiedică modelul să trimită un nume de 3.000 de caractere sau un rol inventat. Prin urmare, validați întotdeauna la punctul de intrare al handler-ului și returnați un mesaj care indică corecția necesară:

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

Al treilea mesaj enumeră valorile permise. Modelul se poate corecta apoi și poate apela din nou instrumentul, în loc să renunțe în fața unei erori „Rol invalid“ fără nicio explicație.

Perfecționarea valorii de returnare

Un instrument MCP returnează întotdeauna text, dar acel text poate fi un JSON structurat, pe care modelul îl interpretează foarte bine. Contrastul dintre aceste două returnări rezumă esențialul:

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

# Rău: date brute greu de utilizat
return "OK:user_id=abc123:status=created"

Preferați întotdeauna valorile lizibile pentru om în detrimentul identificatorilor interni: modelul poate folosi imediat „Alice Dupont“ în răspunsul său, în timp ce un UUID forțează un apel suplimentar pentru a afla despre cine este vorba. În schimb, feriți-vă de returnări umflate – cincizeci de câmpuri per înregistrare umplu contextul fără a aduce valoare. Reflexul corect atunci când scrieți un instrument este să vă întrebați de ce are nevoie modelul pentru a-i spune utilizatorului și să returnați doar atât.

Puncte cheie

  • Decoratorul @app.tool() generează automat JSON Schema pentru parametri
  • Numele funcției = numele instrumentului (verb + obiect)
  • Docstring-ul este crucial: ghidează modelul cu privire la când și cum să apeleze instrumentul
  • Utilizați anotările de tip Python pentru schemă (str, int, float, bool, list, dict)
  • Validați întotdeauna intrările și returnați erori acționabile
  • Returnați JSON structurat cu valori lizibile pentru om