Spring til hovedindhold
Dansk— Vælg et sprog
Menu

Implementering af værktøjer: JSON-skema og håndterere

Lektion 11 af 14 Opdateret 2. november 2026 Udvikler
På denne side
  1. Anatomien af et MCP-værktøj
  2. Hvad dekoreratoren bygger for dig
  3. Navngivning og derefter beskrivelse
  4. Typer, asynkrone håndterere og validering
  5. Polering af returværdien
  6. Vigtige pointer

Opdateret 2. november 2026 — MCP Python SDK v2. Dette kursus følger nu version 2 af mcp-SDK’et (2.3.0 pr. 2. oktober 2026): MCPServer erstatter FastMCP, transportindstillinger flyttes til run() eller streamable_http_app(), og en applikation, der eksponeres under et rigtigt værtsnavn, skal deklarere dette værtsnavn (transport_security). Dette er også den version, der kræves af Mistral SDK: ekstra-pakken mistralai[agents] kræver mcp>=2.2.0,<3.0. Kilder: Hvad er nyt i v2 · Migrationsguide · Deploy & scale.

Anatomien af et MCP-værktøj

Et MCP-værktøj ligner en Python-funktion, men set fra modellens perspektiv er det ikke én. Det er en kontrakt bestående af fire dele: et navn, en beskrivelse, et JSON-inputskema og en håndterer, der udfører logikken. Modellen ser aldrig din kode – den ser kun denne kontrakt. Et perfekt implementeret værktøj, der er dårligt beskrevet, vil aldrig blive kaldt, eller også vil det blive kaldt på det forkerte tidspunkt. Derfor bestemmer kvaliteten af kontrakten serverens effektivitet langt mere end kvaliteten af selve implementeringen.

Hvad dekoreratoren bygger for dig

MCPServer bygger denne kontrakt automatisk ud fra din funktionssignatur og docstring. Du skriver almindelig 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
    ...

Og modellen modtager dette:

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

Sammenlign de to blokke linje for linje: hver typeannotation bliver til en JSON-type, hver standardværdi bliver til et default-felt, hver linje i Args-sektionen bliver til en parameterbeskrivelse, og det eneste argument uden en standardværdi ender i required. Med andre ord forsvinder alt, hvad du udelader fra docstringen, fuldstændigt fra kontrakten.

Værktøjets navn er funktionens navn, og modellen bruger det som sit første hint. Et handlingsverbum efterfulgt af et klart objekt efterlader ingen tvetydighed, hvorimod et generisk eller teknisk navn tvinger modellen til at gætte:

# Godt: handlingsverbum + klart 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: ...

# Dårligt: vagt, tvetydigt, teknisk
@app.tool()
def process(data: str) -> str: ...        # For vagt

@app.tool()
def handle_request(req: str) -> str: ...   # Uforståeligt for LLM'en

@app.tool()
def db_query(sql: str) -> str: ...         # For teknisk

Docstringen overtager derefter og udgør det vigtigste element i hele din server. Den skal besvare tre spørgsmål i denne rækkefølge: hvornår værktøjet skal bruges, hvilke parametre der skal angives med deres format og begrænsninger, og hvad man kan forvente tilbage. Følgende eksempel viser, hvordan dette ser ud i et realistisk tilfælde:

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

Afsnittet efter den første linje er det, amatørservere oftest mangler. Uden det ved modellen, hvad værktøjet gør, men ikke i hvilken situation det skal aktiveres. Og eksemplet med datoen i ISO 8601-format vil spare dig for snesevis af kald med "15. april kl. 19.30".

Typer, asynkrone håndterere og validering

MCPServer oversætter almindelige Python-annotationer til deres JSON-skema-modstykker.

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

Så snart et værktøj træder uden for sin egen proces – netværkskald, databaseforespørgsel, læsning af fjernfil – skal du deklarere det som async. En synkron håndterer, der venter på et HTTP-svar, blokerer hele serveren og dermed også dine andre brugere:

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-skemaet begrænser typer, aldrig værdier: intet forhindrer modellen i at sende et navn på 3.000 tegn eller en opdigtet rolle. Derfor skal du altid validere ved håndtererens indgangspunkt og returnere en besked, der angiver den nødvendige korrektion:

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

Den tredje besked lister de tilladte værdier. Modellen kan derefter rette sig selv og kalde værktøjet igen, i stedet for at give op over for en „Ugyldig rolle”-fejl uden forklaring.

Polering af returværdien

Et MCP-værktøj returnerer altid tekst, men denne tekst kan være struktureret JSON, som modellen fortolker meget godt. Kontrasten mellem disse to returneringer opsummerer det væsentlige:

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

# Dårligt: rå data, der er svære at bruge
return "OK:user_id=abc123:status=created"

Foretræk altid værdier, der er læsbare for et menneske, frem for interne identifikatorer: modellen kan straks bruge "Alice Dupont" i sit svar, hvorimod en UUID tvinger den til et ekstra kald for at finde ud af, hvem der tales om. Omvendt skal du passe på oppustede returneringer – halvtreds felter pr. post fylder konteksten uden at tilføje værdi. Den rigtige refleks, når du skriver et værktøj, er at spørge dig selv, hvad modellen får brug for at fortælle brugeren, og kun returnere dét.

Vigtige pointer

  • Dekoreratoren @app.tool() genererer automatisk JSON-skemaet for parametre
  • Funktionsnavnet = værktøjsnavn (verbum + objekt)
  • Docstringen er afgørende: den guider modellen i, hvornår og hvordan værktøjet skal kaldes
  • Brug Python-typeannotationer til skemaet (str, int, float, bool, list, dict)
  • Valider altid input og returner handlingsorienterede fejlmeddelelser
  • Returner struktureret JSON med menneskelæsbare værdier