Generic MCP Server

汎用 MCP サーバー

TypeScript と Express で構築された、本番環境に対応する Model Context Protocol（MCP）サーバーの実装です。AI エージェントと外部 API をシームレスに接続できるように設計されています。

概要

このプロジェクトでは、@modelcontextprotocol/sdk を使用して、Server-Sent Events（SSE）対応の MCP サーバーを実装する方法を紹介します。映画データベースとのやり取りに重点を置き、AI エージェントや大規模言語モデル（LLM）に API を公開するための実践的なリファレンスを開発者に提供します。

実装の詳細は、src/mcp/tools.ts、src/mcp/prompts.ts、src/helpers/ ディレクトリおよび関連ファイルに記載されています。

MCP とは？

Model Context Protocol（MCP）は、AI モデルが外部システムと安全かつ効率的にやり取りするための標準化されたインターフェースを確立します。以下のための構造化されたフレームワークを定義します。

• リソース：モデルがアクセスできるデータオブジェクト
• ツール：モデルが呼び出せる実行可能な関数
• プロンプト：モデルとのやり取りを導くテンプレート

この標準化により、既存のアプリケーションやサービスへの AI 機能の統合が簡素化されます。

詳しいドキュメントについては、Model Context Protocol リポジトリをご覧ください。

主な機能

• MCP 仕様の完全な実装
• Server-Sent Events（SSE）によるリアルタイム通信
• 拡張しやすいモジュール式アーキテクチャ
• 人物検索や映画の発見に対応した、映画データベースとの組み込み連携
• API レスポンス用の型安全なインターフェース
• 包括的なエラー処理
• テストとリファレンスに使えるサンプルクライアント

前提条件

• Node.js 18 以降
• npm または yarn のパッケージマネージャー

はじめに

インストール

1. リポジトリをクローンします。

   git clone https://github.com/yourusername/generic-mcp-server.git
   cd generic-mcp-server
   

2. 依存関係をインストールします。

   npm install
   

3. 環境を設定します。

   cp .env.example .env
   

4. API 認証情報を .env ファイルに追加します。

   PORT=8089
   ACCESS_TOKEN=your_movie_db_access_token
   

サーバーの起動

ホットリロードを有効にした開発モード：

npm run dev

本番モード：

npm run build
npm start

サーバーは http://localhost:8089（または .env ファイルで指定したポート）で利用できます。

API リファレンス

エンドポイント

エンドポイント	メソッド	説明
/sse	GET	MCP 通信用の Server-Sent Events エンドポイント
/messages	POST	クライアントが MCP サーバーにメッセージを送信するためのエンドポイント

MCP コンポーネント

リソース

• greeting://welcome：静的なウェルカムメッセージ
• users://{userId}：動的なユーザーデータリソース

ツール

このサーバーは、映画データベース用の強力なツールを実装しています。

• movie_database_search_person：俳優、監督、映画業界の専門家を検索し、経歴、伝記データ、フィルモグラフィーに関する詳細情報を取得します。
• movie_database_discover_films：キャスト、ジャンル、公開日、評価などで絞り込める、高度な映画検索機能です。

プロンプト

• greeting：親しみやすいユーザーへの挨拶
• help：コマンドに関する詳細な案内
• ask-question：会話を導くための質問テンプレート
• error：適切なエラー処理のためのプロンプト

映画データベースの機能

このサーバーでは、以下の機能を備えた The Movie Database（TMDB）API を利用できます。

• 俳優や監督を含む映画業界の専門家を検索
• 豊富な絞り込みオプションで映画を検索：
  • 公開日、人気度、評価による絞り込み
  • キャストまたはスタッフによる絞り込み
  • ジャンル、キーワード、制作会社による絞り込み
  • 上映時間または言語による絞り込み
  • 収益化の種類（無料、サブスクリプション、レンタルなど）による絞り込み

環境設定

変数	説明	デフォルト
PORT	サーバーのポート番号	8089
ACCESS_TOKEN	映画データベース API の認証トークン	必須

サンプルクライアントでのテスト

このリポジトリには、MCP サーバーへの接続方法と操作方法を示すデモクライアントが含まれています。

npm run client

クライアントでは、以下の操作を行います。

• サーバーへの接続を確立します
• 利用可能なリソース、ツール、プロンプトを表示します
• 挨拶のリソースを読み取ります
• ツールの使用方法を実演します
• プロンプトテンプレートを取得します

AI モデルとの統合

このサーバーは、MCP プロトコルをサポートするあらゆる LLM と統合できます。標準化されたインターフェースにより、さまざまな AI フレームワークやプラットフォームとの互換性が確保されます。

アーキテクチャ

このプロジェクトは、モジュール式のアーキテクチャを採用しています。

• src/mcp/：MCP プロトコルのコア実装
• src/helpers/：API 固有のヘルパー関数
• src/utils/：ユーティリティ関数と共有コード
• src/types.ts：TypeScript インターフェース定義

利用可能なインターフェース

このプロジェクトには、API レスポンス用の型付きインターフェースが含まれています。

• ApiResponse<T>：データ、エラー、ステータスの各フィールドを持つ汎用 API レスポンスラッパー
• ApiConfig：baseUrl と任意のヘッダーを指定する API クライアントの設定

これらのインターフェースは、API データを扱う際の型安全性の確保に役立ちます。

コントリビューション

コントリビューションを歓迎します。お気軽にプルリクエストを送信してください。

ライセンス

MIT