익스프레스 MCP 핸들러

익스프레스-mcp-핸들러

Express 애플리케이션에 MCP(Model Context Protocol)를 통합하기 위한 유틸리티입니다.

특징

상태 저장 핸들러 : 세션 ID와 SSE(서버 전송 이벤트)를 사용하여 장기 세션을 유지합니다.
상태 비저장 핸들러 : 간단하고 일회성 상호작용을 위해 각 요청을 완전히 격리하여 처리합니다.
SSE 핸들러 : 전용 GET 및 POST 엔드포인트를 사용하여 SSE(Server-Sent Events)를 통해 MCP(Model Context Protocol)를 처리합니다.
Express 경로에 직접 연결되는 유연하고 사용하기 쉬운 API입니다.

설치

npm을 통해 설치:

지엑스피1

또는 실:

yarn add express-mcp-handler

피어 종속성

express >= 4.x
@modelcontextprotocol/sdk

용법

패키지에서 핸들러를 가져와 Express 앱에 마운트합니다.

import express from 'express';
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { statefulHandler, statelessHandler } from 'express-mcp-handler';

const app = express();
app.use(express.json());

상태 저장 모드

statefulHandler 사용하여 클라이언트와 서버 간에 재사용 가능한 세션을 설정합니다.

import { randomUUID } from 'node:crypto';

const server = new McpServer({
  name: 'my-server',
  version: '1.0.0',
});

const handlerOptions = {
  sessionIdGenerator: randomUUID,
  onSessionInitialized: (sessionId: string) => {
    console.log(`Session initialized: ${sessionId}`);
  },
  onSessionClosed: (sessionId: string) => {
    console.log(`Session closed: ${sessionId}`);
    // perform cleanup logic here
  },
  onError: (error: Error, sessionId?: string) => {
    console.error(`Error in session ${sessionId}:`, error);
  }
};

app.post('/mcp', statefulHandler(server, handlerOptions));
app.get('/mcp', statefulHandler(server, handlerOptions));
app.delete('/mcp', statefulHandler(server, handlerOptions));

app.listen(3000, () => {
  console.log('Express MCP server running on port 3000');
});

핸들러는 다음을 수행합니다.

첫 번째 요청( mcp-session-id 헤더 없음)에서 새로운 세션을 초기화합니다.
클라이언트가 후속 요청에 포함해야 하는 mcp-session-id 헤더를 반환합니다.
서버에서 클라이언트로 메시지를 푸시하기 위해 서버 전송 이벤트(SSE)를 관리합니다.
닫을 때 세션을 자동으로 정리합니다.

상태 비저장 모드

세션 관리 없이 일회성 요청 처리를 위해 statelessHandler 사용하세요.

app.post('/mcp', statelessHandler());

app.listen(3000, () => {
  console.log('Express Stateless MCP server running on port 3000');
});

각 요청:

새로운 전송 및 서버 인스턴스를 생성합니다.
격리를 보장하고 세션 추적을 사용하지 않습니다.
간단한 환경이나 서버리스 환경에 적합합니다.

SSE 모드

sseHandlers 사용하여 SSE(Server-Sent Events)를 통한 MCP(Model Context Protocol)를 처리합니다.

import { sseHandlers } from 'express-mcp-handler';

// Provide a factory function that returns a fresh McpServer for each SSE connection
const handlers = sseHandlers(serverFactory, {
  onError: (error: Error, sessionId?: string) => {
    console.error(`[SSE][${sessionId || 'unknown'}]`, error);
  },
  onClose: (sessionId: string) => {
    console.log(`[SSE] transport closed: ${sessionId}`);
  },
});

// Mount the SSE endpoints
app.get('/sse', handlers.getHandler);
app.post('/messages', handlers.postHandler);
app.listen(3002, () => {
  console.log('Express MCP SSE server running on port 3002');
});

GET /sse : SSE 스트림을 설정하고 mcp-session-id 헤더를 반환합니다.
POST /messages : 지정된 mcp-session-id 쿼리 매개변수에 대해 SSE 전송을 통해 MCP 메시지를 전송합니다.

API 참조

상태 저장 핸들러

function statefulHandler(
  server: McpServer,
  options: {
    sessionIdGenerator: () => string;
    onSessionInitialized?: (sessionId: string) => void;
    onSessionClosed?: (sessionId: string) => void;
    onError?: (error: Error, sessionId?: string) => void;
    onInvalidSession?: (req: express.Request) => void;
  }
): express.RequestHandler;

서버 : 프로토콜 논리를 처리하는 McpServer 의 인스턴스입니다.
options.sessionIdGenerator : 고유한 세션 ID를 반환하는 함수입니다.
options.onSessionInitialized (선택 사항) : 새로운 세션 ID로 호출되는 콜백입니다.
options.onSessionClosed (선택 사항) : 세션이 닫힐 때 호출되는 콜백입니다.
options.onError (선택 사항) : 오류 발생 시 호출되는 콜백입니다.
options.onInvalidSession (선택 사항) : 유효하지 않은 세션에 액세스했을 때 호출되는 콜백입니다.

statelessHandler

function statelessHandler(
  serverFactory: () => McpServer,
  options?: {
    sessionIdGenerator?: () => string;
    onClose?: (req: express.Request, res: express.Response) => void;
    onError?: (error: Error) => void;
  }
): express.RequestHandler;

serverFactory : 새로운 서버 인스턴스를 반환하는 함수입니다.
options.sessionIdGenerator (선택 사항) : 전송 세션 ID 생성을 재정의합니다.
options.onClose (선택 사항) : 요청/응답 주기가 종료될 때 실행되는 콜백입니다.
options.onError (선택 사항) : 처리 중 오류가 발생하면 실행되는 콜백입니다.

sse핸들러

function sseHandlers(
  serverFactory: ServerFactory,
  options: SSEHandlerOptions
): {
  getHandler: express.RequestHandler;
  postHandler: express.RequestHandler;
};

serverFactory : 각 SSE 연결에 대해 새로운 McpServer 반환하는 팩토리 함수입니다.
options.onError (선택 사항) : 오류 발생 시 호출되는 콜백으로, error 와 선택적 sessionId 수신합니다.
options.onClose (선택 사항) : SSE 세션이 닫힐 때 호출되는 콜백으로 sessionId 받습니다.

개발

git clone https://github.com/jhgaylor/express-mcp-handler.git
cd express-mcp-handler
npm install
npm run build
npm test

테스트 범위

이제 이 프로젝트는 테스트 범위를 크게 개선했습니다.

진술: 86.06%
지점: 79.06%
기능: 88.88%
라인: 85.71%

모든 핸들러 유형에 대한 포괄적인 테스트를 추가했습니다.

상태 비저장 핸들러: 100% 적용 범위
SSE 핸들러: 97.29% 적용
상태 저장 핸들러: 67.34% 적용 범위(개선 진행 중)

모든 변경 사항은 테스트를 위해 Jest를 사용하고, 커버리지 보고를 위해 Codecov를 사용하는 CI/CD 파이프라인을 통해 검증됩니다.

지속적인 통합

이 프로젝트는 지속적인 통합을 위해 GitHub Actions를 사용합니다. 메인 브랜치에 대한 모든 푸시와 풀 리퀘스트는 다음과 같은 작업을 수행합니다.

린트 검사를 실행하세요
프로젝트를 빌드하세요
커버리지로 테스트 실행
Codecov 에 적용 범위 보고서 업로드

이 README 상단의 배지나 GitHub 저장소의 작업 탭 에서 현재 CI 상태를 볼 수 있습니다.

특허

MIT 라이센스

npm에 게시하기

아직 npm에 로그인하지 않았다면 로그인하세요.

npm login

npm에 패키지를 게시합니다(prepublishOnly 빌드가 실행됩니다):

npm publish

새 버전을 범프, 태그 및 푸시하려면 다음을 수행합니다.

npm version patch    # or minor, major
git push origin main --tags

Express MCP Handler

Integrations