mcp-server-template

Отправная точка для MCP-сервера, доведённая до продакшен‑формы.

Быстрый старт в документации MCP даёт вам работающий инструмент за десять минут. А вот то, что вам предстоит добавить в течение следующих трёх недель — когда этот инструмент уже вызывается чем-то, что вы не контролируете.

@mcp.tool()
def add(a: int, b: int) -> int:
    return a + b          # fine on a laptop

Чего там не хватает — не функций. Дело в том, что происходит, когда инструмент зависает, выбрасывает исключение, возвращает необычный результат или вызывается сорок раз одновременно — и что модели в этот момент позволено видеть.

Решаемая проблема

Вызывающий инструмент MCP — это языковая модель, и это меняет инженерный подход.

• Модель не может прочитать стек‑трейс, но с радостью повторит его вашему пользователю. Так что утёкший traceback — одновременно и бесполезен, и является разглашением.

• У модели свой дедлайн. Зависший инструмент даёт не медленный ответ, а мёртвую беседу.

• Модель не отличает обрезанный результат от полного. Молчаливое переполнение контекста не вызывает ошибку — оно ухудшает ответ, и вы узнаёте об этом от клиента.

• Модель будет повторять, если вы ей позволите. Поэтому «не найдено» и «недоступен вышестоящий сервис» должны быть разными ответами, иначе она будет долбить сервис из‑за записи, которой никогда не было.

Каждая из этих проблем решается один раз и в одном месте, чтобы инструмент, добавленный в пятницу после обеда, получал ту же защиту, что и инструмент, аккуратно написанный в первый день.

Related MCP server: Graft

Что вы получаете

Быстрый старт

git clone https://github.com/muhammadwaqasmbd/mcp-server-template
cd mcp-server-template
make install
make test
make run          # stdio, ready for a desktop MCP client

Или запустите его по сети:

TRANSPORT=streamable-http PORT=8000 python -m mcp_server_template

Подключите к нему десктопный клиент

{
  "mcpServers": {
    "template": {
      "command": "python",
      "args": ["-m", "mcp_server_template"],
      "cwd": "/absolute/path/to/mcp-server-template"
    }
  }
}

Добавление своего инструмента

Напишите функцию. И не нужно ничего остального.

# src/mcp_server_template/tools/orders.py
from ..errors import InvalidInput, UpstreamUnavailable

async def cancel_order(order_id: str) -> dict:
    """Cancel an order. Returns the order's new state."""
    if not order_id.strip():
        raise InvalidInput("order_id must not be empty")     # model can fix this
    ...
    raise UpstreamUnavailable("order service timed out")     # model may retry

Зарегистрируйте её за гардом:

mcp.tool(name="cancel_order", description="Cancel an order by id.")(
    guard.wrap(orders.cancel_order)
)

Теперь у неё есть таймаут, потолок, граница ошибок, усечение и логирование. Вы ничего из этого не пислели.

Выбрасывайте InvalidInput, когда модель может это то исправвить. Выбрасывайте UpstreamUnavailabled, когда повторная попутка других дейстовать. Просто ложные исходы возвращайте обычным способом — отсуствющая запись — это ответ, а не ошибка.

Архитектура

server.py      the ONLY module that imports the MCP SDK
   │
   ├── guard.py          timeout · concurrency · error boundary · truncation · timing
   ├── errors.py         what a model is allowed to see, and secret redaction
   ├── observability.py  JSON logs on stderr, correlation ids
   ├── config.py         validated once at boot, immutable thereafter
   └── tools/            plain functions. No protocol knowledge. No decorators

Стрелка зависимостей указывает в одну сторону: инструменты не знают об MCP, а гард ничего не знает ваших инструментах. Иминно поэтому тесты выполняются за миллисекунды без сервера и поэтому изменение SDK затрагивает ровно один файлся.

Чего эта система намеренно не делает

Честные про границы полезнее длинного списка возможностей.

• Никакой аутификации. Промость stdio-граница ОС является границей безопасности. Если выставляете пот CSV, поставть перед настойщим аутом — SDK это поддерживает, а писать её здесь означало бы подразумет адаптую модель угрроз, которую вы не выбрали.

• Никакой ретраи внутри инструментов. Гард сообщает, является ли сбой повётным; решать, не нужруется ли повторить, должен вызывающий, у которого есть контекст и бюджет.

• Никакого ограничения запросов в наблюдателе. "потолок параллельности ограничивает" все суммарную работу, а не честность в отplicательного под отдельный идентификаторов. Если вам это нужно, сначала нужна идентификация.

• Никакой постоянчик, очереди или планировщика. Серверный сервер, который тихо превращается в выполненur job'ов, — распределительная система, которую никто не проектировал.

• Никакого streaming-вызова частых результатов. Это стоит добавить для долгих инструментов, но опущено, потому что усложния границу ошибок, а большинству а инструментов это не ненужно.

Тестирование

make test

Набор нап ли с фокусе на отобини чтобы — failures. Он проверяет, что зависший инструмент отменяется, что непредвиденные исключения не моя не вытечь; не большого объём результаты отобразяется вилимо, что потолок параллельности держится в десять одновременных вызовов и что блокирующий синхронный инструмент не уморит с гролод, событийный цикл.

Лицензия

MIT — см. LICENSE.

Собрал Muhammad Waqas, который большую часть своего времени занимаатся агентными системами в регулируемых отраслях, где уверенный неправильный ответ — это инцидент, который следует докладывать.