Архитектура на персонализиран MCP сървър
На тази страница
Обновено на 2 ноември 2026 г. — MCP Python SDK v2. Този курс следва версия 2 на
mcpSDK (2.3.0 към 2 октомври 2026 г.):MCPServerзаместваFastMCP, настройките за транспорт се преместват вrun()илиstreamable_http_app(), а приложението, изложено под реално име на хост, трябва да декларира това име (transport_security). Това е също версията, изисквана от Mistral SDK: допълнениетоmistralai[agents]изискваmcp>=2.2.0,<3.0. Източници: Какво е ново във v2 · Ръководство за миграция · Разполагане и мащабиране.
Проектиране на производствен MCP сървър
Прототип на MCP се събира в файл от четиридесет реда и това често е достатъчно, за да убедите екипа. Преминаването към реална употреба обаче променя всичко: множество хора извикват сървъра, инструментите се умножават, конфигурацията варира сред различните среди и единственият файл става невъзможен за поддръжка. Този урок обхваща архитектурните решения, които предотвратяват сблъсъка с тази стена – избор на框架, структуриране на проекта, управление на конфигурацията и грешките, както и изборът между сървъри със и без състояние.
Избор на ваша рамка (Framework)
В 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 # Контейнеризация
├── requirements.txt # Python зависимости
├── .env # Променливи на средата (не се комитват)
└── tests/
├── test_tools.py
└── test_integration.py
Това разделение има директно, конкретно следствие: Вашите инструменти вече не съдържат SQL или HTTP извиквания, а само валидация и делегиране към услуга. Тогава можете да тествате бизнес логиката, без да минавате през MCP, и да сменяте бази данни, без да докосвате нито един docstring, който моделът вижда.
Точката на вход: server.py
Основният файл не прави нищо друго, освен да сглобява компонентите: той създава FastAPI приложението, подрежда middleware слоевете и монтира всеки MCP сървър на собствен маршрут.
# 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
# Всеки 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 за уеб клиенти
api.add_middleware(
CORSMiddleware,
allow_origins=["*"],
allow_methods=["*"],
allow_headers=["*"],
)
# Middleware за автентикация
api.add_middleware(AuthMiddleware)
# Публичен хост, под който се обслужват сървърите (иначе: 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 на крайната точка; тя отговаря вместо Вас и служи като проверка за здраве.
Един модул с инструменти на домейн
Всеки файл в папката tools/ декларира собствен обект MCPServer и групира инструменти от един и същи функционален домейн. Ето как изглежда модулът за управление на проекти, импортиран по-рано от 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()
Забележете колко кратки са телата на функциите: само по два реда всяка, защото достъпът до данни живее в services/database.py. Инструментът просто описва своя контракт пред модела и делегира.
Централизирана конфигурация
Всяка стойност, която се променя между Вашата машина и производствения сървър, трябва да идва от средата, никога от кода. Един единствен файл config.py събира тези променливи със стойностите им по подразбиране:
# 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()
Параметърът max_results илюстрира ползата от този подход: в деня, в който инструмент връща твърде много резултати и насища контекста на модела, Вие коригирате променлива на средата и рестартирате, без да преразполагате код.
Грешки, които моделът може да прочете
Python изключение, което излиза рязко нагоре, не казва нищо на модела: той вижда неуспех, без да разбира защо, и често опитва отново по същия начин. Вместо това, стандартизирайте явен формат на отговор за грешка с код и съобщение.
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")
Разликата е решаваща в разговора. Изправен пред not_found, моделът разбира, че първо трябва да изброи проектите, за да намери правилния ID; изправен пред тихо изключение, той се отказва или влиза в цикъл.
Със състояние или без състояние
Сървър със състояние (stateful) запазва информация между извикванията: база данни в паметта, потребителски сесии, работен контекст. Това е често срещано за сървъри за управление, като мениджъра на задачи от предишния урок. Сървър без състояние (stateless) обработва всяка заявка независимо, без да помни нищо – препоръчително за чисти изчисления или трансформации и позволяващо хоризонтално мащабиране, тъй като всеки екземпляр може да обработи всяка заявка. SDK v2 позволява това чрез параметър на HTTP приложението (вече не се предава на конструктора). Имайте предвид, че със спецификацията от 28 юли 2026 г., самият протокол вече не познава сесиите: тази настройка засяга само клиенти, договарящи по-ранна версия на протокола.
app = MCPServer("Stateless Server")
# Настройката се предава при изграждане на HTTP приложението
mcp_app = app.streamable_http_app(stateless_http=True)
Решете този въпрос, преди да напишете инструментите си, а не след това: преминаването от сървър със състояние към такъв без състояние означава преместване на цялото състояние във външна база данни, което пренаписва добра част от кода.
Ключови изводи
- Разделете инструментите си на тематични модули в папка
tools/ - Използвайте FastAPI като HTTP основа, монтирайте MCP сървърите на специализирани маршрути и предайте техния lifespan
- Централизирайте конфигурацията чрез променливи на средата
- Стандартизирайте форматите на отговор при грешка, за да може моделът да ги използва
- Изберете между със състояние (управление на данни) и без състояние (чисти изчисления)
- Добавете начална страница
/, за да документирате Вашите MCP крайни точки