익스프레스-mcp-핸들러
Express 애플리케이션과 MCP(Model Context Protocol)를 통합하기 위한 미들웨어로, LLM과 도구 간의 원활한 통신을 지원합니다.
모델 컨텍스트 프로토콜(MCP)이란 무엇입니까?
모델 컨텍스트 프로토콜(MCP) 은 대규모 언어 모델(LLM)을 외부 데이터 소스 및 도구와 통합하기 위한 개방형 프로토콜입니다. AI 비서가 표준화된 인터페이스를 통해 실시간 데이터에 접근하고, 작업을 실행하고, 다양한 서비스와 상호 작용할 수 있도록 지원합니다.
Related MCP server: Memory Cache Server
특징
상태 저장 핸들러 : 세션 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
피어 종속성
이 패키지에는 다음과 같은 피어 종속성이 필요합니다.
아직 설치하지 않았다면 설치하세요.
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 핸들러는 다음을 제공합니다.
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에 패키지를 게시합니다(prepublishOnly 빌드가 실행됩니다):
새 버전을 범프, 태그 및 푸시하려면 다음을 수행합니다.
npm version patch # or minor, major
git push origin main --tags
핸들러 유형 한눈에 보기
매니저 | 대본 | 세션 | 스트리밍 |
statelessHandler | 일회성 또는 서버리스 워크로드 | 아니요 | 아니요 |
상태 저장 핸들러 | 멀티턴 상호작용 | 예 | 예 |
sse핸들러 | 실시간 SSE 스트리밍 | 예 | 예 |
문제 해결
mcp-session-id
클라이언트가 초기 요청에서 반환된 mcp-session-id 헤더를 포함하는지 확인하세요.
교통 연결이 조기에 종료되었습니다.
네트워크 연결을 확인하고 클라이언트가 SSE 이벤트를 적절하게 처리하는지 확인합니다.
변경 사항
이 프로젝트의 모든 주요 변경 사항은 CHANGELOG.md 에 기록되어 있습니다.