Työkalujen toteuttaminen: JSON Schema ja käsittelijät
Tällä sivulla
Päivitetty 2. marraskuuta 2026 — MCP Python SDK v2. Tämä kurssi noudattaa nyt
mcp-SDK:n versiota 2 (2.3.0 tilanteen mukaan 2. lokakuuta 2026):MCPServerkorvaaFastMCP:n, kuljetusasetukset siirtyvät metodeihinrun()taistreamable_http_app(), ja todellisen isäntänimen alla julkaistun sovelluksen on ilmoitettava kyseinen isäntänimi (transport_security). Tämä on myös Mistral SDK:n vaatima versio:mistralai[agents]-lisäosa vaatiimcp>=2.2.0,<3.0. Lähteet: Mitä uutta versiossa v2 · Migraatio-opas · Käyttöönotto ja skaalaus.
MCP-työkalun anatomia
MCP-työkalu näyttää Python-funktiolta, mutta mallin näkökulmasta se ei ole sellainen. Se on neliosainen sopimus: nimi, kuvaus, JSON-syöteskeema ja logiikan suorittava käsittelijä. Malli ei koskaan näe koodiasi – se näkee vain tämän sopimuksen. Täydellisesti toteutettu työkalu, jota on kuvattu huonosti, ei koskaan käynnisty, tai se käynnistyy väärään aikaan. Siksi sopimuksen laatu määrittää palvelimen tehokkuuden paljon enemmän kuin toteutuksen laatu.
Mitä dekorattori rakentaa puolestasi
MCPServer rakentaa tämän sopimuksen automaattisesti funktion allekirjoituksesta ja docstringistä. Kirjoitat tavallista Pythonia:
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 malli vastaanottaa tämän:
{
"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"]
}
}
Vertaa näitä kahta lohkoa rivi riviltä: jokainen tyyppimerkintä muuttuu JSON-tyypiksi, jokainen oletusarvo muuttuu default-kentäksi, jokainen Args-osion rivi muuttuu parametrin kuvaukseksi, ja ainoa argumentti, jolla ei ole oletusarvoa, päätyy required-listaan. Toisin sanoen kaikki, mitä jätät pois docstringistä, katoaa kokonaan sopimuksesta.
Nimeäminen ja sitten kuvaaminen
Työkalun nimi on funktion nimi, ja malli käyttää sitä ensimmäisenä vihjeenä. Toimintaa kuvaava verbi followed by selkeä objekti ei jätä tilaa epäselvyydelle, kun taas yleinen tai tekninen nimi pakottaa mallin arvailemaan:
# Hyvä: toimintaverbi + selkeä objekti
@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: ...
# Huono: epämääräinen, monitulkintainen, tekninen
@app.tool()
def process(data: str) -> str: ... # Liian epämääräinen
@app.tool()
def handle_request(req: str) -> str: ... # LLM:lle käsittämätön
@app.tool()
def db_query(sql: str) -> str: ... # Liian tekninen
Docstring ottaa sitten ohjat ja muodostaa koko palvelimesi kriittisimmän osan. Sen on vastattava kolmeen kysymykseen tässä järjestyksessä: milloin työkalua käytetään, mitkä parametrit annetaan niiden muodot ja rajoitukset huomioiden, ja mitä paluuarvosta voi odottaa. Seuraava esimerkki näyttää, miltä tämä näyttää todellisessa tilanteessa:
@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
"""
...
Ensimmäisen rivin jälkeinen kappale on se, mitä amatööri-palvelimilta useimmiten puuttuu. Ilman sitä malli tietää, mitä työkalu tekee, mutta ei sitä, missä tilanteessa se pitäisi käynnistää. Ja ISO 8601 -päiväesimerkki säästää sinut kymmeniltä puheluilta, joissa päivämäärä on muodossa "April 15 at 7:30 PM".
Tyypit, asynkroniset käsittelijät ja validointi
MCPServer kääntää yleiset Python-merkinnät niiden JSON Schema -vastineiksi.
| Python | JSON Schema | Esimerkki |
|---|---|---|
str | string | "text" |
int | integer | 42 |
float | number | 3.14 |
bool | boolean | true |
list[str] | array of string | ["a", "b"] |
dict | object | {"key": "val"} |
Optional[str] | string (nullable) | "text" tai null |
Heti kun työkalu astuu prosessinsa ulkopuolelle – verkkopyyntö, tietokantakysely, etätiedoston luku – ilmoita se async:na. Synkroninen käsittelijä, joka odottaa HTTP-vastausta, tukkii koko palvelimen ja samalla muut käyttäjäsi:
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-skeema rajoittaa tyyppejä, ei arvoja: mikään ei estä mallia lähettämästä 3 000 merkin pituista nimeä tai keksittyä roolia. Siksi validoita aina käsittelijän sisäänmenopisteessä ja palauta viesti, joka kertoo tarvittavan korjauksen:
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}})
Kolmas viesti listaa sallitut arvot. Malli voi sitten korjata itseään ja kutsua työkalua uudelleen sen sijaan, että se luovuttaisi selittämättömän “Invalid role” -virheen edessä.
Paluuarvon hiominen
MCP-työkalu palauttaa aina tekstiä, mutta tämä teksti voi olla jäsenneltyä JSONia, jota malli tulkitsee erittäin hyvin. Näiden kahden paluuarvon kontrasti tiivistää oleellisen:
# Hyvä: jäsennelty, luettava JSON
return json.dumps({
"success": True,
"user": {
"name": "Alice Dupont",
"email": "[email protected]",
"role": "editor",
},
"message": "User created successfully"
}, ensure_ascii=False)
# Huono: raaka data, jota on vaikea käyttää
return "OK:user_id=abc123:status=created"
Suosi aina ihmisen luettavia arvoja sisäisten tunnisteiden sijaan: malli voi käyttää välittömästi nimeä "Alice Dupont" vastauksessaan, kun taas UUID pakottaa tekemään lisäkutsun selvittääkseen, kenestä on kyse. Toisaalta varo liian paisuneita paluuarvoja – viisikymmentä kenttää per tietue täyttää kontekstin lisäämättä arvoa. Oikea refleksi työkalua kirjoittaessa on kysyä itseltäsi, mitä malli tarvitsee kertoakseen käyttäjälle, ja palauttaa vain se.
Keskeiset asiat
@app.tool()-dekorattori generoi automaattisesti parametrien JSON Scheman- Funktion nimi = työkalun nimi (verbi + objekti)
- Docstring on ratkaisevan tärkeä: se ohjaa mallia siitä, milloin ja miten työkalua kutsutaan
- Käytä Pythonin tyyppimerkintöjä skeemaan (str, int, float, bool, list, dict)
- Validoi aina syötteet ja palauta toimintakykyisiä virheilmoituksia
- Palauta jäsennelty JSON, jossa on ihmisen luettavia arvoja