mcp-helmet

MCP 서버를 위한 프로덕션 미들웨어. 인증, 세션, 상태 확인, 정상 종료, 전송 인체공학을 제공합니다. Express의 helmet에서 영감을 받은 구성 가능한 미들웨어입니다.

mcp-helmet은 공식 @modelcontextprotocol/sdk를 감싸서 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

healthCheck(), gracefulShutdown(), 선택적 인증, 다단계 Dockerfile 및 타입 체크가 적용된 tsconfig가 포함된 작동하는 MCP 서버를 얻을 수 있습니다. 플래그를 사용하여 특정 기능을 건너뛰거나(--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 토큰 검증을 수행하며, 검증된 주체(principal)는 모든 도구 핸들러 내부에서 사용할 수 있습니다:

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 이슈를 감사했습니다. 세 가지 패턴이 계속해서 나타났습니다:

1. 모든 서버가 동일한 20-40줄의 설정을 다시 작성합니다. 전송 선택, 콘텐츠 래핑, 오류 형식 지정, 신호 처리 등. SDK는 빌딩 블록을 제공하지만, 이 툴킷은 집을 제공합니다.

2. 로컬에서 작동하는 서버가 프로덕션에서 중단됩니다. Docker 컨테이너는 응답 후 종료되고, Kubernetes 파드는 세션을 잃어버리며, 로드 밸런서가 프로빙할 상태 확인 기능이 없습니다. 최근 조사에서 원격 MCP 엔드포인트의 52%가 죽어 있었습니다.

3. 아무도 인증을 구현하는 방법을 모릅니다. "도구 내부에서 Bearer 토큰에 어떻게 접근하나요?"는 두 SDK 저장소 모두에서 가장 많이 묻는 질문입니다.

mcp-helmet은 SDK를 대체하지 않고 확장하는 구성 가능한 미들웨어로 이러한 문제를 해결합니다.

상태

v0.1.0-alpha — 기능 완성. 현재 제공되는 기능:

• ✅ 자동 콘텐츠 래핑(문자열, 객체, Content[])을 지원하는 createServer()

• ✅ MCP_TRANSPORT 환경 변수를 통한 자동 전송 감지

• ✅ Zod v3 + v4 호환성 심(shim)

• ✅ 구성 가능한 미들웨어 시스템 (server.use(mw))

• ✅ healthCheck() 미들웨어

• ✅ gracefulShutdown() 미들웨어

• ✅ AsyncLocalStorage 기반 getAuthContext()를 사용하는 bearerAuth() 및 apiKeyAuth() 미들웨어

• ✅ rateLimiter() 미들웨어 (슬라이딩 윈도우, IP 또는 키 기반, 표준 429 헤더)

• ✅ npx mcp-helmet init CLI 스캐폴더 + Docker 템플릿

v0.1.0 안정 버전은 알파 주기가 30일 이상의 실제 사용 사례를 거친 후 출시될 예정입니다. v0.2는 로드맵에 있습니다: Redis 기반 세션 저장소, 구조화된 로깅 미들웨어, FastMCP 플러그인을 통한 Python 포트.

공식 SDK와의 관계

mcp-helmet은 포크, 대안 또는 대체품이 아닙니다. 편의를 위한 계층입니다.

SDK는 피어 의존성입니다. 직접 버전을 지정해야 합니다. SDK가 중복되는 기능을 추가하면 툴킷 미들웨어는 얇은 패스스루(pass-through)가 됩니다.

요구 사항

• Node.js 20+

• @modelcontextprotocol/sdk ^1.29.0

• TypeScript 5.4+ (권장, 필수 아님)

• Zod 3.22+ 또는 3.25+ (zod/v4 하위 경로를 통한 v4)

기여

PR과 이슈는 언제나 환영합니다. 설정, 테스트 및 PR 규칙은 CONTRIBUTING.md를 참조하세요.

보안

책임 있는 공개 경로는 SECURITY.md를 참조하세요.

라이선스

MIT