Léim go dtí an príomhábhar
Gaeilge— Roghnaigh teanga
Roghchlár

Cur chun Feidhme Uirlisí: Scéama JSON agus Lámhaireoirí

Ceacht 11 as 14 Nuashonraithe 2 Samhain 2026 Forbróir
Ar an leathanach seo
  1. Anatamaíocht Uirlis MCP
  2. Cad a Thógann an Maisitheoir Duit
  3. Ainmniú, agus ansin Cur síos
  4. Cineálacha, Lámhaireoirí Asincronacha, agus Bailíochtú
  5. Snas a chur ar an Luach Fillte
  6. Príomhphointí

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éann MCPServer in ionad FastMCP, bogann socruithe iompair go run() 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án mistralai[agents] go mbeadh mcp>=2.2.0,<3.0 ann. 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.

PythonScéama JSONSampla
strstring"text"
intinteger42
floatnumber3.14
boolbooleantrue
list[str]array de string["a", "b"]
dictobject{"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