Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Implementazione degli strumenti: JSON Schema e gestori

Lezione 11 di 14 Aggiornata il 2 novembre 2026 Sviluppatore
In questa pagina
  1. L’anatomia di uno strumento MCP
  2. Cosa costruisce per te il decoratore
  3. Nominare, poi descrivere
  4. Tipi, gestori asincroni e validazione
  5. Affinare il valore di ritorno
  6. Punti chiave

Aggiornato il 2 novembre 2026 — MCP Python SDK v2. Questo corso segue ora la versione 2 dell’SDK mcp (2.3.0 al 2 ottobre 2026): MCPServer sostituisce FastMCP, le impostazioni di trasporto si spostano in run() o streamable_http_app(), e un’applicazione esposta sotto un hostname reale deve dichiarare tale hostname (transport_security). Questa è anche la versione richiesta dall’SDK Mistral: l’extra mistralai[agents] richiede mcp>=2.2.0,<3.0. Fonti: Novità nella v2 · Guida alla migrazione · Deploy e scalabilità.

L’anatomia di uno strumento MCP

Uno strumento MCP sembra una funzione Python, ma dal punto di vista del modello non lo è. È un contratto in quattro parti: un nome, una descrizione, uno schema di input JSON e un gestore che esegue la logica. Il modello non vede mai il tuo codice: vede solo questo contratto. Uno strumento perfettamente implementato ma mal descritto non verrà mai chiamato, oppure verrà invocato al momento sbagliato. Pertanto, la qualità del contratto determina l’efficacia del server ben più della qualità dell’implementazione.

Cosa costruisce per te il decoratore

MCPServer genera automaticamente questo contratto a partire dalla firma della tua funzione e dal suo docstring. Scrivi 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
    ...

E il modello riceve questo:

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

Confronta i due blocchi riga per riga: ogni annotazione di tipo diventa un tipo JSON, ogni valore predefinito diventa un campo default, ogni riga nella sezione Args diventa una descrizione del parametro, e l’unico argomento senza valore predefinito finisce in required. In altre parole, tutto ciò che ometti nel docstring scompare completamente dal contratto.

Nominare, poi descrivere

Il nome dello strumento è il nome della funzione, e il modello lo usa come primo indizio. Un verbo d’azione seguito da un oggetto chiaro non lascia ambiguità, mentre un nome generico o tecnico costringe il modello a indovinare:

# Buono: verbo d'azione + oggetto chiaro
@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: ...

# Cattivo: vago, ambiguo, tecnico
@app.tool()
def process(data: str) -> str: ...        # Troppo vago

@app.tool()
def handle_request(req: str) -> str: ...   # Incomprensibile per l'LLM

@app.tool()
def db_query(sql: str) -> str: ...         # Troppo tecnico

Il docstring prende poi il sopravvento e costituisce il pezzo più critico dell’intero server. Deve rispondere a tre domande in questo ordine: quando usare questo strumento, quali parametri fornire con il loro formato e i loro vincoli, e cosa aspettarsi in ritorno. L’esempio seguente mostra come appare tutto ciò in un caso reale:

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

Il paragrafo successivo alla prima riga è ciò che manca più spesso nei server amatoriali. Senza di esso, il modello sa cosa fa lo strumento, ma non in quale situazione attivarlo. E l’esempio di data ISO 8601 ti risparmierà decine di chiamate con "15 aprile alle 19:30".

Tipi, gestori asincroni e validazione

MCPServer traduce le comuni annotazioni Python nei loro equivalenti JSON Schema.

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

Non appena uno strumento esce dal suo processo — chiamata di rete, query al database, lettura di file remoto — dichiaralo async. Un gestore sincrono in attesa di una risposta HTTP blocca l’intero server, e con esso tutti gli altri utenti:

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

Lo schema JSON vincola i tipi, mai i valori: nulla impedisce al modello di inviare un nome di 3.000 caratteri o un ruolo inventato. Pertanto, valida sempre all’ingresso del gestore e restituisci un messaggio che indichi la correzione necessaria:

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

Il terzo messaggio elenca i valori consentiti. Il modello può così correggersi e richiamare lo strumento, invece di arrendersi di fronte a un errore “Ruolo non valido” senza spiegazioni.

Affinare il valore di ritorno

Uno strumento MCP restituisce sempre testo, ma quel testo può essere JSON strutturato, che il modello interpreta molto bene. Il contrasto tra questi due ritorni riassume l’essenziale:

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

# Cattivo: dati grezzi difficili da usare
return "OK:user_id=abc123:status=created"

Preferisci sempre valori leggibili da un umano rispetto a identificatori interni: il modello può usare immediatamente "Alice Dupont" nella sua risposta, mentre un UUID costringe a una chiamata aggiuntiva per capire di chi si sta parlando. Al contrario, attenzione ai ritorni gonfiati: cinquanta campi per record riempiono il contesto senza aggiungere valore. Il buon riflesso quando scrivi uno strumento è chiederti di cosa avrà bisogno il modello per parlare all’utente, e restituire solo quello.

Punti chiave

  • Il decoratore @app.tool() genera automaticamente lo JSON Schema per i parametri
  • Il nome della funzione = nome dello strumento (verbo + oggetto)
  • Il docstring è cruciale: guida il modello su quando e come chiamare lo strumento
  • Usa le annotazioni di tipo Python per lo schema (str, int, float, bool, list, dict)
  • Valida sempre gli input e restituisci errori azionabili
  • Restituisci JSON strutturato con valori leggibili dall’uomo