MCP-сервер на Python

Шаблон на официальном Python SDK MCP (mcp 1.30.0, FastMCP, транспорт Streamable HTTP). Общие вопросы (публикация, белый список IP, подключение в Trialix, шлюз во внутреннюю сеть) описаны в README выше.

Запуск в Docker

docker build -t mcp-orders .
export MCP_TOKEN="$(openssl rand -hex 32)"
docker run --rm -p 127.0.0.1:8000:8000 -e MCP_TOKEN="$MCP_TOKEN" mcp-orders

Запуск без Docker

Нужен Python 3.13, как в образе.

python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
export MCP_TOKEN="$(openssl rand -hex 32)"
python server.py

Сервер слушает http://0.0.0.0:8000/mcp.

Переменные окружения

Где менять код

• Данные. Класс OrderStore: методы search, get, create. Замените тела методов запросами к своей БД или API, в комментариях есть примеры. Если оставить сигнатуры, инструменты менять не придётся. Для PostgreSQL удобен psycopg, для HTTP API - httpx (он уже стоит вместе с mcp).
• Инструменты. Функции с декоратором @mcp.tool. Описание для модели - строка документации функции, описания параметров - Field(description=...). Схема параметров строится из подсказок типов.
• Чтение или запись. Аргумент annotations: READ (readOnlyHint=True) для инструментов, которые ничего не меняют, WRITE для остальных. Вызов инструмента записи Trialix выполняет только после подтверждения сотрудника.
• Ошибки. raise ToolError("понятный текст"): модель увидит текст и сможет исправить запрос.
• Описание сервера для модели. Параметр instructions у FastMCP.

Инструменты в шаблоне синхронные. Если ваш клиент БД или API асинхронный, объявите функцию как async def, FastMCP поддерживает оба варианта.

Обновление SDK

Шаблон написан на ветке 1.x SDK. В mcp 2.x класс FastMCP переименован в MCPServer и изменились другие API, поэтому при переходе на 2.x сверьтесь с руководством по миграции SDK. Внутри ветки 1.x: поднимите версию mcp в requirements.txt, соберите образ и замените остальные строки выводом docker run --rm mcp-orders pip freeze.