Αρχιτεκτονική ενός προσαρμοσμένου διακομιστή MCP
Σε αυτήν τη σελίδα
Ενημερώθηκε στις 2 Νοεμβρίου 2026 — MCP Python SDK v2. Αυτό το μάθημα ακολουθεί πλέον την έκδοση 2 του SDK
mcp(2.3.0 στις 2 Οκτωβρίου 2026): τοMCPServerαντικαθιστά τοFastMCP, οι ρυθμίσεις μεταφοράς μεταφέρονται στοrun()ή στοstreamable_http_app(), και μια εφαρμογή που εκτίθεται υπό πραγματικό όνομα host πρέπει να δηλώνει αυτό το όνομα host (transport_security). Αυτή είναι επίσης η έκδοση που απαιτείται από το Mistral SDK: το πρόσθετοmistralai[agents]απαιτείmcp>=2.2.0,<3.0. Πηγές: Τι νέο υπάρχει στο v2 · Οδηγός Μετάβασης · Ανάπτυξη και κλιμάκωση.
Σχεδιασμός ενός διακομιστή MCP για παραγωγή
Ένα πρωτότυπο MCP χωράει σε ένα αρχείο σαράντα γραμμών, και αυτό συχνά αρκεί για να πείσετε μια ομάδα. Η μετάβαση σε πραγματική χρήση αλλάζει τα πάντα: πολλοί χρήστες καλούν τον διακομιστή, τα εργαλεία πληθαίνουν, η διαμόρφωση διαφέρει ανά περιβάλλον και το ενιαίο αρχείο καθίσταται αδύνατο να συντηρηθεί. Αυτό το μάθημα καλύπτει τις αρχιτεκτονικές αποφάσεις που αποτρέπουν το να χτυπήσετε αυτόν τον τοίχο—επιλογή πλαισίου εργασίας, δομή του έργου σας, διαχείριση διαμόρφωσης και σφαλμάτων, και η απόφαση μεταξύ διακομιστών με κατάσταση (stateful) και χωρίς κατάσταση (stateless).
Επιλογή του πλαισίου εργασίας σας
Στην Python, η κλάση MCPServer από το επίσημο SDK (πρώην FastMCP) είναι το στάνταρ εργαλείο. Εκθέτει ένα API βασισμένο σε διακοσμητές και χειρίζεται το πρωτόκολλο MCP για εσάς, ώστε ένας διακομιστής να αποκτά ζωή σε τρεις γραμμές:
from mcp.server.mcpserver import MCPServer
app = MCPServer(
"My Server",
instructions="MCP Server for project management",
)
Οι ομάδες JavaScript και TypeScript έχουν το επίσημο MCP SDK που δημοσιεύεται από την Anthropic. Η λογική είναι συγκρίσιμη ακόμα και αν η σύνταξη διαφέρει:
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
const server = new McpServer({
name: "My Server",
version: "1.0.0",
});
Η επιλογή εξαρτάται λιγότερο από τις δυνατότητες και περισσότερο από το οικοσύστημα όπου ο διακομιστής σας θα ανακτά τα δεδομένα του. Ένας διακομιστής που κάνει ερωτήματα σε βάση δεδομένων μέσω SQLAlchemy ή επαναχρησιμοποιεί υπάρχοντα σενάρια επεξεργασίας θα είναι φυσικά σε Python· ένας διακομιστής που υποστηρίζεται από μια υπάρχουσα εφαρμογή Express θα παραμείνει σε TypeScript. Ο παρακάτω πίνακας συνοψίζει τις πρακτικές διαφορές.
| Κριτήριο | MCPServer (Python SDK) | MCP SDK (TypeScript) |
|---|---|---|
| Ωριμότητα | Πολύ ώριμο | Ώριμο |
| Διακοσμητές | @app.tool() | Μέθοδος server.tool() |
| Μεταφορά HTTP | Ενσωματωμένη (FastAPI) | Ενσωματωμένη (Express) |
| Κοινότητα | Μεγάλη | Μεγάλη |
Μια δομή έργου που αντέχει
Η συνιστώμενη δομή καταλόγου διαχωρίζει τέσσερις ευθύνες: τι βλέπει το μοντέλο (tools/), τι αποκτά πρόσβαση στα δεδομένα (services/), τι ελέγχει την πρόσβαση (auth/), και τι περιγράφει το περιβάλλον (config.py, .env).
my-mcp-server/
├── server.py # Σημείο εισόδου FastAPI + προσάρτηση MCP
├── tools/
│ ├── __init__.py
│ ├── project_tools.py # Εργαλεία διαχείρισης έργων
│ ├── file_tools.py # Εργαλεία διαχείρισης αρχείων
│ └── search_tools.py # Εργαλεία αναζήτησης
├── services/
│ ├── __init__.py
│ ├── database.py # Πρόσβαση στη βάση δεδομένων
│ └── external_api.py # Κλήσεις εξωτερικών API
├── auth/
│ ├── __init__.py
│ └── middleware.py # Middleware ελέγχου ταυτότητας
├── config.py # Διαμόρφωση (μεταβλητές περιβάλλοντος)
├── Dockerfile # Δημιουργία container
├── requirements.txt # Εξαρτήσεις Python
├── .env # Μεταβλητές περιβάλλοντος (δεν καταχωρούνται)
└── tests/
├── test_tools.py
└── test_integration.py
Αυτός ο διαχωρισμός έχει μια άμεση, συγκεκριμένη συνέπεια: τα εργαλεία σας δεν περιέχουν πλέον κλήσεις SQL ή HTTP, μόνο επικύρωση και ανάθεση σε μια υπηρεσία. Μπορείτε έτσι να δοκιμάσετε την επιχειρηματική λογική χωρίς να περάσετε από το MCP, και να αλλάξετε βάσεις δεδομένων χωρίς να αγγίξετε ούτε ένα docstring που βλέπει το μοντέλο.
Το σημείο εισόδου: server.py
Το κύριο αρχείο δεν κάνει τίποτα άλλο από το να συναρμολογεί τα συστατικά: δημιουργεί την εφαρμογή FastAPI, στοιβάζει τα middlewares και προσαρτά κάθε διακομιστή MCP στη δική του διαδρομή.
# server.py
"""Σημείο εισόδου διακομιστή MCP."""
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
# Κάθε διακομιστής MCP πρέπει να ξεκινά τον διαχειριστή συνεδρίας του
@asynccontextmanager
async def lifespan(app: FastAPI):
async with project_mcp.session_manager.run(), search_mcp.session_manager.run():
yield
# Εφαρμογή FastAPI
api = FastAPI(
title="My MCP Server",
version="1.0.0",
lifespan=lifespan,
)
# CORS για πελάτες web
api.add_middleware(
CORSMiddleware,
allow_origins=["*"],
allow_methods=["*"],
allow_headers=["*"],
)
# Middleware ελέγχου ταυτότητας
api.add_middleware(AuthMiddleware)
# Δημόσιο όνομα host υπό το οποίο εξυπηρετούνται οι διακομιστές (διαφορετικά: 421 Invalid Host header)
PUBLIC_HOST = os.environ.get("MCP_PUBLIC_HOST", "localhost")
security = TransportSecuritySettings(allowed_hosts=[PUBLIC_HOST, f"{PUBLIC_HOST}:*"])
# Προσάρτηση διακομιστών MCP σε ξεχωριστές διαδρομές
api.mount("/projects", project_mcp.streamable_http_app(transport_security=security))
api.mount("/search", search_mcp.streamable_http_app(transport_security=security))
# Αρχική σελίδα (προαιρετική αλλά χρήσιμη)
@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)
Η προσάρτηση σε ξεχωριστές διαδρομές επιτρέπει στους χρήστες να ενεργοποιούν μόνο τον τομέα που χρειάζονται: κάποιος που αναζητά τεκμηρίωση συνδέεται στο /search/mcp χωρίς να του προσφέρονται εργαλεία διαχείρισης έργων. Όσο για την αρχική σελίδα, φαίνεται τετριμμένη μέχρι ένας συνάδελφος να ζητήσει την ακριβή URL του endpoint· αυτή απαντά για εσάς και λειτουργεί ως έλεγχος υγείας.
Ένα module εργαλείων ανά τομέα
Κάθε αρχείο στον φάκελο tools/ δηλώνει το δικό του αντικείμενο MCPServer και ομαδοποιεί εργαλεία από τον ίδιο λειτουργικό τομέα. Ορίστε πώς φαίνεται το module διαχείρισης έργων, που εισάγεται νωρίτερα από το server.py:
# tools/project_tools.py
"""Εργαλεία MCP για διαχείριση έργων."""
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:
"""Δημιουργεί ένα νέο έργο.
Args:
name: Όνομα έργου (2-100 χαρακτήρες)
description: Περιγραφή έργου (προαιρετικό)
Returns:
JSON με λεπτομέρειες του δημιουργηθέντος έργου
"""
project = await db.projects.create(name=name, description=description)
return project.to_json()
@project_mcp.tool()
async def list_projects(status: str = "active") -> str:
"""Καταγράφει έργα ανά κατάσταση.
Args:
status: Φίλτρο ανά κατάσταση: active, archived, all (προεπιλογή: active)
Returns:
JSON με λίστα έργων
"""
projects = await db.projects.list(status=status)
return projects.to_json()
Παρατηρήστε πόσο σύντομα είναι τα σώματα των συναρτήσεων: μόλις δύο γραμμές η καθεμία, επειδή η πρόσβαση στα δεδομένα ζει στο services/database.py. Το εργαλείο απλώς περιγράφει τη σύμβασή του στο μοντέλο και αναθέτει την εκτέλεση.
Κεντρικοποιημένη διαμόρφωση
Κάθε τιμή που αλλάζει μεταξύ του μηχανήματός σας και του διακομιστή παραγωγής πρέπει να προέρχεται από το περιβάλλον, ποτέ από τον κώδικα. Ένα ενιαίο αρχείο config.py συγκεντρώνει αυτές τις μεταβλητές με τις προεπιλεγμένες τιμές τους:
# config.py
"""Διαμόρφωση διακομιστή MCP."""
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()
Η παράμετρος max_results illustrates το όφελος αυτής της προσέγγισης: την ημέρα που ένα εργαλείο επιστρέφει πάρα πολλά αποτελέσματα και κορεστεί το context του μοντέλου, προσαρμόζετε μια μεταβλητή περιβάλλοντος και κάνετε επανεκκίνηση, χωρίς να αναπτύξετε ξανά κώδικα.
Σφάλματα που μπορεί να διαβάσει το μοντέλο
Μια εξαίρεση Python που αναδύεται απότομα δεν λέει τίποτα στο μοντέλο: βλέπει μια αποτυχία χωρίς να καταλαβαίνει γιατί, και συχνά επαναλαμβάνει την ίδια ενέργεια. Αντ’ αυτού, τυποποιήστε μια ρητή μορφή απόκρισης σφάλματος με κωδικό και μήνυμα.
import json
def error_response(message: str, code: str = "error") -> str:
"""Μορφοποιεί ένα τυποποιημένο μήνυμα σφάλματος."""
return json.dumps({
"success": False,
"error": {"code": code, "message": message}
}, ensure_ascii=False)
@project_mcp.tool()
async def get_project(project_id: str) -> str:
"""Ανακτά λεπτομέρειες έργου ανά 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")
Η διαφορά είναι καθοριστική στη συνομιλία. Αντιμετωπίζοντας το not_found, το μοντέλο καταλαβαίνει ότι πρέπει πρώτα να καταγράψει τα έργα για να βρει το σωστό ID· αντιμετωπίζοντας μια σιωπηλή εξαίρεση, τα παρατάει ή μπαίνει σε βρόχο.
Με κατάσταση (Stateful) ή χωρίς κατάσταση (Stateless)
Ένας διακομιστής με κατάσταση (stateful) διατηρεί πληροφορίες μεταξύ κλήσεων: βάση δεδομένων στη μνήμη, συνεδρίες χρήστη, context εργασίας. Αυτό είναι σύνηθες για διακομιστές διαχείρισης, όπως ο διαχειριστής εργασιών από το προηγούμενο μάθημα. Ένας διακομιστής χωρίς κατάσταση (stateless) χειρίζεται κάθε αίτημα ανεξάρτητα, χωρίς να θυμάται τίποτα—συνιστάται για καθαρό υπολογισμό ή μετασχηματισμό, και επιτρέπει την οριζόντια κλιμάκωση καθώς οποιοδήποτε instance μπορεί να χειριστεί οποιοδήποτε αίτημα. Το SDK v2 το επιτρέπει αυτό με μια παράμετρο HTTP εφαρμογής (δεν περνάει πλέον στον κατασκευαστή). Σημειώστε ότι με την προδιαγραφή της 28-07-2026, το ίδιο το πρωτόκολλο δεν γνωρίζει πλέον συνεδρίες: αυτή η ρύθμιση αφορά μόνο πελάτες που διαπραγματεύονται μια παλαιότερη έκδοση πρωτοκόλλου.
app = MCPServer("Stateless Server")
# Η ρύθμιση περνά κατά τη δημιουργία της HTTP εφαρμογής
mcp_app = app.streamable_http_app(stateless_http=True)
Αποφασίστε αυτό το ζήτημα πριν γράψετε τα εργαλεία σας, όχι μετά: η μετάβαση από έναν διακομιστή με κατάσταση σε έναν χωρίς κατάσταση σημαίνει τη μεταφορά όλης της κατάστασης σε μια εξωτερική βάση δεδομένων, κάτι που ξαναγράφει ένα σημαντικό μέρος του κώδικα.
Βασικά σημεία
- Διαχωρίστε τα εργαλεία σας σε θεματικά modules σε έναν φάκελο
tools/ - Χρησιμοποιήστε το FastAPI ως βάση HTTP, προσαρτήστε διακομιστές MCP σε αφιερωμένες διαδρομές και περάστε το lifespan τους
- Κεντρικοποιήστε τη διαμόρφωση μέσω μεταβλητών περιβάλλοντος
- Τυποποιήστε τις μορφές απόκρισης σφάλματος ώστε το μοντέλο να μπορεί να τις χρησιμοποιήσει
- Επιλέξτε μεταξύ με κατάσταση (διαχείριση δεδομένων) και χωρίς κατάσταση (καθαρός υπολογισμός)
- Προσθέστε μια αρχική σελίδα
/για να τεκμηριώσετε τα endpoints του MCP σας