Премини към основното съдържание
Български— Изберете език
Меню

Архитектура на персонализиран MCP сървър

Урок 10 от 14 Обновен 2 ноември 2026 г. Програмист
На тази страница
  1. Проектиране на производствен MCP сървър
  2. Избор на ваша рамка (Framework)
  3. Структура на проекта, която издържа
  4. Точката на вход: server.py
  5. Един модул с инструменти на домейн
  6. Централизирана конфигурация
  7. Грешки, които моделът може да прочете
  8. Със състояние или без състояние
  9. Ключови изводи

Обновено на 2 ноември 2026 г. — MCP Python SDK v2. Този курс следва версия 2 на mcp SDK (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 крайни точки