RAGmonsters 向けカスタム PostgreSQL MCP サーバー
概要
このリポジトリは、モデルコンテキストプロトコル（MCP）を用いて大規模言語モデル（LLM）とデータベースを統合する、より高度なアプローチを示しています。汎用的なMCP PostgreSQLサーバーでは、LLMが生のSQLクエリを通じてデータベースを探索できますが、このプロジェクトでは、アプリケーションのニーズに合わせてカスタマイズされたドメイン固有のAPIを提供するカスタムMCPサーバーを作成することで、異なるアプローチを採用しています。
この実装では、モデルコンテキストプロトコルの高性能実装であるFastMCPが使用され、LLM とのツールベースの相互作用の効率と信頼性が向上します。
このプロジェクトは、 RAGmonstersデータセットを基盤として利用しています。RAGmonstersは、様々な属性、能力、関係性を持つ架空のモンスターの豊富なデータセットを提供するオープンソースプロジェクトで、特に検索拡張生成（RAG）システムのデモンストレーションとテストを目的として設計されています。
汎用MCPデータベースアクセスの問題点
汎用 MCP PostgreSQL サーバーは、LLM に次の機能を可能にするqueryツールを提供します。
- データベーススキーマを調べる
- 自然言語の質問に基づいてSQLクエリを作成する
- これらのクエリをデータベースに対して実行する
このアプローチは機能しますが、実際のアプリケーションではいくつかの制限があります。
- 認知負荷: LLMはデータベーススキーマ全体を理解する必要がある
- 非効率性: 1つの質問に答えるのに複数のSQLクエリが必要になることが多い
- セキュリティ上の懸念: 生のSQLアクセスには、インジェクション攻撃を防ぐために慎重かつ迅速なエンジニアリングが必要です。
- パフォーマンス: LLMがデータベースのインデックス戦略を理解していない場合、複雑なクエリは非効率になる可能性があります。
- ドメイン知識のギャップ: LLMはビジネスルールとドメイン固有の制約を理解していない
RAGmonstersデータセットについて
RAGmonstersは、検索拡張生成（RAG）システムのテストとデモンストレーションのために特別に設計されたオープンデータセットです。豊富な属性、能力、そして関係性を持つ架空のモンスターに関する情報が含まれており、自然言語クエリのデモンストレーションに最適です。
RAGmonsters の PostgreSQL バージョンは、次のような複数のテーブルとリレーションシップを備えた、適切に構造化されたリレーショナル データベースを提供します。
- 様々な属性（攻撃力、防御力、体力など）を持つモンスター
- モンスターが持つ能力
- 複雑な関係を持つ要素（火、水、土など）
- モンスターが生息する生息地
- モンスター間の進化の連鎖と関係性
このリッチで相互接続されたデータセットは、汎用 SQL アクセスと比較したドメイン固有の API の威力を示すのに最適です。
私たちのソリューション: ドメイン固有のMCP API
このプロジェクトでは、RAGmonstersデータセット用の高水準かつドメイン固有のAPIを提供するカスタムMCPサーバーの構築方法を紹介します。生のSQL機能を公開するのではなく、MCPサーバーは以下のような専用関数を提供します。
- 抽象データベースの複雑さ: 基礎となるスキーマとSQLの詳細を非表示にする
- ドメイン固有の操作を提供する：ビジネスコンセプトに沿った機能を提供する
- 一般的なクエリの最適化: よくある質問に対して効率的なクエリパターンを実装します
- ビジネスルールの適用: ドメイン固有のロジックと制約を埋め込む
- セキュリティの向上: 直接SQLアクセスを排除することで攻撃対象領域を制限
ウェブインターフェース
このプロジェクトには、RAGmonsters データセットと対話するための 2 つの主要なインターフェースが含まれています。
エクスプローラーインターフェース
MCP API を介して RAGmonsters データセットを探索およびフィルタリングするためのデータ重視のインターフェース:
- カテゴリ、生息地、希少性でフィルタリングしてすべてのモンスターを閲覧します
- 各モンスターの詳細情報を見る
- Bootstrapで構築されたインタラクティブなUI
チャットインターフェース
RAGmonsters データセットと対話するための自然言語インターフェース:
- 自然言語でモンスターについて質問する
- 豊富なフォーマットでMarkdown形式のレスポンスを取得
- LangGraphのReActエージェントパターンを搭載
- MCPツールとのシームレスな統合
このインターフェースにより、ユーザーは次のことが可能になります。
- データセット内のすべてのモンスターを閲覧する
- 生息地、カテゴリー、レア度でモンスターをフィルタリング
- 各モンスターの詳細な情報（パワー、能力、長所、短所など）を表示します
例: ドメイン固有 API と汎用 SQL
一般的なMCP PostgreSQLアプローチ:
User: "What are the top 3 monsters with the highest attack power that are vulnerable to fire?"
LLM: (Must understand schema, joins, and SQL syntax)
1. First query to understand the schema
2. Second query to find monsters with attack power
3. Third query to find vulnerabilities
4. Final query to join and filter results
当社のカスタム MCP サーバー アプローチ:
User: "What are the top 3 monsters with the highest attack power that are vulnerable to fire?"
LLM: (Uses our domain-specific API)
1. Single call: getMonsters({ vulnerableTo: "fire", sortBy: "attackPower", limit: 3 })
プロジェクト構造
├── .env.example # Example environment variables
├── package.json # Node.js project configuration
├── README.md # This documentation
├── img/ # Images for documentation
├── scripts/
│ ├── testMcpServer.js # Test script for the MCP server
│ └── testLogger.js # Logger for test script
├── src/
│ ├── index.js # Main application server
│ ├── mcp-server/ # Custom MCP server implementation with FastMCP
│ │ ├── index.js # Server entry point
│ │ ├── tools/ # Domain-specific tools
│ │ │ ├── index.js # Tool registration
│ │ │ └── monsters.js # Monster-related operations
│ │ └── utils/ # Helper utilities
│ │ └── logger.js # Logging functionality
│ ├── llm.js # LangChain integration for LLM
│ └── public/ # Web interface files
│ ├── index.html # Monster explorer interface
│ └── chat.html # Chat interface for LLM interactions
特徴
- FastMCPを使用したカスタムMCPサーバー:RAGmonstersデータ用の高性能なドメイン固有API
- 最適化されたクエリ: 事前に構築された効率的なデータベース操作
- ビジネスロジック層: APIに埋め込まれたドメインルールと制約
- 構造化応答フォーマット: LLM 使用時の一貫した JSON 応答
- 包括的なログ記録: デバッグと監視のための詳細なログ記録
- テストスイート: サーバーの機能と LLM の統合を検証するためのスクリプト
- LLM統合:
- LangChain.js と OpenAI およびその他の互換性のある LLM プロバイダーとの統合
- 効率的なツール使用のためのLangGraph ReActエージェントパターン
- ツールの呼び出しと応答の自動処理
- Webインターフェース:
- モンスターを閲覧およびフィルタリングするためのエクスプローラーインターフェース
- 自然言語によるやりとりを可能にする Markdown レンダリングを備えたチャット インターフェース
特徴
- LangChain.js 統合: MCP ツールと完全に統合された LLM のインタラクション
- Web インターフェース: RAGmonsters データセットを操作するためのエクスプローラーおよびチャット インターフェース
- 導入準備完了: Clever Cloud などのプラットフォームに簡単に導入できるように構成されています
このアプローチの利点
- パフォーマンスの向上: 最適化されたクエリとキャッシュ戦略
- より良いユーザーエクスペリエンス：より正確で迅速な応答
- トークン使用量の削減: LLMは複雑なSQLやスキーマ情報を処理する必要がない
- 強化されたセキュリティ: 直接 SQL アクセスがないため、インジェクション攻撃のリスクが軽減されます。
- 保守性: データベーススキーマの変更にLLMの再トレーニングは不要
- スケーラビリティ: より大規模で複雑なデータベースを処理できます
はじめる
インストール
- このリポジトリをクローンする
- 依存関係をインストール:
npm install .env.exampleを.envにコピーし、PostgreSQL 接続文字列と LLM API キーを設定します。- MCPサーバーのテストスクリプトを実行します:
npm run test - LLM統合テストスクリプトを実行します:
npm run test:llm - サーバーを起動します:
npm start
利用可能なツール
MCP サーバーは次のツールを提供します。
- getMonsters - オプションのフィルタリング、並べ替え、ページ区切りを使用してモンスターのリストを取得します
- パラメータ: フィルター (カテゴリ、生息地、希少性)、並べ替え (フィールド、方向)、制限、オフセット
- 戻り値: 基本情報を持つモンスターオブジェクトの配列
- getMonsterById - IDで特定のモンスターの詳細情報を取得します
- パラメータ: モンスターID
- 戻り値: すべての属性、パワー、能力、長所、短所を含む詳細なモンスターオブジェクト
- add - 2つの数値を加算するシンプルなユーティリティ（テスト用）
LLM統合アーキテクチャ
このプロジェクトでは、ドメイン固有のツールを使用した LLM 統合に最新のアプローチを採用しています。
LangGraph ReAct エージェントパターン
アプリケーションは、LangGraph の ReAct (推論と行動) エージェント パターンを使用します。
- ユーザーのクエリを処理して意図を理解する
- クエリに基づいて使用するツールを決定します
- 適切なツールを自動的に実行します
- 結果を統合して一貫した対応をします
- 必要に応じて複数段階の推論を処理する
LLM統合のテスト
このプロジェクトには、LangChain.js を使用して LLM を MCP サーバーに統合する方法を示すテスト スクリプトが含まれています。
このスクリプト:
- StdioClientTransportを使用してMCPサーバーに接続します
- LangChainのMCPアダプターを使用して利用可能なすべてのMCPツールをロードします
- OpenAI APIを使用してLangChainエージェントを作成する
- モンスターに関する自然言語クエリを処理する
- LLMが情報を取得するためにツール呼び出しを行う方法を示します
- やり取りに関する詳細情報を記録します
スクリプト内のテストクエリを変更することで、システムのさまざまな機能を調査できます。スクリプトはscripts/testLlmWithMcpServer.jsにあります。
前提条件
- Node.js 23以降
- RAGmonstersデータを含むPostgreSQLデータベース
- LLM API（例：OpenAI）へのアクセス
- FastMCP パッケージ (依存関係に含まれています)
環境変数
次の変数を含む.envファイルを作成します。
# PostgreSQL connection string
POSTGRESQL_ADDON_URI=postgres://username:password@host:port/database
# LLM API configuration
LLM_API_KEY=your_openai_api_key
LLM_API_MODEL=gpt-4o-mini
LLM_API_URL=https://api.openai.com/v1
LLM 構成
- LLM_API_KEY : OpenAI APIキーまたは互換性のあるプロバイダーキー
- LLM_API_MODEL : 使用するモデル（デフォルト: gpt-4o-mini）
- LLM_API_URL : APIエンドポイント（デフォルト: OpenAIのエンドポイント）
アプリケーションは、セルフホスト モデルや代替プロバイダーを含む、OpenAI 互換の API をすべてサポートします。
Clever Cloudへの導入
Clever Cloud CLIの使用
- Clever Cloud CLI をインストールします。
npm install -g clever-tools
- Clever Cloud アカウントにログインします。
- 新しいアプリケーションを作成します。
clever create --type node <APP_NAME>
- ドメインを追加します (オプションですが推奨されます):
clever domain add <YOUR_DOMAIN_NAME>
- PostgreSQL アドオンを作成し、アプリケーションにリンクします。
clever addon create <APP_NAME>-pg --plan dev
clever service link-addon <APP_NAME>-pg
POSTGRESQL_ADDON_URI環境変数が自動的に設定されます。 - 必要な環境変数を設定します。
clever env set LLM_API_KEY "your-openai-api-key"
clever env set LLM_API_MODEL "gpt-4o-mini" # Optional, defaults to gpt-4o-mini
clever env set LLM_API_URL "https://api.your-llm-provider.com" # Optional, for alternative OpenAI-compatible providers
- アプリケーションをデプロイします。
- アプリケーションを開きます:
Clever Cloud Consoleの使用
Clever Cloud Consoleから直接デプロイすることもできます。
- コンソールで新しいアプリケーションを作成する
- ランタイムとしてNode.jsを選択する
- PostgreSQLアドオンを作成し、アプリケーションにリンクする
- コンソールで必要な環境変数を設定します。
LLM_API_KEY : OpenAI APIキーLLM_API_MODEL : (オプション) 使用するモデル。デフォルトは gpt-4o-mini
- Git または GitHub 統合を使用してアプリケーションをデプロイする
重要な注意事項
POSTGRESQL_ADDON_URI環境変数は、PostgreSQLアドオンをアプリケーションにリンクすると、Clever Cloudによって自動的に設定されます。- アプリケーションにはNode.js 20以降が必要です。これはClever Cloudで入手できます。
- アプリケーションは、Clever Cloud 上の Node.js アプリケーションのデフォルト ポートであるポート 8080 で自動的に実行されます。
ライセンス
このプロジェクトは MIT ライセンスに基づいてライセンスされています - 詳細については LICENSE ファイルを参照してください。
謝辞