Ailtireacht Freastalaí MCP Saincheaptha
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 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ánmistralai[agents]go mbeadhmcp>=2.2.0,<3.0ann. 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éar | MCPServer (Python SDK) | MCP SDK (TypeScript) |
|---|---|---|
| Aibíocht | An-aibí | Aibí |
| Maisitheoirí | @app.tool() | Modh server.tool() |
| Iompar HTTP | Inghabháilte (FastAPI) | Inghabháilte (Express) |
| Pobal | Mór | Mó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ú