Implimentazzjoni tal-Għodod: JSON Schema u Handlers
F'din il-paġna
Aġġornat fit-2 ta’ Novembru, 2026 — MCP Python SDK v2. Dan il-kors issa jsegwi l-verżjoni 2 tal-SDK
mcp(2.3.0 sal-2 ta’ Ottubru, 2026):MCPServertissostitwixxiFastMCP, is-settings tat-trasport jiċċaqalqu lejnrun()jewstreamable_http_app(), u applikazzjoni esposta taħt hostname reali trid tiddikjara dak l-hostname (transport_security). Din hija wkoll il-verżjoni meħtieġa mill-Mistral SDK: l-extramistralai[agents]jeħtieġmcp>=2.2.0,<3.0. Sorsi: X’inhu ġdid f’v2 · Gwida għall-Migrazzjoni · Iddispjega u skala.
L-Anatomija ta’ Għodda MCP
Għodda MCP tidher bħala funzjoni Python, iżda mill-perspettiva tal-mudell, mhijiex waħda. Hija kuntratt f’erba’ partijiet: isem, deskrizzjoni, skema ta’ input JSON, u handler li jesegwixxi l-loġika. Il-mudell qatt ma jara l-kodiċi tiegħek—jara biss dan il-kuntratt. Għodda implimentata perfettament iżda deskritta ħażin qatt ma tiġi msejħa, jew tiġi msejħa fil-ħin żbaljat. Għalhekk, il-kwalità tal-kuntratt tiddetermina l-effettività tas-server ferm aktar mill-kwalità tal-implimentazzjoni.
X’Jibni d-Dekoratur Għalik
MCPServer tibni dan il-kuntratt awtomatikament mill-firma tal-funzjoni tiegħek u d-docstring. Int tikteb 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
...
U l-mudell jirċievi dan:
{
"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"]
}
}
Qabbel iż-żewġ blokki linja b’linja: kull annotazzjoni tat-tip issir tip JSON, kull valur default isir camp default, kull linja fit-taqsima Args issir deskrizzjoni tal-parametru, u l-uniku argument mingħajr valur default jispiċċa f’required. Fi kliem ieħor, kull ma tħalli barra mid-docstring jisparixxi kompletament mill-kuntratt.
L-Isem, Imbagħad id-Deskrizzjoni
L-isem tal-għodda huwa l-isem tal-funzjoni, u l-mudell jużah bħala l-ewwel indizju. Verb ta’ azzjoni segwit minn oġġett ċar ma jħalli l-ebda ambigwità, filwaqt li isem ġeneriku jew tekniku jfurza lill-mudell jissupponi:
# Tajjeb: verb ta' azzjoni + oġġett ċar
@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: ...
# Ħażin: vag, ambigwu, tekniku
@app.tool()
def process(data: str) -> str: ... # Wisq vag
@app.tool()
def handle_request(req: str) -> str: ... # Inkomprensibbli għall-LLM
@app.tool()
def db_query(sql: str) -> str: ... # Wisq tekniku
Id-docstring imbagħad tieħu f’idejha u tikkostitwixxi l-aktar parti kritika tas-server kollu tiegħek. Trid twieġeb tliet mistoqsijiet f’dan l-ordni: meta tuża din l-għodda, liema parametri tipprovdi bil-format u l-vincoli tagħhom, u x’tistenna lura. L-eżempju li ġej juri kif tidher din f’każ reali:
@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-paragrafu wara l-ewwel linja huwa dak li l-aktar spiss jonqos fis-servers dilettanti. Mingħajru, il-mudell jaf x’tagħmel l-għodda iżda mhux f’liema sitwazzjoni għandu jattivalha. U l-eżempju tad-data ISO 8601 iffrankalek għexieren ta’ sejħat b‘“April 15 at 7:30 PM”.
Tipi, Handlers Asinkroni, u Validazzjoni
MCPServer tittraduċi annotazzjonijiet komuni ta’ Python fl-ekwivalenti tagħhom ta’ JSON Schema.
| Python | JSON Schema | Eżempju |
|---|---|---|
str | string | "text" |
int | integer | 42 |
float | number | 3.14 |
bool | boolean | true |
list[str] | array ta’ string | ["a", "b"] |
dict | object | {"key": "val"} |
Optional[str] | string (nullable) | "text" jew null |
Hekk kif għodda toħroġ mill-proċess tagħha—sejħa tan-network, query tad-database, qari ta’ fajl remot—iddikjarahha async. Handler sinkronu li jistenna risposta HTTP jimblokaw is-server kollu, u lill-utenti l-oħra tiegħek flimkien miegħu:
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
L-iskema JSON tillimita t-tipi, qatt il-valuri: xejn ma jipprevjeni lill-mudell milli jibgħat isem ta’ 3,000 karattru jew rwol inventat. Għalhekk, dejjem ivvalida fil-punt tad-dħul tal-handler, u rritorna messaġġ li jindika l-korrezzjoni meħtieġa:
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}})
It-tielet messaġġ jelenka l-valuri permessi. Il-mudell imbagħad jista’ jikkoreġi ruħu u jsejjaħ l-għodda mill-ġdid, minflok ma jirriżenja quddiem żball “Invalid role” mingħajr spjegazzjoni.
Irraffina l-Valur Irritornat
Għodda MCP dejjem tirritorna test, iżda dak it-test jista’ jkun JSON strutturat, li l-mudell jinterpreta tajjeb ħafna. Il-kuntrast bejn dawn iż-żewġ ritorni jgħaqqad l-essenzjali:
# Tajjeb: JSON strutturat u li jinqara
return json.dumps({
"success": True,
"user": {
"name": "Alice Dupont",
"email": "[email protected]",
"role": "editor",
},
"message": "User created successfully"
}, ensure_ascii=False)
# Ħażin: data mhux ipproċessata li hija diffiċli biex tuża
return "OK:user_id=abc123:status=created"
Dejjem ippreferi valuri li jinqraw mill-bniedem fuq identifikaturi interni: il-mudell jista’ juża immedjatament "Alice Dupont" fir-risposta tiegħu, filwaqt li UUID jfurza sejħa addizzjonali biex issir taf min qed jitkellem dwaru. Bil-maqlub, oqgħod attent għal ritorni mimlija żżejjed—ħamsin camp għal kull rekord jimlew il-kuntest mingħajr ma jżidu valur. Ir-rifless it-tajjeb meta tikteb għodda huwa li tistaqsi lilek innifsek x’ikollu bżonn il-mudell biex jgħid lill-utent, u tirritorna biss dak.
Punti Ewlenin
- Id-dekoratur
@app.tool()jiġġenera awtomatikament l-JSON Schema għall-parametri - L-isem tal-funzjoni = isem tal-għodda (verb + oġġett)
- Id-docstring hija kruċjali: tgħid lill-mudell meta u kif isejjaħ l-għodda
- Uża annotazzjonijiet tat-tip ta’ Python għall-iskema (str, int, float, bool, list, dict)
- Dejjem ivvalida l-inputs u rritorna errori li jistgħu jiġu azzjonati
- Irritorna JSON strutturat b’valuri li jinqraw mill-bniedem