Arkitettura ta' Server MCP Personalizzat
F'din il-paġna
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):MCPServertissostitwixxiFastMCP, is-settings tat-trasport jiċċaqalqu lejnrun()jewstreamable_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-extramistralai[agents]jeħtieġmcp>=2.2.0,<3.0. Sorsi: X’hemm ġdid f’v2 · Gwida għall-Migrazzjoni · Iddispjega u skala.
Id-disinn ta’ server MCP għall-produzzjoni
Prototip MCP jista’ joqgħod f’file ta’ erbgħin linja, u spiss dan ikun biżżejjed biex tikkonvinċi tim. Imma meta tgħaddi għall-użu fid-dinja reali, kollox jinbidel: ħafna nies isejħu s-server, l-għodod jiżdiedu, il-konfigurazzjoni tvarja bejn l-ambjenti, u l-file wieħed isir impossibbli li tinżamm. Din il-lezzjoni tkopri d-deċiżjonijiet arkitetturali li jipprevjenuk milli tilħaq dak il-ħajt—kif tagħżel framework, tistruttura l-proġett tiegħek, timmaniġġja l-konfigurazzjoni u l-iżbalji, u tiddeċiedi bejn servers b’stat (stateful) u mingħajr stat (stateless).
L-għażla tal-framework tiegħek
F’Python, il-klassi MCPServer mill-SDK uffiċjali (qabel FastMCP) hija l-għodda standard. Tesponi API bbażata fuq dekoraturi u timmaniġġja l-protokoll MCP għalik, hekk server jitqajjem f’tliet linji:
from mcp.server.mcpserver import MCPServer
app = MCPServer(
"My Server",
instructions="MCP Server for project management",
)
It-timijiet ta’ JavaScript u TypeScript għandhom l-SDK MCP uffiċjali ppubblikat minn Anthropic. Il-loġika hija komparabbli anke jekk is-sintassi tkun differenti:
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
const server = new McpServer({
name: "My Server",
version: "1.0.0",
});
L-għażla tiddependi inqas fuq il-kapaċitajiet u aktar fuq l-ekosistema fejn is-server tiegħek se jiġbed id-data tiegħu. Server li jistaqsi database permezz ta’ SQLAlchemy jew jerġa’ juża scripts ta’ pproċessar eżistenti naturalment ikun f’Python; server appoġġjat minn applikazzjoni Express eżistenti jibqa’ f’TypeScript. It-tabella hawn taħt tissorvelja d-differenzi prattiċi.
| Kriterju | MCPServer (Python SDK) | MCP SDK (TypeScript) |
|---|---|---|
| Maturità | Ħafna matur | Matur |
| Dekoraturi | @app.tool() | Metodu server.tool() |
| Trasport HTTP | Integrat (FastAPI) | Integrat (Express) |
| Komunità | Kbira | Kbira |
Struttura ta’ proġett li ddum
L-istruttura tad-direttorju rrakkomandata tissepara erba’ responsabbiltajiet: x’jara l-mudell (tools/), x’jaċċessa d-data (services/), x’jikkontrolla l-aċċess (auth/), u x’jiddeskrivi l-ambjent (config.py, .env).
my-mcp-server/
├── server.py # Punt tad-dħul FastAPI + immuntar MCP
├── tools/
│ ├── __init__.py
│ ├── project_tools.py # Għodod għall-ġestjoni tal-proġetti
│ ├── file_tools.py # Għodod għall-ġestjoni tal-files
│ └── search_tools.py # Għodod ta' tfittxija
├── services/
│ ├── __init__.py
│ ├── database.py # Aċċess għad-database
│ └── external_api.py # Sejħiet għal API esterna
├── auth/
│ ├── __init__.py
│ └── middleware.py # Middleware tal-awtentikazzjoni
├── config.py # Konfigurazzjoni (varjabbli tal-ambjent)
├── Dockerfile # Konteniturizzazzjoni
├── requirements.txt # Dipendenzi Python
├── .env # Varjabbli tal-ambjent (mhux imcommitjati)
└── tests/
├── test_tools.py
└── test_integration.py
Din is-separazzjoni għandha konsegwenza diretta u konkreta: l-għodod tiegħek ma fihomx aktar sejħiet SQL jew HTTP, biss validazzjoni u delegazzjoni lil servizz. B’hekk tista’ tittestja l-loġika tan-negozju mingħajr ma tgħaddi mill-MCP, u tbiddel databases mingħajr ma tmiss dokumentazzjoni waħda li jara l-mudell.
Il-punt tad-dħul: server.py
Il-file prinċipali ma jagħmel xejn ħlief jgħaqqad il-komponenti: joħloq l-applikazzjoni FastAPI, jistackja l-middlewares, u jimmonta kull server MCP fuq ir-rotta tiegħu stess.
# 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
# Kull server MCP irid jibda l-session manager tiegħu
@asynccontextmanager
async def lifespan(app: FastAPI):
async with project_mcp.session_manager.run(), search_mcp.session_manager.run():
yield
# Applikazzjoni FastAPI
api = FastAPI(
title="My MCP Server",
version="1.0.0",
lifespan=lifespan,
)
# CORS għall-klijenti web
api.add_middleware(
CORSMiddleware,
allow_origins=["*"],
allow_methods=["*"],
allow_headers=["*"],
)
# Middleware tal-awtentikazzjoni
api.add_middleware(AuthMiddleware)
# Hostname pubbliku li taħtu jservu s-servers (inkella: 421 Invalid Host header)
PUBLIC_HOST = os.environ.get("MCP_PUBLIC_HOST", "localhost")
security = TransportSecuritySettings(allowed_hosts=[PUBLIC_HOST, f"{PUBLIC_HOST}:*"])
# Immonta s-servers MCP fuq rotot distinti
api.mount("/projects", project_mcp.streamable_http_app(transport_security=security))
api.mount("/search", search_mcp.streamable_http_app(transport_security=security))
# Paġna tad-dar (opzjonali iżda utli)
@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)
L-immuntar fuq rotot distinti jħalli lill-utenti jattivaw biss id-dominju li għandhom bżonn: xi ħadd li qed ifittex dokumentazzjoni jikkonnettja ma’ /search/mcp mingħajr ma jiġu offruti għodod ta’ ġestjoni tal-proġetti. Għall-paġna tad-dar, tidher trivjali sakemm kollega jistaqsik għall-URL eżatt tal-endpoint; din twieġeb għalik u sservi bħala kontroll tas-saħħa.
Modulu wieħed ta’ għodod għal kull dominju
Kull file fil-folder tools/ jiddikjara l-oġġett MCPServer tiegħu stess u jiġbor flimkien għodod mill-istess dominju funzjonali. Hekk tidher il-modulu tal-ġestjoni tal-proġetti, importat qabel minn 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()
Innota kemm huma qosra l-korpi tal-funzjonijiet: biss żewġ linji kull waħda, għax l-aċċess għad-data jgħix f’services/database.py. L-għodda sempliċiment tiddeskrivi l-kuntratt tagħha lill-mudell u tiddelega.
Konfigurazzjoni ċentralizzata
Kwalunkwe valur li jinbidel bejn il-magna tiegħek u s-server tal-produzzjoni għandu jiġi mill-ambjent, qatt mill-kodiċi. File wieħed config.py jiġbor dawn il-varjabbli bil-valuri default tagħhom:
# 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()
Il-parametru max_results juri l-benefiċċju ta’ dan l-approċċ: il-jum li għodda tirritorna wisq riżultati u tissatura l-kuntest tal-mudell, taġġusta varjabbli tal-ambjent u terġa’ tistarta, mingħajr ma terġa’ tiddispjega l-kodiċi.
Żbalji li l-mudell jista’ jaqra
Eċċezzjoni Python li titla’ f’daqqa waħda ma tgħid xejn lill-mudell: jara falliment mingħajr ma jifhem għaliex, u spiss jerġa’ jipprova bl-istess mod. Minflok, standardizza format ta’ rispons ta’ żball espliċitu b’kodiċi u messaġġ.
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")
Id-differenza hija deċiżiva fil-konversazzjoni. Meta jiffaċċja not_found, il-mudell jifhem li l-ewwel irid jelenka l-proġetti biex isib l-ID it-tajjeb; meta jiffaċċja eċċezzjoni siekta, jirriżenja jew idur f’loop.
B’stat jew mingħajr stat
Server b’stat (stateful) iżomm informazzjoni bejn is-sejħiet: database fil-memorja, sessjonijiet tal-utent, kuntest tax-xogħol. Dan huwa komuni għas-servers ta’ ġestjoni, bħall-maniġer tal-kompiti mil-lezzjoni preċedenti. Server mingħajr stat (stateless) jittratta kull talba b’mod indipendenti, mingħajr ma jiftakar xejn—rakkomandat għal komputazzjoni pura jew trasformazzjoni, u jippermetti skalar orizzontali peress li kwalunkwe istanza tista’ tittratta kwalunkwe talba. L-SDK v2 jippermetti dan b’parametru tal-applikazzjoni HTTP (li ma jgħaddix aktar lill-konstruttur). Innota li bis-speċifikazzjoni tal-28 ta’ Lulju, 2026, il-protokoll innifsu ma jafx aktar is-sessjonijiet: dan is-setting jikkonċerna biss klijenti li qed jinnegozjaw verżjoni aktar bikrija tal-protokoll.
app = MCPServer("Stateless Server")
# Is-setting jgħaddi meta tinbena l-applikazzjoni HTTP
mcp_app = app.streamable_http_app(stateless_http=True)
Iddeċiedi din il-mistoqsija qabel ma tikteb l-għodod tiegħek, mhux wara: li tgħaddi minn server b’stat għal wieħed mingħajr stat ifisser li tmexxi l-istat kollu lejn database esterna, li tikteb mill-ġdid parti kbira mill-kodiċi.
Punti Ewlenin
- Separa l-għodod tiegħek f’moduli tematiċi f’folder
tools/ - Uża FastAPI bħala l-bażi HTTP, immonta s-servers MCP fuq rotot dedikati, u għaddi l-lifespan tagħhom
- Iċċentralizza l-konfigurazzjoni permezz ta’ varjabbli tal-ambjent
- Standardizza l-formati tar-rispons tal-iżbalji biex il-mudell ikun jista’ jużahom
- Agħżel bejn b’stat (ġestjoni tad-data) u mingħajr stat (komputazzjoni pura)
- Żid paġna tad-dar
/biex tiddokumenta l-endpoints MCP tiegħek