Cur chun Feidhme Uirlisí: Scéama JSON agus Lámhaireoirí
Ar an leathanach seo
Nuashonraithe an 2 Samhain, 2026 — MCP Python SDK v2. Leanann an cúrsa seo anois leagan 2 den SDK
mcp(2.3.0 ón 2 Deireadh Fómhair, 2026): téannMCPServerin ionadFastMCP, bogann socruithe iompair gorun()nóstreamable_http_app(), agus caolfaidh feidhmchlár atá nochtaithe faoi óstainm fíor an t-óstainm sin a dhearbhú (transport_security). Is é seo an leagan a éilíonn an Mistral SDK freisin: éilíonn an breiseánmistralai[agents]go mbeadhmcp>=2.2.0,<3.0ann. Foinse: Cad atá nua i v2 · Treoir Imirce · Deighilt & scálú.
Anatamaíocht Uirlis MCP
Cosúil le feidhm Python atá d’uirlis MCP, ach ó thaobh an mhúnla de, ní feidhm í. Conradh ceithre chuid atá ann: ainm, cur síos, scéama ionchuir JSON, agus lámhaireoir a fhorghníomhaíonn an loighic. Ní fheiceann an múnla do chód riamh—ní fheiceann sé ach an conradh seo. Má tá uirlis curtha i bhfeidhm go foirfe ach go bhfuil cur síos bocht uirthi, ní ghlaofar uirthi choíche, nó glaofar uirthi ag an am mícheart. Dá bhrí sin, cinneann cáilíocht an chonartha éifeachtúlacht an fhreastalaí i bhfad níos mó ná cáilíocht an chur i bhfeidhme.
Cad a Thógann an Maisitheoir Duit
Tógann MCPServer an conradh seo go huathoibríoch ó shíniú do fheidhme agus ón doicstring. Scríobhann tú gnáth-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
...
Agus faigheann an múnla é seo:
{
"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"]
}
}
Déan comparáid idir an dá bhloc líne ar líne: aistríonn gach nóta cineáil go cineál JSON, aistríonn gach luach réamhshocraithe go réimse default, aistríonn gach líne sa rannán Args go cur síos paraiméadair, agus críochnaíonn an t-aon argóint gan luach réamhshocraithe i required. I mbeagán focal, imíonn aon rud a fhágann tú ar lár sa doicstring go hiomlán ón gconradh.
Ainmniú, agus ansin Cur síos
Is é ainm na feidhme ainm na huirlise, agus úsáideann an múnla é mar a chéad leid. Fágann briathar gníomhaíochta agus oibiacht shoiléir gan aon débhríocht, ach cuireann ainm ginearálta nó teicniúil iallach ar an múnla tuairimíocht a dhéanamh:
# Maith: briathar gníomhaíochta + oibiacht shoiléir
@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: ...
# Droch: doiléir, débhríoch, teicniúil
@app.tool()
def process(data: str) -> str: ... # Ró-dhoiléir
@app.tool()
def handle_request(req: str) -> str: ... # Dodhéanta don LLM a thuiscint
@app.tool()
def db_query(sql: str) -> str: ... # Ró-theicniúil
Ansin glacann an doicstring seilbh agus is í an píosa is criticiúla d’fhreastalaí ar bith atá agat. Caithfidh sí freagra a thabhairt ar thrí cheist san ord seo: cathain an uirlis seo a úsáid, cé na paraiméadair le soláthar lena bhformáid agus a srianta, agus cad atá le súil leis ar ais. Taispeánann an sampla seo a leanas conas a bhreathnaíonn sé seo i gcás fíorshaol:
@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
"""
...
Is é an mír a leanann an chéad líne an rud is minice a bhíonn in easnamh ar fhreastalaithe amaitéaracha. Gan é, tá a fhios ag an múnla cad a dhéanann an uirlis ach ní fios cén staid ina gcuirfear i ngníomh í. Agus sábhálfaidh an sampla dáta ISO 8601 dosaen glaonna uait le "April 15 at 7:30 PM".
Cineálacha, Lámhaireoirí Asincronacha, agus Bailíochtú
Aistríonn MCPServer nótaí coitianta Python go dtí a gcoibhéisí Scéama JSON.
| Python | Scéama JSON | Sampla |
|---|---|---|
str | string | "text" |
int | integer | 42 |
float | number | 3.14 |
bool | boolean | true |
list[str] | array de string | ["a", "b"] |
dict | object | {"key": "val"} |
Optional[str] | string (in-nialasaithe) | "text" nó null |
Chomh luath agus a théann uirlis thar a próiseas féin—glao líonra, ceist bunachair sonraí, léamh comhaid i gcéin—declaraigh mar async í. Cuireann lámhaireoir sioncronach atá ag fanacht le freagra HTTP bac ar an bhfreastalaí ar fad, agus ar do chuid úsáideoirí eile mar aon leis:
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
Srianaíonn an scéama JSON cineálacha, ní luachanna riamh: ní choscann sé ar an múnla ainm 3,000 carachtar nó ról bréagach a sheoladh. Dá bhrí sin, déan bailíochtú i gcónaí ag pointe iontrála an lámhaireora, agus seol teachtaireacht a léiríonn an ceartúchán atá ag teastáil:
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}})
Liostaíonn an tríú teachtaireacht na luachanna ceadaithe. Ansin is féidir leis an múnla é féin a cheartú agus glao a chur ar an uirlis arís, in ionad géilleadh os comhair earráide “Invalid role” gan aon mhíniú.
Snas a chur ar an Luach Fillte
Filleann uirlis MCP téacs i gcónaí, ach is féidir leis an téacs sin a bheith ina JSON struchtúrtha, rud a thuigeann an múnla go han-mhaith. Tugann an chodarsnacht idir an dá fhilleadh seo achoimre ar na bunphointí:
# Maith: JSON struchtúrtha, inléite
return json.dumps({
"success": True,
"user": {
"name": "Alice Dupont",
"email": "[email protected]",
"role": "editor",
},
"message": "User created successfully"
}, ensure_ascii=False)
# Droch: sonraí amha atá deacair a úsáid
return "OK:user_id=abc123:status=created"
Roghnaigh luachanna atá inléite ag an duine i gcónaí thar aitheantóirí inmheánacha: is féidir leis an múnla "Alice Dupont" a úsáid láithreach ina fhreagra, ach cuireann UUID iallach air glao breise a dhéanamh chun a fháil amach cé faoi atá sé ag caint. Ar an láimh eile, bí ar do chluiche maidir le filltí atá ró-líonta—líonann caoga réimse in aghaidh na taifeada an comhthéacs gan luach a chur leis. Is é an freagra ceart nuair a scríobhann tú uirlis ná fiafraí díot féin cad a bheidh ag teastáil ón múnla chun inis don úsáideoir, agus gan ach é sin a fhilleadh.
Príomhphointí
- Gineann an maisitheoir
@app.tool()an Scéama JSON do pharaiméadair go huathoibríoch - Ainm na feidhme = ainm na huirlise (briathar + oibiacht)
- Tá an doicstring ríthábhachtach: treoraíonn sí an múnla maidir le cathain agus conas glao a chur ar an uirlis
- Úsáid nótaí cineáil Python don scéama (str, int, float, bool, list, dict)
- Déan bailíochtú ar ionchuir i gcónaí agus fille earráidí atá ingníomhaithe
- Fill JSON struchtúrtha le luachanna atá inléite ag an duine