A
licenseNot graded
qualityD
maintenanceA comprehensive ElysiaJS plugin for building Model Context Protocol (MCP) servers with HTTP transport, session management, and support for tools, resources, and prompts.
11,932 npm
49
MIT
Express MCP Handler
by jhgaylor
익스프레스-mcp-핸들러
Express 애플리케이션과 MCP(Model Context Protocol)를 통합하기 위한 미들웨어로, LLM과 도구 간의 원활한 통신을 지원합니다.
모델 컨텍스트 프로토콜(MCP)이란 무엇입니까?
모델 컨텍스트 프로토콜(MCP) 은 대규모 언어 모델(LLM)을 외부 데이터 소스 및 도구와 통합하기 위한 개방형 프로토콜입니다. AI 비서가 표준화된 인터페이스를 통해 실시간 데이터에 접근하고, 작업을 실행하고, 다양한 서비스와 상호 작용할 수 있도록 지원합니다.
Related MCP server: MCP Hub
특징
상태 저장 핸들러 : 세션 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.2zod>= 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;매개변수 | 유형 | 설명 |
|
| 프로토콜 논리를 처리하기 위한 |
|
| 고유한 세션 ID를 반환하는 함수 |
|
| (선택 사항) 새 세션 ID로 호출되는 콜백 |
|
| (선택 사항) 세션이 닫힐 때 호출되는 콜백 |
|
| (선택 사항) 오류 발생 시 호출되는 콜백 |
|
| (선택 사항) 유효하지 않은 세션에 액세스하면 호출되는 콜백 |
statelessHandler
function statelessHandler(
serverFactory: () => McpServer,
options?: {
sessionIdGenerator?: () => string;
onClose?: (req: express.Request, res: express.Response) => void;
onError?: (error: Error) => void;
}
): express.RequestHandler;매개변수 | 유형 | 설명 |
|
| 각 요청에 대해 새로운 서버 인스턴스를 반환하는 함수 |
|
| (선택 사항) 전송 세션 ID 생성 재정의 |
|
| (선택 사항) 요청/응답 주기가 종료되면 콜백이 실행됩니다. |
|
| (선택 사항) 처리 중 오류 발생 시 콜백이 실행됩니다. |
sse핸들러
function sseHandlers(
serverFactory: ServerFactory,
options: SSEHandlerOptions
): {
getHandler: express.RequestHandler;
postHandler: express.RequestHandler;
};매개변수 | 유형 | 설명 |
|
| 각 SSE 연결에 대해 새로운 |
|
| (선택 사항) 오류 발생 시 호출되는 콜백으로 |
|
| (선택 사항) SSE 세션이 닫힐 때 호출되는 콜백, |
오류 처리
모든 핸들러 유형은 다음 옵션을 통해 사용자 정의 오류 처리를 지원합니다.
// 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 상태를 볼 수 있습니다.
특허
npm에 게시하기
아직 npm에 로그인하지 않았다면 로그인하세요.
npm loginnpm에 패키지를 게시합니다(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 deployed
Maintenance
ActivityInactive
ResponsivenessNo issues
Related MCP Connectors
Model Context Protocol server for the Apideck Unified API. Connect any MCP-compatible agent framework to 100+ accounting systems, HRIS platforms, file storage providers, and more through one integration. More information https://www.apideck.com/mcp-server
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
MCP server for secureFlows: token-free URL builders and integration-linting tools for AI agents.
Connect MCP clients to 2,000+ AI models without managing provider API keys.
Related MCP Servers
- -licenseNot gradedqualityNot gradedmaintenanceAn Express server implementation of Model Context Protocol that allows websites to connect to LLMs through streamable HTTP and stdio transports, with a built-in chat UI for testing responses.-
- FlicenseNot gradedqualityDmaintenanceA lightweight Hono.js middleware for building Model Context Protocol servers using a simple, fluent API and supporting both SSE and HTTP transports. It enables developers to create type-safe, edge-ready MCP-compatible APIs with built-in session management.-
chuk-mcp-runtimeofficial
AlicenseNot gradedqualityCmaintenanceA robust runtime for the official Model Context Protocol (MCP) that adds proxying, session management, JWT auth, persistent user storage with scopes, and progress notifications.9Apache 2.0