익스프레스 MCP 핸들러

익스프레스-mcp-핸들러

Express 애플리��이션과 MCP(Model Context Protocol)를 통합하기 위한 미들웨어로, LLM과 도구 간의 원활한 통신을 지원합니다.

모델 컨텍스트 프로토콜(MCP)이란 무엇입니까?

모델 컨텍스트 프로토콜(MCP) 은 대규모 언어 모델(LLM)을 외부 데이터 소스 및 도구와 통합하기 위한 개방형 프로토콜입니다. AI 비서가 표준화된 인터페이스를 통해 실시간 데이터에 접근하고, 작업을 실행하고, 다양한 서비스와 상호 작용할 수 있도록 지원합니다.

특징

상태 저장 핸들러 : 세션 ID와 SSE(서버 전송 이벤트)를 사용하여 일회성 요청을 처리하거나 장기 세션을 유지할 수 있습니다.
상태 비저장 핸들러 : 간단하고 일회성 상호작용을 위해 각 요청을 완전히 격리하여 처리합니다.
SSE 핸들러 : 전용 GET 및 POST 엔드포인트를 사용하여 SSE(Server-Sent Events)를 통해 MCP(Model Context Protocol)를 처리합니다.
Type-Safe API : 안정적인 통합을 위해 TypeScript로 구축되었습니다.
유연한 구성 : 사용자 정의 가능한 오류 처리, 세션 관리 및 라이프사이클 후크.
Express 통합 : 미들웨어 패턴을 사용하여 Express 경로에 직접 연결됩니다.

설치

npm을 통해 설치:

지엑스피1

또는 실:

yarn add express-mcp-handler

또는 pnpm:

pnpm add express-mcp-handler

피어 종속성

이 패키지에는 다음과 같은 피어 종속성이 필요합니다.

express >= 4.0.0
@modelcontextprotocol/sdk >= 1.10.2
zod >= 3.0.0

아직 설치하지 않았다면 설치하세요.

npm install express @modelcontextprotocol/sdk zod

빠른 시작

시작하는 데 도움이 되는 기본적인 예는 다음과 같습니다.

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

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

// Create a factory function that returns a new McpServer instance for each request
const serverFactory = () => new McpServer({
  name: 'my-mcp-server',
  version: '1.0.0',
});

// Mount the stateless handler
app.post('/mcp', statelessHandler(serverFactory));

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

용법

Express-mcp-handler는 다양한 사용 사례에 맞게 세 가지 핸들러 유형을 제공합니다.

상태 저장 모드

statefulHandler 사용하면 클라이언트와 서버 간에 재사용 가능한 세션을 설정할 수 있으며, 이는 여러 상호작용에서 컨텍스트를 유지하는 데 이상적입니다.

import express from 'express';
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { statefulHandler } from 'express-mcp-handler';
import { randomUUID } from 'node:crypto';

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

// Create an MCP server instance
const server = new McpServer({
  name: 'my-server',
  version: '1.0.0',
});

// Configure handler options
const handlerOptions = {
  sessionIdGenerator: randomUUID, // Function to generate unique session IDs
  onSessionInitialized: (sessionId: string) => {
    console.log(`Session initialized: ${sessionId}`);
    // You could store session metadata or initialize resources here
  },
  onSessionClosed: (sessionId: string) => {
    console.log(`Session closed: ${sessionId}`);
    // Perform cleanup logic here
  },
  onError: (error: Error, sessionId?: string) => {
    console.error(`Error in session ${sessionId}:`, error);
    // Handle errors for monitoring or logging
  }
};

// Mount the handlers for different HTTP methods
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(Server-Sent Events)를 관리합니다.
닫을 때 세션을 자동으로 정리합니다.

상태 비저장 모드

세션 관리 없이 일회성 요청 처리를 위해 statelessHandler 사용하세요. 서버리스 환경이나 간단한 요청에 적합합니다.

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

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

// Function that creates a fresh McpServer for each request
const serverFactory = () => new McpServer({
  name: 'stateless-mcp-server',
  version: '1.0.0',
});

// Configure with custom error handling
const options = {
  onError: (error: Error) => {
    console.error('MCP error:', error);
    // Add custom error reporting logic here
  }
};

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

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

각 무국적 요청:

새로운 전송 및 서버 인스턴스를 생성합니다.
세션 추적 없이 완전한 격리를 보장합니다.
단순 또는 서버리스 환경에 적합합니다.

SSE 모드

sseHandlers 사용하여 SSE(Server-Sent Events)를 통한 MCP(Model Context Protocol)를 처리합니다. 실시간 스트리밍 응답에 이상적입니다.

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

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

// Provide a factory function that returns a fresh McpServer for each SSE connection
const serverFactory = () => new McpServer({
  name: 'sse-mcp-server',
  version: '1.0.0',
});

// Configure SSE handlers
const handlers = sseHandlers(serverFactory, {
  onError: (error: Error, sessionId?: string) => {
    console.error(`[SSE][${sessionId || 'unknown'}]`, error);
  },
  onClose: (sessionId: string) => {
    console.log(`[SSE] transport closed: ${sessionId}`);
    // Clean up any session resources
  },
});

// 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');
});

SSE 핸들러는 다음을 제공합니다.

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;

매개변수	유형	설명
`server`	`McpServer`	프로토콜 논리를 처리하기 위한 `McpServer` 인스턴스
`options.sessionIdGenerator`	`() => string`	고유한 세션 ID를 반환하는 함수
`options.onSessionInitialized`	`(sessionId: string) => void`	(선택 사항) 새 세션 ID로 호출되는 콜백
`options.onSessionClosed`	`(sessionId: string) => void`	(선택 사항) 세션이 닫힐 때 호출되는 콜백
`options.onError`	`(error: Error, sessionId?: string) => void`	(선택 사항) 오류 발생 시 호출되는 콜백
`options.onInvalidSession`	`(req: express.Request) => void`	(선택 사항) 유효하지 않은 세션에 액세스하면 호출되는 콜백

statelessHandler

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

매개변수	유형	설명
`serverFactory`	`() => McpServer`	각 요청에 대해 새로운 서버 인스턴스를 반환하는 함수
`options.sessionIdGenerator`	`() => string`	(선택 사항) 전송 세션 ID 생성 재정의
`options.onClose`	`(req: express.Request, res: express.Response) => void`	(선택 사항) 요청/응답 주기가 종료되면 콜백이 실행됩니다.
`options.onError`	`(error: Error) => void`	(선택 사항) 처리 중 오류 발생 시 콜백이 실행됩니다.

sse핸들러

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

매개변수	유형	설명
`serverFactory`	`ServerFactory`	각 SSE 연결에 대해 새로운 `McpServer` 반환하는 팩토리 함수
`options.onError`	`(error: Error, sessionId?: string) => void`	(선택 사항) 오류 발생 시 호출되는 콜백으로 `error` 및 선택적 `sessionId` 수신합니다.
`options.onClose`	`(sessionId: string) => void`	(선택 사항) SSE 세션이 닫힐 때 호출되는 콜백, `sessionId` 수신

오류 처리

모든 핸들러 유형은 다음 옵션을 통해 사용자 정의 오류 처리를 지원합니다.

// Example of custom error handling for stateful handler
const handlerOptions = {
  // ... other options
  onError: (error: Error, sessionId?: string) => {
    console.error(`Error in session ${sessionId}:`, error);
    // Send error to monitoring service
    Sentry.captureException(error, {
      extra: { sessionId }
    });
  }
};

TypeScript 지원

이 패키지는 TypeScript로 작성되었으며 모든 export에 대한 타입 정의를 제공합니다. TypeScript를 사용하면 완전한 IntelliSense 및 타입 검사를 활용할 수 있습니다.

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

// Type-safe options
const options: StatefulHandlerOptions = {
  sessionIdGenerator: () => Date.now().toString(),
  onError: (error, sessionId) => {
    // TypeScript knows the types of these parameters
    console.error(`Error in session ${sessionId}:`, error);
  }
};

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

// Type-safe handler
app.post('/mcp', statefulHandler(server, options));

개발

이 프로젝트에 기여하려면:

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

테스트 범위

이 프로젝트는 견고한 테스트 범위를 갖추고 있으며, 이를 유지할 것을 약속합니다.

모든 변경 사항은 테스트를 위해 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

핸들러 유형 한눈에 보기

매니저	대본	세션	스트리밍
statelessHandler	일회성 또는 서버리스 워크로드	아니요	아니요
상태 저장 핸들러	멀티턴 상호작용	예	예
sse핸들러	실시간 SSE 스트리밍	예	예

문제 해결

mcp-session-id 헤더가 없습니다.
클라이언트가 초기 요청에서 반환된 mcp-session-id 헤더를 포함하는지 확인하세요.

교통 연결이 조기에 종료되었습니다.
네트워크 연결을 확인하고 클라이언트가 SSE 이벤트를 적절하게 처리하는지 확인합니다.

변경 사항

이 프로젝트의 모든 주요 변경 사항은 CHANGELOG.md 에 기록되어 있습니다.

This server cannot be installed

security - not tested

license - not found

quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Express 애플리케이션에 MCP(Model Context Protocol)를 통합하여 상태 저장 세션 관리와 상태 비저장 요청 처리 옵션을 모두 제공하는 유틸리티입니다.

Related MCP Servers

MCP Server
la-rebelion
-
security
A
license
-
quality
MCP Server simplifies the implementation of the Model Context Protocol by providing a user-friendly API to create custom tools and manage server workflows efficiently.
Last updated -
4
3
TypeScript
MIT License
MCP Server
agentico-dev
-
security
A
license
-
quality
MCP Server provides a simpler API to interact with the Model Context Protocol by allowing users to define custom tools and services to streamline workflows and processes.
Last updated -
13
2
TypeScript
MIT License
Todo List MCP Server
RegiByte
A
security
A
license
A
quality
A Model Context Protocol (MCP) server that provides tools for managing todo items, including creation, updating, completion, deletion, searching, and summarizing tasks.
Last updated -
10
4
TypeScript
MIT License
Sleep MCP Server
Garoth
A
security
F
license
A
quality
A Model Context Protocol (MCP) server that provides a simple sleep/wait tool, useful for adding delays between operations such as waiting between API calls or testing eventually consistent systems.
Last updated -
1
6
7
JavaScript

View all related MCP servers

Express MCP Handler