Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Arkitettura ta' Server MCP Personalizzat

Lezzjoni 10 / 14 Aġġornat 2 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. Id-disinn ta’ server MCP għall-produzzjoni
  2. L-għażla tal-framework tiegħek
  3. Struttura ta’ proġett li ddum
  4. Il-punt tad-dħul: server.py
  5. Modulu wieħed ta’ għodod għal kull dominju
  6. Konfigurazzjoni ċentralizzata
  7. Żbalji li l-mudell jista’ jaqra
  8. B’stat jew mingħajr stat
  9. Punti Ewlenin

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): MCPServer tissostitwixxi FastMCP, is-settings tat-trasport jiċċaqalqu lejn run() jew streamable_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-extra mistralai[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.

KriterjuMCPServer (Python SDK)MCP SDK (TypeScript)
MaturitàĦafna maturMatur
Dekoraturi@app.tool()Metodu server.tool()
Trasport HTTPIntegrat (FastAPI)Integrat (Express)
KomunitàKbiraKbira

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