Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Implimentazzjoni tal-Għodod: JSON Schema u Handlers

Lezzjoni 11 / 14 Aġġornat 2 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. L-Anatomija ta’ Għodda MCP
  2. X’Jibni d-Dekoratur Għalik
  3. L-Isem, Imbagħad id-Deskrizzjoni
  4. Tipi, Handlers Asinkroni, u Validazzjoni
  5. Irraffina l-Valur Irritornat
  6. Punti Ewlenin

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): MCPServer tissostitwixxi FastMCP, is-settings tat-trasport jiċċaqalqu lejn run() jew streamable_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-extra mistralai[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.

PythonJSON SchemaEżempju
strstring"text"
intinteger42
floatnumber3.14
boolbooleantrue
list[str]array ta’ string["a", "b"]
dictobject{"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