mcp-helmet

Промышленное промежуточное ПО для серверов MCP. Аутентификация, сессии, проверки работоспособности, корректное завершение работы, эргономика транспорта. Компонуемое промежуточное ПО, идейно заимствованное из helmet для Express.

mcp-helmet дополняет официальный @modelcontextprotocol/sdk тем, чего в нем нет: автоматическое определение транспорта, обертки контента, проверки работоспособности, корректное завершение работы, управление сессиями и промежуточное ПО для аутентификации. Один пакет. Компонуемый. Отключайте то, что вам не нужно. Переходите от «hello world» к продакшену за минуты, а не дни.

npm install mcp-helmet @modelcontextprotocol/sdk zod

Peer-зависимости: @modelcontextprotocol/sdk ^1.29.0, zod ^3.22.0 или ^3.25 (v4). zod-to-json-schema является опциональной peer-зависимостью для пользователей Zod v3.

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

Самый быстрый способ — использовать генератор проектов:

npx mcp-helmet init my-server --transport http --auth bearer
cd my-server
npm install
npm run dev

Вы получите работающий сервер MCP с healthCheck(), gracefulShutdown(), опциональной аутентификацией, многоэтапным Dockerfile и tsconfig с проверкой типов. Используйте флаги, чтобы пропустить части (--no-docker, --no-health и т. д.), или настройте их позже.

Или подключите вручную:

import { createServer } from "mcp-helmet";
import { z } from "zod";

const server = createServer({ name: "hello", version: "1.0.0" });

server.tool("greet", { name: z.string() }, async ({ name }) => {
  return `Hello, ${name}!`;
});

await server.start();

Вот и все. Никакой настройки транспорта, создания массивов контента или обработчиков сигналов. Запустите его:

# Local development (stdio, the default)
npx tsx src/index.ts

# Production (HTTP)
MCP_TRANSPORT=http PORT=3000 node dist/index.js

Тот же код, оба режима.

Аутентификация в 6 строк

Проверка Bearer-токена, при этом проверенный субъект доступен внутри любого обработчика инструментов:

import { createServer, bearerAuth, getAuthContext } from "mcp-helmet";

const server = createServer({ name: "secure", version: "1.0.0" });

server.use(bearerAuth({
  verify: async (token) => {
    const claims = await verifyJwt(token); // your call
    return { user: claims.sub, scopes: claims.scope?.split(" ") ?? [] };
  },
}));

server.tool("whoami", {}, async () => {
  const auth = getAuthContext();
  return { user: auth?.user, scopes: auth?.scopes };
});

await server.start();

Сигнатура обработчика инструментов с одним аргументом остается прежней — getAuthContext() считывает данные из AsyncLocalStorage, поэтому это работает с любой глубины асинхронной цепочки.

Почему это существует

Мы проанализировали 30 промышленных серверов MCP и 320 тикетов на GitHub в официальных SDK. Постоянно повторялись три паттерна:

1. Каждый сервер переписывает одни и те же 20-40 строк настройки. Выбор транспорта, обертка контента, форматирование ошибок, обработка сигналов. SDK дает вам строительные блоки; это дает вам готовый дом.

2. Серверы, работающие локально, ломаются в продакшене. Docker-контейнеры завершаются после одного ответа, поды Kubernetes теряют сессии, нет проверки работоспособности для балансировщиков нагрузки. 52% удаленных эндпоинтов MCP в недавнем исследовании были нерабочими.

3. Никто не может разобраться с аутентификацией. «Как мне получить доступ к Bearer-токену внутри моего инструмента?» — самый частый вопрос в обоих репозиториях SDK.

mcp-helmet решает эти проблемы с помощью компонуемого промежуточного ПО, которое расширяет SDK, не заменяя его.

Статус

v0.1.0-alpha — функциональность завершена. В настоящее время реализовано:

• ✅ createServer() с автоматической оберткой контента (строка, объект, Content[])

• ✅ Автоматическое определение транспорта через переменную окружения MCP_TRANSPORT

• ✅ Шим совместимости Zod v3 + v4

• ✅ Система компонуемого промежуточного ПО (server.use(mw))

• ✅ Промежуточное ПО healthCheck()

• ✅ Промежуточное ПО gracefulShutdown()

• ✅ Промежуточное ПО bearerAuth() и apiKeyAuth() с getAuthContext() на основе AsyncLocalStorage

• ✅ Промежуточное ПО rateLimiter() (скользящее окно, на основе IP или ключа, стандартные заголовки 429)

• ✅ CLI-генератор npx mcp-helmet init + шаблон Docker

Стабильная версия v0.1.0 выйдет после того, как альфа-цикл пройдет 30+ дней реального использования. v0.2 находится в ROADMAP: хранилище сессий на базе Redis, промежуточное ПО для структурированного логирования, порт для Python через плагин FastMCP.

Как это соотносится с официальным SDK

mcp-helmet — это не форк, не альтернатива и не замена. Это слой удобства.

SDK является peer-зависимостью. Вы используете свою версию. Если SDK добавляет функции, которые пересекаются, промежуточное ПО набора инструментов становится тонким прокси-слоем.

Требования

• Node.js 20+

• @modelcontextprotocol/sdk ^1.29.0

• TypeScript 5.4+ (рекомендуется, не обязательно)

• Zod 3.22+ или 3.25+ (v4 через подпуть zod/v4)

Участие в разработке

PR и тикеты приветствуются. См. CONTRIBUTING.md для ознакомления с настройкой, тестированием и соглашениями по PR.

Безопасность

См. SECURITY.md для получения информации о порядке ответственного раскрытия информации.

Лицензия

MIT