# Архитектурный справочник: Разработка локальных MCP-серверов на Python

> **Назначение:** Технический справочник и стандарт архитектуры для создания высокопроизводительных, типобезопасных локальных серверов по спецификации Model Context Protocol (MCP) с использованием Python SDK (`FastMCP` / `MCPServer`).

---

## 1. Архитектура и эволюция SDK (FastMCP vs MCPServer)

В экосистеме Python MCP произошла важная унификация:
- **Официальный Python SDK v2.x+ (`mcp[cli]`):** Высокоуровневый декларативный класс `FastMCP` был стандартизирован и переименован в `mcp.server.MCPServer` (импорты из `mcp.server.mcpserver.*`). При этом API декораторов (`@mcp.tool()`, `@mcp.resource()`, `@mcp.prompt()`) полностью сохранился.
- **Официальный Python SDK v1.x:** Использовал путь `from mcp.server.fastmcp import FastMCP, Context`.
- **Автономный пакет `fastmcp` (by Prefect):** Параллельная легковесная реализация со схожими паттернами декораторов.

*Данный справочник ориентирован на современный канонический стандарт SDK v2 (с указанием обратной совместимости для v1).*

---

## 2. Инициализация и жизненный цикл (`lifespan`)

### 2.1. Концепция управления жизненным циклом
Серверы MCP не должны пересоздавать тяжелые ресурсы (пулы подключений к БД, сессии `httpx.AsyncClient`, кэши, модели) на каждый вызов инструмента. 
Управление глобальными ресурсами осуществляется через асинхронный контекстный менеджер (`@asynccontextmanager`), аналогично паттерну Lifespan в ASGI/FastAPI.

Жизненный цикл выполняется **один раз**:
1. **Startup (до yield):** Инициализируются клиенты, открываются пулы соединений.
2. **Yield:** Предоставляет типизированный контейнер состояния (`AppContext`), доступный каждому вызову инструмента через `Context`.
3. **Shutdown (в блоке `finally`):** Корректно закрываются коннекторы, сокеты и сбрасываются буферы.

### 2.2. Реализация: переиспользуемый `httpx.AsyncClient`

```python
"""
server.py — Декларативный MCP-сервер с управлением жизненным циклом HTTP-клиента
"""
from collections.abc import AsyncIterator
from contextlib import asynccontextmanager
from dataclasses import dataclass
import httpx

# В SDK v2: MCPServer. В v1: from mcp.server.fastmcp import FastMCP as MCPServer
from mcp.server import MCPServer
from mcp.server.mcpserver import Context


@dataclass
class AppContext:
    """Типизированный контейнер общего состояния сервера."""
    http_client: httpx.AsyncClient


@asynccontextmanager
async def app_lifespan(server: MCPServer) -> AsyncIterator[AppContext]:
    """
    Фаза Startup/Shutdown сервера.
    Гарантирует единую сессию HTTP с connection pooling и корректное закрытие.
    """
    # --- STARTUP ---
    limits = httpx.Limits(max_keepalive_connections=20, max_connections=100)
    timeout = httpx.Timeout(connect=5.0, read=30.0, write=10.0, pool=5.0)
    
    async with httpx.AsyncClient(
        base_url="https://api.example.com",
        limits=limits,
        timeout=timeout,
        headers={"User-Agent": "FastMCP-LocalServer/1.0"}
    ) as client:
        try:
            # Yield типизированного контекста
            yield AppContext(http_client=client)
        finally:
            # --- SHUTDOWN ---
            # httpx.AsyncClient закрывается автоматически по выходу из блока async with
            pass


# Инициализация сервера с привязкой lifespan
mcp = MCPServer(
    name="ProductionService",
    instructions="Локальный сервер для интеграции с внешними API и базами данных.",
    lifespan=app_lifespan
)
```

---

## 3. Проектирование инструментов (`@mcp.tool()`)

Инструменты (Tools) — функции, которые вызывающая LLM выбирает и выполняет удаленно. 

### 3.1. Ключевые архитектурные правила
1. **Type Hints = JSON Schema:** Сигнатура функции напрямую транслируется в JSON Schema 2020-12 при вызове клиентом `tools/list`. Все аргументы без значений по умолчанию автоматически становятся `required`.
2. **Docstrings = Описание для LLM:** Первая строка докстринга и её тело определяют, когда и как LLM будет выбирать данный инструмент. Описание должно быть лаконичным, но детерминированным.
3. **Pydantic Validation:** Использование моделей Pydantic (`BaseModel`) и `Annotated[T, Field(...)]` позволяет жестко валидировать границы входных параметров (регулярные выражения, диапазоны `ge`/`le`, описания полей) еще до исполнения тела функции.
4. **Асинхронность:** Рекомендуется объявлять функции как `async def` для неблокирующего ввода-вывода. Для чистых CPU-операций допустим синхронный `def`.
5. **Метаданные и аннотации безопасности (`ToolAnnotations`):** Подсказки хосту о характере операции:
   - `read_only_hint=True`: инструмент не модифицирует состояние среды (безопасен для автовыполнения без подтверждения пользователя).
   - `open_world_hint=True`: инструмент взаимодействует с внешним миром / интернетом, результаты недетерминированы.
   - `destructive_hint=True`: инструмент выполняет необратимые операции (удаление, перезапись).

### 3.2. Входная валидация и структурированный выход (`Structured Output`)

```python
from typing import Annotated, Literal
from pydantic import BaseModel, Field
from mcp.server import MCPServer
from mcp.server.mcpserver import Context
from mcp.types import ToolAnnotations


class UserFilter(BaseModel):
    """Модель входных параметров со строгой валидацией."""
    department: Literal["engineering", "product", "sales"] = Field(
        description="Отдел компании для фильтрации"
    )
    min_tenure_years: int = Field(
        default=1,
        ge=0,
        le=50,
        description="Минимальный стаж работы в годах"
    )


class UserProfile(BaseModel):
    """Модель отдельной записи."""
    user_id: str
    full_name: str
    email: str
    active: bool


class UserSearchResponse(BaseModel):
    """
    Модель структурированного вывода (Structured Output).
    SDK автоматически генерирует output_schema и раскладывает ответ на два канала:
    1. content (JSON-текст для чтения языковой моделью).
    2. structured_content (десериализованный объект для приложения-хоста).
    """
    total_found: int
    items: list[UserProfile]


@mcp.tool(
    name="search_directory",
    title="Search Employee Directory",
    annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False)
)
async def search_directory(
    filter_params: UserFilter,
    limit: Annotated[int, Field(ge=1, le=100, description="Лимит возвращаемых записей")] = 20,
    ctx: Context[AppContext] = None  # Внедрение контекста не попадает в схему инструмента для LLM
) -> UserSearchResponse:
    """
    Поиск сотрудников компании по отделу и критериям стажа.
    Возвращает список профилей сотрудников и общее число найденных совпадений.
    """
    # Доступ к синглтону HTTP-клиента из lifespan
    client = ctx.request_context.lifespan_context.http_client

    response = await client.get(
        "/directory/search",
        params={
            "dept": filter_params.department,
            "min_tenure": filter_params.min_tenure_years,
            "limit": limit
        }
    )
    response.raise_for_status()
    raw_data = response.json()

    users = [
        UserProfile(
            user_id=item["id"],
            full_name=item["name"],
            email=item["email"],
            active=item["is_active"]
        )
        for item in raw_data.get("users", [])
    ]

    return UserSearchResponse(total_found=len(users), items=users)
```

---

## 4. Контекст, логирование и транспорт `stdio`

### 4.1. Принцип изоляции `stdout` в `stdio`-транспорте
Транспорт `stdio` работает через стандартные файловые дескрипторы:
- `sys.stdin`: входной поток JSON-RPC сообщений от хоста.
- `sys.stdout`: **строго зарезервирован** под протокольный обмен JSON-RPC.
- `sys.stderr`: диагностический поток сервера.

> **КРИТИЧЕСКОЕ ПРАВИЛО:**  
> **Категорически запрещено использовать `print()` в коде сервера и используемых библиотеках.**  
> Любая неэкранированная строка в `stdout` приводит к рассинхронизации JSON-RPC фреймов и разрыву сессии клиентом.

### 4.2. Стандартный логгер Python (`logging`)
SDK автоматически инициализирует `logging.basicConfig(stream=sys.stderr)` с уровнем, заданным в конфигурации сервера. Все сообщения стандартного логгера уходят в `stderr` и не засоряют протокол.

```python
import logging
from mcp.server import MCPServer

# Инициализация модуля логгера
logger = logging.getLogger(__name__)

# Уровень логирования можно передать в конструктор MCPServer
mcp = MCPServer("LoggedServer", log_level="DEBUG")

@mcp.tool()
async def process_item(item_id: str) -> str:
    """Обработка элемента с диагностическим логированием."""
    # Безопасный лог: пишется в stderr
    logger.debug("Начало обработки элемента id=%s", item_id)
    
    # ... логика ...
    
    logger.info("Элемент id=%s успешно обработан", item_id)
    return f"Processed {item_id}"
```

### 4.3. Возможности объекта `Context`
Объект `Context` (из `mcp.server.mcpserver`) автоматически инжектируется рантаймом, если параметр помечен типом `Context` (он исключается из генерируемой схемы аргументов тулза).

Возможности `Context`:
- **Отчет о прогрессе длительных задач:**
  ```python
  await ctx.report_progress(progress=current_step, total=total_steps)
  ```
- **Протокольные логи на сторону клиента (Logging notifications):**
  ```python
  await ctx.info("Информационное сообщение для хоста")
  await ctx.error("Ошибка в контексте выполнения задачи")
  ```
- **Чтение внутренних ресурсов сервера из инструмента:**
  ```python
  contents = await ctx.read_resource("config://settings")
  ```
- **Доступ к метаданным сессии и lifespan:**
  ```python
  state = ctx.request_context.lifespan_context
  client_id = ctx.request_context.client_id if hasattr(ctx.request_context, "client_id") else None
  ```

---

## 5. Корректная обработка ошибок (Error Handling Strategy)

При сбоях внутри инструментов критично разделять **ошибки уровня выполнения логики (бизнес-ошибки)** и **ошибки уровня протокола**.

| Тип исключения | Поведение в MCP | Что получает LLM | Применение |
| :--- | :--- | :--- | :--- |
| **`ToolError`**<br>(`mcp.server.mcpserver.exceptions`) | Возвращает результат вызова с флагом `is_error=True`. RPC-запрос считается **успешным**. | Текст ошибки в блоке `content`. Модель видит причину и **может скорректировать запрос**. | Неверный ID ресурса, сущность не найдена, превышена квота пользователя, конфликт данных. |
| **`MCPError`**<br>(`mcp.shared.exceptions`) | Срывает RPC-запрос кодом ошибки JSON-RPC (`code=-32602` и др.). Результата нет. | Модель **ничего не получает**. Хост-приложение перехватывает системный сбой. | Нарушение протокола, недействительные заголовки, фатальные сбои инфраструктуры. |
| **Необработанное исключение** (`ValueError`, `Exception`) | Перехватывается SDK; возвращает `is_error=True` с нейтральным сообщением об ошибке без утечки секретов. | Общее сообщение `Error executing tool <name>`. | Непредвиденные баги кода (traceback пишется только в `stderr`). |

### 5.1. Паттерн самокоррекции LLM (Self-Correction)

> **АНТИПАТТЕРН:**  
> Возвращать строку вида `return "Ошибка: файл не найден"` — в этом случае `is_error=False`, хост и модель считают вызов успешным, что ломает логику рассуждений агента.

```python
from mcp.server import MCPServer
from mcp.server.mcpserver.exceptions import ToolError

mcp = MCPServer("DatabaseTool")

RECORDS = {"order_101": {"status": "shipped"}, "order_102": {"status": "pending"}}


@mcp.tool()
async def get_order_status(order_id: str) -> str:
    """Получение текущего статуса заказа по его ID."""
    if not order_id.startswith("order_"):
        # Позволяет LLM увидеть формат и исправить аргумент на следующем шаге
        raise ToolError(
            f"Некорректный формат order_id: '{order_id}'. ID должен начинаться с префикса 'order_' (например: 'order_101')."
        )
    
    order = RECORDS.get(order_id)
    if not order:
        raise ToolError(
            f"Заказ с идентификатором '{order_id}' не найден в базе данных. Проверьте номер и повторите запрос."
        )
        
    return f"Статус заказа {order_id}: {order['status']}"
```

---

## 6. Запуск сервера и конфигурация хостов

### 6.1. Точка входа в коде
Сервер запускается блокирующим вызовом `.run()`. Для локальных серверов по умолчанию используется транспорт `stdio`:

```python
# server.py

if __name__ == "__main__":
    # Запуск сервера через stdio транспорт по умолчанию
    mcp.run()
    # Альтернатива для явного указания: mcp.run(transport="stdio")
```

### 6.2. Команды запуска и разработки
Для управления зависимостями и окружением рекомендуется инструмент `uv`:
- **Интерактивный дебаг через MCP Inspector:**
  ```bash
  uv run --with "mcp[cli]" mcp dev server.py
  ```
- **Прямой тестовый запуск:**
  ```bash
  uv run --with "mcp[cli]" mcp run server.py
  ```

### 6.3. Шаблоны конфигурации подключения к MCP-клиентам

Хост запускает сервер как изолированный дочерний подпроцесс и соединяется с его stdin/stdout. Рекомендуется использовать `uv run --with ...` с абсолютными путями, чтобы исключить зависимость от системного `$PATH` или активного виртуального окружения.

#### Для Claude Desktop / Cursor / Antigravity (`mcpServers` формат):
Файл: `claude_desktop_config.json` / `settings.json`

```json
{
  "mcpServers": {
    "my_local_service": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp[cli]",
        "--with",
        "httpx",
        "--with",
        "pydantic",
        "mcp",
        "run",
        "C:\\Users\\Daniil\\VS_Code\\Trash\\server.py"
      ],
      "env": {
        "API_KEY": "secret-token-here",
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}
```

#### Для расширений VS Code (Cline, Roo Code и др.):
```json
{
  "servers": {
    "my_local_service": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp[cli]",
        "mcp",
        "run",
        "C:/Users/Daniil/VS_Code/Trash/server.py"
      ]
    }
  }
}
```

---

## 7. Чек-лист готовности архитектуры (Production Checklist)

1. [ ] **Lifespan:** Сетевые сессии (`httpx`), соединения с БД и пулы инициализируются в `@asynccontextmanager` и передаются через `AppContext`.
2. [ ] **Clean Stdout:** В кодовой базе нет ни одного вызова `print()`; системное логирование переведено на `logging.getLogger` (пишет в `sys.stderr`).
3. [ ] **Strict Typing:** Все аргументы тулзов снабжены type hints и валидаторами `Field(description=..., ge=..., le=...)`.
4. [ ] **Docstrings:** У каждого тулза описано назначение и семантика аргументов для планировщика LLM.
5. [ ] **Structured Outputs:** Тулзы с нетривиальным ответом возвращают Pydantic-модели с типизированными полями.
6. [ ] **Tool Annotations:** На операции без побочных эффектов установлена аннотация `read_only_hint=True`.
7. [ ] **Business Errors:** Логические сбои и ненайденные сущности выбрасывают `ToolError` с пояснением для модели, а не возвращают строку ошибки.
8. [ ] **Entrypoint Guard:** Запуск обернут в `if __name__ == "__main__": mcp.run()`.
