mcp-helmet

用于 MCP 服务器的生产级中间件。包含身份验证、会话、健康检查、优雅停机和传输人体工程学。其可组合中间件的设计灵感源自 Express 的 helmet。

mcp-helmet 封装了官方的 @modelcontextprotocol/sdk，并补全了其缺失的功能：自动传输检测、内容封装、健康检查、优雅停机、会话管理和身份验证中间件。一个包，可组合。按需使用。在几分钟而非几天内从“Hello World”迈向生产环境。

npm install mcp-helmet @modelcontextprotocol/sdk zod

对等依赖： @modelcontextprotocol/sdk ^1.29.0，zod ^3.22.0 或 ^3.25 (v4)。zod-to-json-schema 是 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 服务器以及官方 SDK 中的 320 个 GitHub Issue。发现三个反复出现的模式：

1. 每个服务器都在重写相同的 20-40 行设置代码。 传输选择、内容封装、错误格式化、信号处理。SDK 提供了构建块，而这提供了完整的房屋。

2. 本地运行正常的服务器在生产环境中崩溃。 Docker 容器在一次响应后退出，Kubernetes Pod 丢失会话，没有供负载均衡器探测的健康检查。在最近的一项调查中，52% 的远程 MCP 端点是失效的。

3. 没人搞得懂身份验证。 “如何在工具内部访问 Bearer 令牌？”是两个 SDK 仓库中最常被问到的问题。

mcp-helmet 通过可组合的中间件解决了这些问题，在不替换 SDK 的前提下对其进行了扩展。

状态

v0.1.0-alpha — 功能完整。 目前已实现：

• ✅ createServer() 支持自动内容封装（字符串、对象、Content[]）

• ✅ 通过 MCP_TRANSPORT 环境变量自动检测传输方式

• ✅ Zod v3 + v4 兼容性垫片

• ✅ 可组合的中间件系统 (server.use(mw))

• ✅ healthCheck() 中间件

• ✅ gracefulShutdown() 中间件

• ✅ 基于 AsyncLocalStorage 的 getAuthContext()，支持 bearerAuth() 和 apiKeyAuth() 中间件

• ✅ rateLimiter() 中间件（滑动窗口，基于 IP 或 Key，标准的 429 响应头）

• ✅ npx mcp-helmet init CLI 脚手架 + Docker 模板

v0.1.0 稳定版将在 alpha 周期经过 30 天以上的实际使用后发布。v0.2 已列入 ROADMAP：基于 Redis 的会话存储、结构化日志中间件、通过 FastMCP 插件实现的 Python 移植。

与官方 SDK 的关系

mcp-helmet 不是一个分支、替代品或重写。它是一个便利层。

SDK 是一个对等依赖。你需要自行引入版本。如果 SDK 添加了重叠的功能，工具包中间件将变为一个轻量级的透传层。

要求

• Node.js 20+

• @modelcontextprotocol/sdk ^1.29.0

• TypeScript 5.4+ (推荐，非必须)

• Zod 3.22+ 或 3.25+ (通过 zod/v4 子路径支持 v4)

贡献

欢迎提交 PR 和 Issue。请参阅 CONTRIBUTING.md 了解设置、测试和 PR 规范。

安全

请参阅 SECURITY.md 了解负责任的披露路径。

许可证

MIT