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
express-mcp-ハンドラー
モデル コンテキスト プロトコル (MCP)を Express アプリケーションに統合し、LLM とツール間のシームレスな通信を可能にするミドルウェア。
モデルコンテキストプロトコル (MCP) とは何ですか?
モデルコンテキストプロトコル（MCP）は、大規模言語モデル（LLM）を外部データソースやツールと統合するためのオープンプロトコルです。これにより、AIアシスタントは標準化されたインターフェースを介してリアルタイムデータにアクセスし、操作を実行し、さまざまなサービスと対話できるようになります。
Related MCP server: MCP Hub
特徴
ステートフル ハンドラー: 1 回限りのリクエストを処理したり、セッション ID と Server-Sent Events (SSE) を使用して長期間有効なセッションを維持したりできます。
ステートレス ハンドラー: 単純な 1 回限りのやり取りのために、各リクエストを完全に分離して処理します。
SSE ハンドラー: 専用の GET および POST エンドポイントを使用して、Server-Sent Events (SSE) 経由の Model Context Protocol (MCP) を処理します。
タイプセーフ API : 信頼性の高い統合のために TypeScript を使用して構築されています。
柔軟な構成: カスタマイズ可能なエラー処理、セッション管理、ライフサイクル フック。
Express 統合: ミドルウェア パターンを使用して Express ルートに直接プラグインします。
インストール
npm 経由でインストール:
npm install express-mcp-handlerまたは糸:
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 は、さまざまなユースケースに合わせて 3 つのハンドラー タイプを提供します。
ステートフルモード
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ヘッダーを返します。サーバーからクライアントにメッセージをプッシュするための Server-Sent Events (SSE) を管理します
セッションを閉じると自動的にクリーンアップされます
ステートレスモード
セッション管理のない 1 回限りのリクエスト処理には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を使用して、Server-Sent Events (SSE) 経由の Model Context Protocol (MCP) を処理します。これは、リアルタイムのストリーミング応答に最適です。
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で呼び出されるコールバック |
|
| *(オプション)*セッションが閉じられたときに呼び出されるコールバック |
|
| *(オプション)*エラー時に呼び出されるコールバック |
|
| *(オプション)*無効なセッションにアクセスしたときに呼び出されるコールバック |
ステートレスハンドラー
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で記述されており、すべてのエクスポートの型定義を提供します。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にアップロードする
現在の CI ステータスは、この README の上部にあるバッジ、または GitHub リポジトリの[アクション] タブで確認できます。
ライセンス
npmへの公開
まだ npm にログインしていない場合はログインしてください。
npm loginパッケージを npm に公開します (prepublishOnly ビルドが実行されます)。
npm publish新しいバージョンをバンプ、タグ付け、プッシュするには:
npm version patch # or minor, major
git push origin main --tagsハンドラーの種類の概要
ハンドラ | シナリオ | セッション | ストリーミング |
ステートレスハンドラー | 1回限りまたはサーバーレスのワークロード | いいえ | いいえ |
ステートフルハンドラー | マルチターンインタラクション | はい | はい |
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