Loads environment variables from .env files for server configuration, enabling customization of transport types, HTTP settings, authentication, and logging options.
Provides HTTP request utilities through the 'serviceRequest' function in httpUtils.ts, supporting authenticated API requests with OAuth2 or API key authentication, retries, and response validation.
Implements the HTTP transport layer using Express to handle POST requests to the /mcp endpoint, process JSON-RPC messages, and support stateless request handling.
MCP-SERVER-TEMPLATEへようこそ。これは、公式 TypeScript SDK を使用して Model Context Protocol (MCP) サーバーを実装するためのテンプレート プロジェクトです。このプロジェクトは、HTTP や標準 I/O (stdio) などのさまざまなトランスポート メカニズムをサポートし、ステートレスおよびステートフル MCP サーバーを構築するための基盤を提供します。
このプロジェクト（ MCP-SERVER-TEMPLATE ）は、公式SDKを用いてModel Context Protocol（MCP）サーバーを構築するためのTypeScriptベースのスターターテンプレートです。このサーバーは、ユーザークエリとツール実行間のインターフェースとして機能し、AIアシスタントや外部システムがツールを動的に呼び出し、プロンプトを解釈し、モジュール式かつ拡張可能な方法でリソースを管理できるようにします。
execute関数.envおよびランタイム構成ファイルを通じて簡単に調整可能:このテンプレートは次の場合に最適です。
LLM ツールチェーンのプロトタイプ作成、独自システムとの統合、スケーラブルな本番環境向け MCP アシスタント バックエンドの準備など、このプロジェクトはすぐに拡張できる、徹底的に構造化されたソリューションを提供します。
package.jsonで定義されているように、本番環境の依存関係 (例: @modelcontextprotocol/sdk 、 express 、 axios ) と開発環境の依存関係 (例: typescript 、 ts-node 、 jest ) の両方がインストールされます。@modelcontextprotocol/sdkパッケージ (バージョン^1.10.1 ) がインストールされていることを確認します。このプロジェクトでは、環境変数とsrc/core/config/内の2つの主要ファイルによって管理される設定システムを使用しています。設定はConfigServiceとruntimeConfigで定義されており、トランスポートタイプ、ログ記録、外部API統合のカスタマイズが可能です。
runtimeConfig.tsのdotenv経由で読み込まれます):TRANSPORT_TYPE : トランスポートメカニズムを設定します ( 'http'または'stdio' 、デフォルト: 'stdio' )。HTTP_PORT : HTTP サーバーのポート (デフォルト: 3000 )。HTTP_HOST : HTTP サーバーのホスト (デフォルト: localhost )。SESSION_SUPPORT : セッション サポートを有効/無効にします (デフォルト: 'true' )。LOG_LEVEL : ログレベル (例: 'info' 、 'debug' 、デフォルト: 'info' )。MCP_INSPECTOR_PORT : MCP インスペクタのポート (デフォルト: 6274 )。.envファイルで環境変数を設定します。
サーバーはエントリ ポイントsrc/index.tsを介して起動され、依存性の注入と構成設定を使用して初期化と起動のプロセスを調整します。
index.ts 、 dotenvを使用して環境変数を読み込み、構成設定 (例: TRANSPORT_TYPE 、 HTTP_PORT ) が利用可能であることを確認します。createDependenciesを使用して、ロガーやConfigServiceなどの共有依存関係を設定します。HttpTransportまたはStdioTransport ) は、 TRANSPORT_TYPE設定に基づいて、 runtimeConfigを介して構成されます。MCPServerインスタンスを作成します。tscが実行され、コンパイルされた JavaScript ファイルを含むdist/フォルダーが生成されます。node dist/index.jsが実行され、コンパイルされたサーバーが実行されます。httpの場合、サーバーはhttp://localhost:3000/mcpをリッスンします (ポートとホストはHTTP_PORTとHTTP_HOSTで設定可能です)。stdioの場合、サーバーはコンソールから読み取り、コンソールに書き込みます。ts-nodeを使用して TypeScript でサーバーを直接実行します。ts-node src/index.tsが実行され、ビルド ステップなしで反復処理が高速化されます。runtimeConfig設定が正しく設定されていることを確認してください。LOG_LEVELによって制御) をチェックして、サーバーが正常に起動したことを確認します。このプロジェクトには、自動テストと MCP インスペクターを使用してサーバーをテストし、その動作をデバッグし、機能を検証するためのスクリプトがいくつか含まれています。
Jest を使用して単体テストを実行し、個々のコンポーネントの機能を検証します。
これによりjestが実行され、プロジェクトで定義されているすべてのテスト（テストツール、ユーティリティ、サーバーロジックなど）が実行されます。テストファイルがJestとts-jestでセットアップされていることを確認してください。TypeScriptのサポートが必要です。
MCP サーバーの基本機能を検証するための HTTP トランスポート用のテスト スクリプトが提供されています。
src/scripts/testHttpTransport.js )tools/list要求をサーバーに送信し、応答を検証することで、HTTP トランスポートをテストします。axiosを使用して HTTP POST リクエストをサーバーに送信します。method: 'tools/list' 、 id: 1 、適切なヘッダーを使用して、JSON-RPC 2.0 リクエストをhttp://localhost:3000/mcpに送信します。jsonrpc: '2.0' ) に準拠します。idリクエストと一致します ( id: 1 )。toolsキーを含むresultフィールドが含まれます。TRANSPORT_TYPEが'http'に設定された状態でサーバーが実行されていることを確認します。ts-node src/scripts/testHttpTransport.tsが実行されます。1 つのコマンドでサーバーを起動し、HTTP テストを実行するには:
これによりnpm run start & npm run test:httpが実行され、バックグラウンドでサーバーが起動し、HTTP テスト スクリプトがすぐに実行されます。
http://localhost:3000/mcpで実行されていることを前提としています。HTTP_PORT またはHTTP_HOST``HTTP_PORT異なる場合は、スクリプト内のendpointを調整してください。CalculatorToolなどのツールが登録されていることを確認し、 tools/list応答でそれらを表示します。MCP Inspector は、MCP サーバーのデバッグと監視を行う強力なツールであり、サーバー状態と相互作用を検査するための Web UI を提供します。
src/scripts/mcpInspectorScript.ts )child_processを使用してmcp-inspectorプロセスを生成し、ブラウザーを開くコマンドを実行します。axiosを使用して、MCP Inspector Web UI にアクセスできるかどうかを確認します。createDependencies()を介して依存性注入を活用し、ポート構成のためにConfigServiceアクセスします。npx mcp-inspector node dist/index.jsを使用してmcp-inspectorプロセスを生成し、コンソール出力用の stdio を継承します。waitUntilInspectorIsReadyを実装して、Web UI (デフォルト ポート: 6274 、 MCP_INSPECTOR_PORTで構成可能) を再試行 (20 回の試行、500 ミリ秒の遅延) してポーリングします。openstartxdg-openhttp://localhost:6274 (または設定されたポート)http://localhost:6277npm run build実行してdist/index.jsを生成します)。ts-node src/scripts/start-mcp-inspector.tsが実行されます。プロジェクトをビルドし、MCP インスペクターを 1 つのコマンドで起動するには、次の手順を実行します。
これによりnpm run build && npm run mcp:inspector実行され、インスペクターを起動する前にプロジェクトがコンパイルされていることが保証されます。
MCP_INSPECTOR_PORT別のサービスによって使用されていないことを確認します。このプロジェクトでは、Prettier を使用して、すべてのファイルにわたって一貫したコード形式を維持します。
プロジェクト内のすべてのファイルをフォーマットするには:
これにより、 prettier --write .が実行され、サポートされているすべてのファイル (例: .ts 、 .js 、 .json ) が自動的にフォーマットされます。
すべてのファイルが Prettier フォーマット ルールに準拠しているかどうかを確認するには:
これにより、 prettier --check .が実行され、フォーマット規則に準拠していないファイルが変更されずに報告されます。
src/core/config/configService.ts : サーバー構成を管理するためのクラスであるConfigServiceを実装します。トランスポートタイプ、HTTPサーバー設定、ログレベル、API URL（例：MealDB）、認証資格情報、MCPインスペクタポートなどのデフォルト値を含む環境変数から設定を読み込みます。runtimeConfig.ts : dotenvを使用して環境変数を読み込むランタイム設定を定義します。トランスポート設定 ( transportType 、 port ) と認証戦略 ( authStrategy 、 tokenSecret 、 username 、 password ) を設定します。src/core/dependencies/dependencies.ts : Dependenciesインターフェースを用いた依存性注入を実装し、Winston を使用したloggerとConfigServiceインスタンスを提供しcreateDependencies 。createDependencies 関数はtransportTypeに基づいてログトランスポートを動的に設定し（ stdioの場合は stderr、その他の場合は stdout、およびファイル log combined.log ）、グローバル使用のためのシングルトンloggerをエクスポートします。src/core/server/transports/http/server.ts : Express を用いたステートレス HTTP トランスポートであるHttpTransport実装します。POST POST /mcpリクエストの処理、オプションの Bearer トークン認証による JSON-RPC メッセージの処理、レスポンスのResponseMapへの保存、そして非同期送信をサポートします。ログ記録と設定は、依存性注入 (DI) されたDependenciesに依存します。stdio/server.ts : SDK のStdioServerTransportを使用したトランスポートであるStdioTransportを実装します。stdin/stdout 通信の管理、トランスポートの開始と終了、そして依存性注入されたDependenciesによるエラーログ出力を伴うメッセージ送信の処理を行います。baseTransport.ts : SDK のTransportインターフェースを拡張するBaseTransportインターフェースと抽象クラスAbstractTransportを定義します。トランスポート実装用のメソッド ( start 、 send 、 close 、 isRunning ) とイベントハンドラー ( onmessage 、 onerror 、 onclose ) を指定し、 HttpTransportとStdioTransportに共通の規約を提供します。transportFactory.ts : TransportFactoryを実装します。これは、 TransportConfig型（例: 'http'または'stdio' ）に基づいてHttpTransportまたはStdioTransportのインスタンスを作成する静的クラスです。Dependencies によるDependencies性注入を使用してログ記録と設定を提供し、サポートされていないトランスポートタイプに対してはエラーをスローします。mcpServer.ts : MCP SDK のServerとトランスポート ( HttpTransportまたはStdioTransport ) を統合するコアサーバークラスMCPServerを実装します。サーバーの初期化、 ToolRegistryを持つRequestHandlerのセットアップ、トランスポートへの接続、そして依存性注入によるDependenciesを用いたログ出力によるメッセージパッシング、エラー、レスポンスの処理を行います。requestHandler.ts : RequestHandlerを実装します。これは、MCP SDK を使用してtools/listおよびtools/callリクエストのハンドラーを登録します。利用可能なツールを一覧表示し、検証済みの引数（Zod経由）を使用してツール呼び出しを実行します。認証トークンをサポートし、無効なツール（ ToolNotFoundError ）または引数（ ValidationError ）に対してエラーをスローします。ログ記録には依存性注入（ Dependencies ）を使用します。src/core/toolManagement/toolFactory.ts : ToolFactoryを実装します。これは、 Dependenciesによる依存性注入を用いてツール（例： calculatorTool ）のインスタンスを作成するクラスです。汎用的なToolConstructor型を定義し、インスタンス化エラーをログに記録して処理します。toolRegistry.ts : ツールの登録と取得を管理するクラスToolRegistryを実装します。ToolFactory ToolFactory使用してtoolClassesからツールをインスタンス化し、 Mapに格納します。また、ツールのメタデータ（名前、説明、入力スキーマ）を登録、取得、一覧表示するメソッドを提供します。依存性注入されたDependenciesを介して、読み込みステータスとエラーをログに記録します。errors.ts : ツール管理用のカスタム エラー クラスを定義します。これには、 ToolNotFoundError (要求されたツールが登録されていない場合にスローされます) やValidationError (ツール引数が Zod などを介して検証に失敗した場合、スローされます) が含まれます。types.ts : トランスポートと認証設定のためのTypeScript型TransportConfig定義します。TransportType ( 'stdio' 、 'sse' 、 'http' )、 TransportType (SSEまたはHTTPと認証のオプション付き)、 SSETransportConfig (ポート、CORS、認証)、 HttpStreamTransportConfig (ポート、レスポンスモード、CORS、セッション、再開可能性、認証)、 AuthConfig (戦略、資格情報) が含まれます。src/prompts/ : プロンプト テンプレートのディレクトリ (現在は空ですが、将来の実装用に予約されています)。src/resources/ : リソース管理用のディレクトリ (現在は空ですが、将来の実装用に予約されています)。src/scripts/testHttpTransport.js : tools/list要求を送信し、応答を検証することで基本機能を確認するための HTTP トランスポートのテスト スクリプト。mcpInspectorScript.ts : MCP Inspector を起動し、Web UI の準備が整うまで待機し、MCP サーバーのデバッグのためにブラウザで開くスクリプトです。依存性注入を使用してConfigServiceにアクセスし、ポート設定を行います。また、プラットフォーム固有のブラウザの開き方にも対応しています。src/tools/types/ITool.ts : ツールのIToolインターフェースを定義し、 name 、 description 、 schema （Zod型）、 jsonSchema 、およびJSON-RPC CallToolRequestを処理するためのexecuteメソッドを指定します。ツール実装のDependenciesをエクスポートします。baseTool.ts : 定型句を削減し、 Dependenciesによる依存性注入を処理し、 BaseToolション、ドキュメント化、および UI 生成のためにzod-to-json-schemaを使用して Zod スキーマを JSON スキーマに自動的に変換する抽象 BaseTool クラスを実装します。index.ts : ToolRegistryによる動的な読み込みのために、 toolClassesツール コンストラクター (例: CalculatorTool ) の配列としてエクスポートし、新しいツールによる拡張を容易にします。calculatorTool.ts : CalculatorToolを実装します。 subtractは、 Zod による入力検証、エラー処理 ( HttpErrorを使用したゼロ除算divide )、および依存性注入によるDependenciesによるログ記録を伴う基本的な算術演算 ( add 、 multiply 、乗算、除算) を実行する具体的なツールです。utils/httpUtils.ts : HTTP操作用のユーティリティ関数を提供します。これには、再試行とタイムアウト処理を備えた認証済みHTTPリクエスト（OAuth2またはAPIキー）を作成するためのserviceRequest 、OAuth2トークンの取得とキャッシュを行うgetAuthToken 、クエリ文字列を作成するbuildQueryString 、レスポンス検証を行うvalidateResponseが含まれます。設定のためにConfigServiceと統合されています。index.ts : ツールやその他のコンポーネントで使用するためのユーティリティ関数をエクスポートします。src/index.ts : MCPサーバーを起動するためのエントリポイント。dotenv を使用して環境変数を読み込み、 createDependenciesを使用して依存関係をdotenv化し、 runtimeConfigからのトランスポートを使用してMCPServerインスタンスを作成し、サーバーを非同期的に起動します。致命的なエラーはログに記録して終了することで処理されます。MCPServerセットアップでハンドラーが登録され、機能が設定されていることを確認します ( RequestHandler経由)。MCPServerの再利用を検討してください。ただし、十分なテストを実施してください。.envファイルで正しく設定されているか、プロセスに直接渡されていることを確認します。ConfigServiceログをチェックして、読み込まれた設定を確認します。LOG_LEVEL環境変数が期待されるレベル (例: 'info' 、 'debug' ) と一致していることを確認します。stdioトランスポートの場合、ログが意図したとおりに stderr に送信されていることを確認します。ファイルベースのログについては、 combined.logチェックします。HttpTransportの場合、ポートが使用可能であり、競合するサービスが実行されていないことを確認します。StdioTransportの場合、メッセージが処理されていない場合は stdin/stdout の可用性を確認します。TransportFactoryが失敗した場合は、 TRANSPORT_TYPE構成でサポートされているタイプ ( 'http'または'stdio' ) と一致していることを確認します。tools/listまたはtools/callリクエストが失敗した場合は、 ToolRegistryで登録済みのツールを確認してください。ValidationError回避するには、 CallToolRequestSchema内のスキーマに対してツール引数を検証します。src/tools/index.tsのtoolClassesに有効なツール実装が含まれていることを確認してください。ToolFactoryログでインスタンス化エラーを確認し、 Dependenciesが適切に挿入されていることを確認します。MCP_INSPECTOR_PORT (デフォルト: 6274 ) が使用されていないことを確認してください。npm run buildを実行してdist/index.jsが存在することを確認します。serviceRequestが失敗した場合は、 ConfigServiceのauthType 、 authEndpoint 、 clientId 、 clientSecret 、またはapiKey設定を確認してください。validateResponseを使用してレスポンス スキーマを検証します。testHttpTransport.jsスクリプトが失敗する場合は、サーバーがTRANSPORT_TYPE='http'で実行されており、 http://localhost:3000/mcpをリッスンしていることを確認してください。endpointと一致していることを確認します ( HTTP_PORTまたはHTTP_HOSTが異なる場合は調整します)。ToolRegistryに登録されているツールがあるかどうかを確認します。 tools配列が空の場合は、ツールの読み込みに問題がある可能性があります。npm testが失敗した場合は、TypeScript サポートのために Jest がts-jestで正しく構成されていることを確認し、テスト ファイルが存在することを確認します。npm run mcp:inspectorまたはnpm run mcp:devが失敗する場合は、 @modelcontextprotocol/inspectorがインストールされ、サーバーがコンパイルされている ( dist/index.jsが存在する) ことを確認してください。npm run format:check問題が報告された場合は、 npm run formatを実行して自動的にフォーマットを修正するか、Prettier のルールに合わせてファイルを手動で調整します。GitHubリポジトリに問題やプルリクエストをお気軽にご提出ください。サーバー実装の改善、新機能の追加、パフォーマンスの最適化など、皆様の貢献を歓迎いたします。
このプロジェクトはISCライセンスに基づいてライセンスされています。詳細はLICENSEファイルをご覧ください。
@modelcontextprotocol/sdkを使用して構築This server cannot be installed
AI アシスタントがツールを動的に呼び出し、プロンプトを解釈し、複数のトランスポート方法をサポートするモジュラー アーキテクチャを通じてリソースを管理できるようにするモデル コンテキスト プロトコル サーバーを構築するための TypeScript ベースのスターター テンプレート。