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

Ailtireacht Freastalaí MCP Saincheaptha

Ceacht 10 as 14 Nuashonraithe 2 Samhain 2026 Forbróir
Ar an leathanach seo
  1. Dearadh freastalaí MCP táirgeachta
  2. Do fhráma oibre a roghnú
  3. Struchtúr tionscadail a mhaireann
  4. An pointe iontrála: server.py
  5. Modúl uirlisí amháin in aghaidh an fhearainn
  6. Cumraíocht láraithe
  7. Earráidí is féidir leis an tsamhail a léamh
  8. Le stát nó gan stát
  9. 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 dtí run() nó streamable_http_app(), agus caolfaidh feidhmchlár atá nochtaithe faoi óstainn realta an t-óstainn 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ú.

Dearadh freastalaí MCP táirgeachta

Oireann samhlacha MCP do chomhad daichead líne, agus is minic go leor é sin chun foireann a chur ina choinne. Ach athraíonn gach rud nuair a bhogann tú chuig úsáid sa saol mór: glaonn daoine éagsúla ar an bhfreastalaí, méadaíonn uirlisí, athraíonn cumraíocht thar thimpeallachtaí, agus éiríonn an comhad aonair dodhéanta a chothabháil. Clúdaíonn an ceacht seo na cinntí ailtireachta a chuireann cosc ort an balla sin a bhualadh: fráma oibre a roghnú, do thionscadal a struchtúrú, cumraíocht agus earráidí a bhainistiú, agus roghnú idir freastalaithe stáit agus gan stát.

Do fhráma oibre a roghnú

I bPython, is é an rang **MCPServer** ón SDK oifigiúil (roimhe seo FastMCP`) an uirlis chaighdeánach. Nochtann sé API bunaithe ar mhaisitheoirí agus láimhseálann sé an prótacal MCP duit, mar sin tagann freastalaí chun beatha i dtrí líne:

from mcp.server.mcpserver import MCPServer

app = MCPServer(
    "My Server",
    instructions="MCP Server for project management",
)

Tá SDK MCP oifigiúil foilsithe ag Anthropic d’fhoirne JavaScript agus TypeScript. Tá an loighic inchomparáide cé go bhfuil difríocht sa chomhréir:

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

const server = new McpServer({
  name: "My Server",
  version: "1.0.0",
});

Braitheann an rogha níos lú ar acmhainní agus níos mó ar an éiceachóras ina bhfaighidh do fhreastalaí a chuid sonraí. Beidh freastalaí a dhéanann ceist ar bhunachar sonraí trí SQLAlchemy nó a athúsáideann scripteanna próiseála atá ann cheana i bPython go nádúrtha; fanfaidh freastalaí atá tacaithe ag feidhmchlár Express atá ann cheana i TypeScript. Déanann an tábla thíos achoimre ar na difríochtaí praiticiúla.

CritéarMCPServer (Python SDK)MCP SDK (TypeScript)
AibíochtAn-aibíAibí
Maisitheoirí@app.tool()Modh server.tool()
Iompar HTTPInghabháilte (FastAPI)Inghabháilte (Express)
PobalMórMór

Struchtúr tionscadail a mhaireann

Scarann an struchtúr eolaire molta ceithre fhreagracht: an rud a fheiceann an tsamhail (tools/), an rud a dhéanann rochtain ar shonraí (services/), an rud a rialaíonn rochtain (auth/), agus an rud a chuireann síos ar an timpeallacht (config.py, .env).

my-mcp-server/
├── server.py              # Pointe iontrála FastAPI + suiteáil MCP
├── tools/
│   ├── __init__.py
│   ├── project_tools.py   # Uirlisí bainistíochta tionscadal
│   ├── file_tools.py      # Uirlisí bainistíochta comhad
│   └── search_tools.py    # Uirlisí cuardaigh
├── services/
│   ├── __init__.py
│   ├── database.py        # Rochtain ar bhunachar sonraí
│   └── external_api.py    # Glaochanna API seachtracha
├── auth/
│   ├── __init__.py
│   └── middleware.py       # Meánbhogearraí fíordheimhniúcháin
├── config.py              # Cumraíocht (athróga timpeallachta)
├── Dockerfile             # Coimeádánú
├── requirements.txt       # Spleáchais Python
├── .env                   # Athróga timpeallachta (gan a chur faoi rialú)
└── tests/
    ├── test_tools.py
    └── test_integration.py

Tá toradh díreach, concreideach ag an scaradh seo: ní bhíonn SQL ná glaochanna HTTP i d’uirlisí a thuilleadh, ach bailíochtú agus tarmligean chuig seirbhís. Is féidir leat loighic gnó a thástáil gan dul trí MCP, agus bunachair shonraí a athrú gan teagmháil a dhéanamh le doiciméad amháin a fheiceann an tsamhail.

An pointe iontrála: server.py

Ní dhéanann an príomhchomhad ach comhpháirteanna a chur le chéile: cruthaíonn sé an feidhmchlár FastAPI, cruachaíonn sé meánbhogearraí, agus suiteálann sé gach freastalaí MCP ar a bhealach féin.

# server.py
"""MCP server entry point."""

from contextlib import asynccontextmanager

import os

from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware
from mcp.server.transport_security import TransportSecuritySettings
from tools.project_tools import project_mcp
from tools.search_tools import search_mcp
from auth.middleware import AuthMiddleware

# Caithfidh gach freastalaí MCP a bhainisteoir seisiún a thosú
@asynccontextmanager
async def lifespan(app: FastAPI):
    async with project_mcp.session_manager.run(), search_mcp.session_manager.run():
        yield

# Feidhmchlár FastAPI
api = FastAPI(
    title="My MCP Server",
    version="1.0.0",
    lifespan=lifespan,
)

# CORS do chliaint ghréasáin
api.add_middleware(
    CORSMiddleware,
    allow_origins=["*"],
    allow_methods=["*"],
    allow_headers=["*"],
)

# Meánbhogearraí fíordheimhniúcháin
api.add_middleware(AuthMiddleware)

# Óstainn phoiblí faoina seachadtar freastalaithe (seachas sin: 421 Invalid Host header)
PUBLIC_HOST = os.environ.get("MCP_PUBLIC_HOST", "localhost")
security = TransportSecuritySettings(allowed_hosts=[PUBLIC_HOST, f"{PUBLIC_HOST}:*"])

# Suiteáil freastalaithe MCP ar bhealaí ar leith
api.mount("/projects", project_mcp.streamable_http_app(transport_security=security))
api.mount("/search", search_mcp.streamable_http_app(transport_security=security))

# Leathanach baile (roghnach ach úsáideach)
@api.get("/")
async def root():
    return {
        "service": "My MCP Server",
        "version": "1.0.0",
        "endpoints": {
            "projects": "/projects/mcp",
            "search": "/search/mcp",
        },
    }

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(api, host="0.0.0.0", port=8000)

Ligeann suiteáil ar bhealaí ar leith do úsáideoirí an fearann amháin atá uathu a chumasú: ceanglaíonn duine atá ag lorg doiciméadúcháin le /search/mcp gan uirlisí bainistíochta tionscadal a thairiscint dó. Maidir leis an leathanach baile, dealraíonn sé trivial go dtí go n-iarrann comhghleacaí ort an URL pointe deiridh cruinn; freagraíonn sé duitse agus feidhmíonn sé mar sheiceáil sláinte.

Modúl uirlisí amháin in aghaidh an fhearainn

Dearaíonn gach comhad sa fhillteán tools/ a réad MCPServer féin agus grúpáil sé uirlisí ón bhfeidhmeannas céanna. Seo mar a bhreathnaíonn an modúl bainistíochta tionscadal, a allmhairíodh níos luaithe ag server.py:

# tools/project_tools.py
"""MCP tools for project management."""

from mcp.server.mcpserver import MCPServer
from services.database import db

project_mcp = MCPServer(
    "Project Manager",
    instructions="Tools for project and task management",
)

@project_mcp.tool()
async def create_project(name: str, description: str = "") -> str:
    """Creates a new project.

    Args:
        name: Project name (2-100 characters)
        description: Project description (optional)

    Returns:
        JSON with created project details
    """
    project = await db.projects.create(name=name, description=description)
    return project.to_json()

@project_mcp.tool()
async def list_projects(status: str = "active") -> str:
    """Lists projects by status.

    Args:
        status: Filter by status: active, archived, all (default: active)

    Returns:
        JSON with list of projects
    """
    projects = await db.projects.list(status=status)
    return projects.to_json()

Tabhair faoi deara cé chomh gairid is atá coirp na feidhme: dhá líne amháin in aghaidh na feidhme, toisc go bhfuil rochtain ar shonraí ina chónaí i services/database.py. Ní dhéanann an uirlis ach cur síos ar a conradh leis an tsamhail agus tarmligean a dhéanamh.

Cumraíocht láraithe

Caithfidh aon luach a athraíonn idir do mheaisín agus an freastalaí táirgeachta teacht ón timpeallacht, riamh ón gcód. Bailíonn comhad amháin config.py na hathróga seo lena luachanna réamhshocraithe:

# config.py
"""MCP server configuration."""

import os
from dataclasses import dataclass

@dataclass
class Config:
    api_token: str = os.getenv("MCP_API_TOKEN", "")
    database_url: str = os.getenv("DATABASE_URL", "sqlite:///data.db")
    debug: bool = os.getenv("DEBUG", "false").lower() == "true"
    port: int = int(os.getenv("PORT", "8000"))
    max_results: int = int(os.getenv("MAX_RESULTS", "50"))

config = Config()

Léiríonn an paraiméadar max_results tairbhe an chur chuige seo: an lá a thugann uirlis ró-thorthaí ar ais agus go sáthaíonn sé comhthéacs na samhla, coigeartaíonn tú athróg timpeallachta agus déanann tú atosú, gan cód a ath-imlonnú.

Earráidí is féidir leis an tsamhail a léamh

Ní insíonn eisceacht Python a phléascann suas go tobann aon rud don tsamhail: feiceann sí teip gan tuiscint a bheith aici cén fáth, agus is minic a dhéanann sí iarracht arís ar an mbealach céanna. Ina ionad sin, caighdeánaigh formáid freagartha earráide sainráite le cód agus teachtaireacht.

import json

def error_response(message: str, code: str = "error") -> str:
    """Formats a standardized error message."""
    return json.dumps({
        "success": False,
        "error": {"code": code, "message": message}
    }, ensure_ascii=False)

@project_mcp.tool()
async def get_project(project_id: str) -> str:
    """Retrieves project details by ID."""
    try:
        project = await db.projects.get(project_id)
        if not project:
            return error_response(f"Project {project_id} not found", "not_found")
        return project.to_json()
    except Exception as e:
        return error_response(f"Server error: {str(e)}", "server_error")

Tá an difríocht cinntitheach sa chomhrá. Ag tabhairt aghaidh ar not_found, tuigeann an tsamhail go gcaithfidh sí liosta tionscadal a dhéanamh ar dtús chun an t-ID ceart a aimsiú; ag tabhairt aghaidh ar eisceacht thostach, éiríonn sí as nó téann sí i lúb.

Le stát nó gan stát

Coinníonn freastalaí le stát faisnéis idir glaochanna: bunachar sonraí sa chuimhne, seisiúin úsáideora, comhthéacs oibre. Is coitianta é seo do fhreastalaithe bainistíochta, cosúil leis an mbainisteoir tasc ón gceacht roimhe seo. Déileálann freastalaí gan stát le gach iarratas go neamhspleách, gan aon rud a mheabhrú—molta do ríomh nó claochlú íon, agus ag ligean do scálú cothrománach ós rud é gur féidir le haon samplach aon iarratas a láimhseáil. Cumasaíonn SDK v2 é seo le paraiméadar feidhmchláir HTTP (ní thugtar don tógálaí a thuilleadh). Tabhair faoi deara nach bhfuil a fhios ag an bprótacal féin faoi sheisiúin a thuilleadh leis an sonraíocht 2026-07-28: ní bhaineann an socrú seo ach le cliant a idirbheartaíonn leagan níos luaithe den phrótacal.

app = MCPServer("Stateless Server")

# Tugtar an socrú nuair a thógtar an feidhmchlár HTTP
mcp_app = app.streamable_http_app(stateless_http=True)

Déan an cheist seo a chinneadh sula scríobhann tú d’uirlisí, ní ina dhiaidh: ciallaíonn bogadh ó fhreastalaí le stát go freastalaí gan stát gach stát a bhogadh chuig bunachar sonraí seachtrach, rud a athscríobhann cuid mhaith den chód.

Príomhphointí

  • Scar do chuid uirlisí ina móidil théamacha i bhfillteán tools/
  • Úsáid FastAPI mar bhonn HTTP, suiteáil freastalaithe MCP ar bhealaí tiomnaithe, agus tabhair a lifespan dóibh
  • Láraitigh cumraíocht trí athróga timpeallachta
  • Caighdeánaigh formáidí freagartha earráide ionas gur féidir leis an tsamhail iad a úsáid
  • Roghnaigh idir le stát (bainistíocht sonraí) agus gan stát (ríomh íon)
  • Cuir leathanach baile / leis chun do phointí deiridh MCP a dhoiciméadú