Kohandatud MCP serveri arhitektuur
Sellel lehel
Uuendatud 2. novembril 2026 — MCP Python SDK v2. See kursus järgib nüüd
mcpSDK versiooni 2 (seisuga 2. oktoober 2026 versioon 2.3.0):MCPServerasendabFastMCP-i, transpordi seaded liiguvad meetoditesserun()võistreamable_http_app()ja reaalse hostinime all avaldatud rakendus peab selle hostinime deklareerima (transport_security). See on ka versioon, mida nõuab Mistral SDK: lisapakettmistralai[agents]eeldabmcp>=2.2.0,<3.0. Allikad: Mis on uut v2-s · Migreerimisjuhend · Kasutuselevõtt ja skaleerimine.
Tootevalmis MCP serveri kavandamine
MCP prototüüp mahub neljakümne realisse faili ja sageli piisab sellest meeskonna veenmiseks. Reaalses kasutuses muutub aga kõik: serverit kutsub välja mitu inimest, tööriistu kordub, konfiguratsioon erineb keskkonniti ja üksik fail muutub hooldamatuks. See tund käsitleb arhitektuuriotsuseid, mis hoiavad ära sellise ummiku: raamistiku valik, projekti struktureerimine, konfiguratsiooni ja vigade haldamine ning otsus olekuliste ja olekuta serverite vahel.
Raamistiku valik
Pythonis on ametliku SDK (varem FastMCP) klass MCPServer standardne vahend. See pakub dekoratoritel põhinevat API-d ja haldab MCP protokolli sinu eest, nii et server ärkab ellu kolme reaga:
from mcp.server.mcpserver import MCPServer
app = MCPServer(
"My Server",
instructions="MCP Server for project management",
)
JavaScripti ja TypeScripti meeskondadel on Anthropic’i avaldatud ametlik MCP SDK. Loogika on sarnane, kuigi süntaks erineb:
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
const server = new McpServer({
name: "My Server",
version: "1.0.0",
});
Valik sõltub vähem võimalustest ja rohkem ökosüsteemist, kust sinu server andmeid hangib. Server, mis päringutab andmebaasi SQLAlchemy kaudu või kasutab olemasolevaid töötlemisskripte, on loomupäraselt Pythonis; server, mis toetub olemasolevale Expressi rakendusele, jääb TypeScripti. Allolev tabel võtab kokku praktilised erinevused.
| Kriteerium | MCPServer (Python SDK) | MCP SDK (TypeScript) |
|---|---|---|
| Küpsus | Väga küps | Küps |
| Dekoratorid | @app.tool() | Meetod server.tool() |
| HTTP Transport | Sisseehitatud (FastAPI) | Sisseehitatud (Express) |
| Kogukond | Suur | Suur |
Projektistruktuur, mis kestab
Soovitatud kataloogistruktuur eraldab neli vastutusvaldkonda: mida mudel näeb (tools/), mis pääseb andmetele (services/), mis kontrollib juurdepääsu (auth/) ja mis kirjeldab keskkonda (config.py, .env).
my-mcp-server/
├── server.py # FastAPI sisenemispunkt + MCP ühendamine
├── tools/
│ ├── __init__.py
│ ├── project_tools.py # Projekti haldamise tööriistad
│ ├── file_tools.py # Failihalduse tööriistad
│ └── search_tools.py # Otsingutööriistad
├── services/
│ ├── __init__.py
│ ├── database.py # Andmebaasi juurdepääs
│ └── external_api.py # Väliste API-de kutsumine
├── auth/
│ ├── __init__.py
│ └── middleware.py # Autentimise vahevara
├── config.py # Konfiguratsioon (keskkonnamuutujad)
├── Dockerfile # Konteinerdamine
├── requirements.txt # Pythoni sõltuvused
├── .env # Keskkonnamuutujad (ei salvestata versioonihaldusse)
└── tests/
├── test_tools.py
└── test_integration.py
Sellel eraldusel on otsene ja konkreetne tagajärg: sinu tööriistad ei sisalda enam SQL-i ega HTTP päringuid, vaid ainult valideerimist ja delegeerimist teenusele. Saad testida äriloogikat ilma MCP-d läbimata ja vahetada andmebaase, puutumata ühtegi dokumendistringi, mida mudel näeb.
Sisenemispunkt: server.py
Peamine fail ei tee muud, kui koostab komponendid: loob FastAPI rakenduse, lisab vahevarad ja paigaldab iga MCP serveri oma teele.
# server.py
"""MCP serveri sisenemispunkt."""
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
# Iga MCP server peab käivitama oma sessioonihalduri
@asynccontextmanager
async def lifespan(app: FastAPI):
async with project_mcp.session_manager.run(), search_mcp.session_manager.run():
yield
# FastAPI rakendus
api = FastAPI(
title="My MCP Server",
version="1.0.0",
lifespan=lifespan,
)
# CORS veebiklientidele
api.add_middleware(
CORSMiddleware,
allow_origins=["*"],
allow_methods=["*"],
allow_headers=["*"],
)
# Autentimise vahevara
api.add_middleware(AuthMiddleware)
# Avalik hostinimi, mille all servereid pakutakse (vastasel juhul: 421 Invalid Host header)
PUBLIC_HOST = os.environ.get("MCP_PUBLIC_HOST", "localhost")
security = TransportSecuritySettings(allowed_hosts=[PUBLIC_HOST, f"{PUBLIC_HOST}:*"])
# MCP serverite paigaldamine eraldi teedele
api.mount("/projects", project_mcp.streamable_http_app(transport_security=security))
api.mount("/search", search_mcp.streamable_http_app(transport_security=security))
# Avaleht (valikuline, kuid kasulik)
@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)
Paigaldamine eraldi teedele võimaldab kasutajatel lubada ainult vajalikku domeeni: keegi, kes otsib dokumentatsiooni, ühendub teega /search/mcp ilma, et talle pakutaks projektihalduse tööriistu. Mis puutub avalehte, siis see tundub tühine, kuni kolleeg küsib täpset lõpp-punkti URL-i; see vastab sinu eest ja toimib tervisekontrollina.
Üks tööriistamoodul domeeni kohta
Iga fail kaustas tools/ deklareerib oma MCPServer objekti ja rühmitab sama funktsionaalse domeeni tööriistad. Siin on näide projektihalduse moodulist, mille server.py varem importis:
# tools/project_tools.py
"""MCP tööriistad projektihalduseks."""
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:
"""Loo uus projekt.
Args:
name: Projekti nimi (2–100 tähemärki)
description: Projekti kirjeldus (valikuline)
Returns:
JSON loodud projekti detailidega
"""
project = await db.projects.create(name=name, description=description)
return project.to_json()
@project_mcp.tool()
async def list_projects(status: str = "active") -> str:
"""Loetle projektid staatuse järgi.
Args:
status: Filtreeri staatuse järgi: active, archived, all (vaikimisi: active)
Returns:
JSON projektide loendiga
"""
projects = await db.projects.list(status=status)
return projects.to_json()
Pane tähele, kui lühikesed on funktsioonikehad: vaid kaks rida, sest andmete juurdepääs asub failis services/database.py. Tööriist kirjeldab lihtsalt oma lepingut mudelile ja delegeerib töö edasi.
Tsentraliseeritud konfiguratsioon
Iga väärtus, mis muutub sinu masina ja tooteserveri vahel, peab tulema keskkonnast, mitte koodist. Üksik fail config.py kogub need muutujad koos nende vaikeväärtustega:
# config.py
"""MCP serveri konfiguratsioon."""
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()
Parameeter max_results illustreerib selle lähenemise kasu: päeval, mil tööriist tagastab liiga palju tulemusi ja ummistab mudeli konteksti, kohandad keskkonnamuutujat ja taaskäivitad, ilma koodi uuesti kasutusele võtmata.
Vead, mida mudel saab lugeda
Pythoni erind, mis äkitselt üles kerkib, ei ütle mudelile midagi: ta näeb tõrget, mõistmata põhjust, ja sageli proovib sama uuesti. Selle asemel standardiseeri selge veavastuse formaat koos koodi ja sõnumiga.
import json
def error_response(message: str, code: str = "error") -> str:
"""Vormindab standardiseeritud veateate."""
return json.dumps({
"success": False,
"error": {"code": code, "message": message}
}, ensure_ascii=False)
@project_mcp.tool()
async def get_project(project_id: str) -> str:
"""Hangi projekti detailid ID järgi."""
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")
Erinevus on vestluses otsustav. Silmitsi seisnud not_found-ga, mõistab mudel, et ta peab esmalt loetlema projektid, et leida õige ID; silmitsi vaikiva erindiga, loobub ta või jääb tsüklisse.
Olekuline või olekuta
Olekuline server säilitab teavet väljakutsete vahel: mälusisene andmebaas, kasutajaseansid, töökontekst. See on levinud haldusserverite puhul, nagu eelmises tunnis käsitletud ülesannete haldur. Olekuta server töötleb iga päringut sõltumatult, mitte midagi meeles pidades – soovitatav puhtale arvutusele või teisendusele, võimaldades horisontaalset skaleerimist, kuna iga eksemplar saab hallata iga päringut. SDK v2 võimaldab seda HTTP-rakenduse parameetriga (enam ei anta seda konstruktorile). Pane tähele, et alates 28.07.2026 specifikatsioonist ei tunne protokoll ise enam sessioone: see säte puudutab ainult kliente, mis läbiräägivad varasemat protokolli versiooni.
app = MCPServer("Stateless Server")
# Säte antakse edasi HTTP-rakenduse loomisel
mcp_app = app.streamable_http_app(stateless_http=True)
Otsusta see küsimus enne tööriistade kirjutamist, mitte pärast: liikumine olekuliselt serverilt olekutule tähendab kogu oleku viimist välisesse andmebaasi, mis kirjutab ümber suure osa koodist.
Peamised punktid
- Eralda oma tööriistad teemamooduliteks kaustas
tools/ - Kasuta FastAPI-d HTTP alusena, paigalda MCP serverid pühendatud teedele ja edasta nende lifespan
- Tsentraliseeri konfiguratsioon keskkonnamuutujate kaudu
- Standardiseeri veavastuste formaadid, et mudel saaks neid kasutada
- Vali olekulise (andmehaldus) ja olekuta (puhas arvutus) vahel
- Lisa avaleht
/, et dokumenteerida oma MCP lõpp-punkte