PostgreSQL MCP Server with LLM Chat Example on Clever Cloud

Clever Cloud での LLM チャット例を備えた PostgreSQL MCP サーバー

概要

このリポジトリでは、Clever Cloud にデプロイした Node.js アプリケーションで、PostgreSQL 用の Model Context Protocol（MCP）サーバーと言語モデルを組み合わせ、PostgreSQL データベースに自然言語でクエリを実行する方法を紹介します。

このアプリケーションでは、ユーザーが自然言語で PostgreSQL データベースにクエリを実行できます。クエリは LLM を使って SQL に変換され、その後、MCP サーバーを使ってデータベースに対して実行されます。

アプリケーションの実行画面。PostgreSQL データベースに自然言語でクエリを実行する様子を示しています

サンプルデータ：RAGmonsters

この例では、サンプルデータとして RAGmonsters データセットを使用します。RAGmonsters は、検索拡張生成（RAG）システムのテストとデモンストレーション用に設計されたオープンデータセットです。豊富な属性、能力、関係性を持つ架空のモンスターに関する情報が含まれているため、自然言語クエリのデモンストレーションに最適です。

RAGmonsters の PostgreSQL 版は、複数のテーブルとリレーションシップを備えた、構造の整ったリレーショナルデータベースです。MCP を通じて自然言語処理と構造化データベースへのアクセスを組み合わせることで、強力な機能を活かした複雑なクエリを実行できます。

前提条件

• Clever Cloud のアカウント
• インストールおよび設定済みの Clever Tools CLI
• Node.js 23 以降
• PostgreSQL データベース
• LLM API へのアクセス（例：OpenAI）

プロジェクト構成

├── .env.example        # Example environment variables
├── package.json        # Node.js project configuration
├── README.md           # This documentation
├── img/                # Images for documentation
│   └── screenshot.jpg  # Application screenshot
├── scripts/
│   ├── initializeDb.js # Script to initialize the database with RAGmonsters data
│   └── testMCP.js      # Script to test MCP server with LLM integration
├── src/
│   ├── index.js        # Main application server
│   ├── llm.js          # LangChain integration for LLM
│   ├── mcp-client.js   # MCP client for PostgreSQL
│   └── public/         # Web interface files
│       └── index.html  # Chat interface

機能

• 自然言語を使った PostgreSQL データベースの調査
• 公式 PostgreSQL 実装との MCP サーバー統合
• LLM とのやり取りに対応する LangChain.js 統合
• データベースとチャットできるシンプルなウェブインターフェース
• API エンドポイントを備えた Express.js バックエンド

ローカル開発

1. このリポジトリをクローンします
2. 依存関係をインストールします：

npm install

3. .env.example を .env にコピーし、値を更新して環境変数を設定します：

cp .env.example .env

4. PostgreSQL の接続情報と LLM API キーを使って .env ファイルを更新します。

5. RAGmonsters のサンプルデータを使ってデータベースを初期化します：

node scripts/initializeDb.js

このスクリプトは RAGmonsters リポジトリをクローンし、サンプルデータを PostgreSQL データベースに取り込みます。

6. MCP サーバーと LLM の統合をテストします：

node scripts/testMCP.js

このスクリプトは MCP サーバーを使って PostgreSQL データベースに接続し、LLM を使って自然言語のクエリを SQL に変換します。ウェブインターフェースを使わずに、アプリケーションの主要な機能を実演します。

7. 開発サーバーを起動します：

npm run dev

アプリケーションには http://localhost:8080 からアクセスできます（または .env ファイルで指定したポートを使用します）。

仕組み

1. アプリケーションは、指定された接続情報を使って PostgreSQL データベースに接続します
2. MCP サーバーにより、標準化された方法でデータベースを操作できます
3. 自然言語で質問すると、アプリケーションは次の処理を行います：
   • MCP サーバーを使ってデータベースのスキーマを取得します
   • スキーマとともに質問を LLM に送信します
   • LLM が適切な SQL クエリを生成します
   • MCP サーバーを使ってデータベースに対してクエリを実行します
   • 結果をウェブインターフェースに表示します

testMCP.js でのテスト

testMCP.js スクリプトでは、Web インターフェースを使用せずにアプリケーションの主な機能を確認できます。

1. 環境の設定：PostgreSQL の接続 URI と LLM API キーを含む環境変数を .env ファイルから読み込みます
2. MCP サーバーの初期化：StdioClientTransport を使用して、PostgreSQL MCP サーバーを子プロセスとして起動します
3. LLM の統合：PostgreSQL の構文に関する詳細な指示を含めて、ChatOpenAI モデルを設定します
4. エージェントの作成：LLM と MCP ツールを組み合わせた LangChain ReAct エージェントを設定します
5. クエリの実行：自然言語のクエリを処理し、SQL に変換してデータベースに対して実行します
6. 結果の表示：整形されたレスポンスで結果を表示します

このスクリプトは、次の用途に役立ちます。

• データベース接続のテスト
• MCP サーバーが正常に動作していることの確認
• LLM が有効な PostgreSQL クエリを生成できることの確認
• Web インターフェースを使用せずに、データベースのスキーマとデータを調べる

Clever Cloud へのデプロイ

Clever Cloud CLI を使用する

1. Clever Cloud CLI をインストールします。

   npm install -g clever-tools
   

2. Clever Cloud アカウントにログインします。

   clever login
   

3. 新しいアプリケーションを作成します。

   clever create --type node <APP_NAME>
   

4. ドメインを追加します（任意ですが、追加をおすすめします）。

   clever domain add <YOUR_DOMAIN_NAME>
   

5. PostgreSQL アドオンを作成し、アプリケーションにリンクします。

   clever addon create <APP_NAME>-pg --plan dev
   clever service link-addon <APP_NAME>-pg
   

   これにより、POSTGRESQL_ADDON_URI 環境変数がアプリケーションに自動的に設定されます。

6. 必要な環境変数を設定します。

   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
   

7. アプリケーションをデプロイします。

   clever deploy
   

8. アプリケーションを開きます。

   clever open
   

Clever Cloud Console を使用する

Clever Cloud Console から直接デプロイすることもできます。

1. コンソールで新しいアプリケーションを作成します
2. ランタイムとして Node.js を選択します
3. PostgreSQL アドオンを作成し、アプリケーションにリンクします
4. コンソールで必要な環境変数を設定します。
   • LLM_API_KEY：OpenAI API キー
   • LLM_API_MODEL：（任意）使用するモデル。デフォルトは gpt-4o-mini です
5. Git または GitHub の統合を使用してアプリケーションをデプロイします

重要な注意事項

• PostgreSQL アドオンをアプリケーションにリンクすると、POSTGRESQL_ADDON_URI 環境変数は Clever Cloud によって自動的に設定されます
• このアプリケーションには Node.js 20 以降が必要です。Clever Cloud では利用できます
• このアプリケーションは、Clever Cloud の Node.js アプリケーションのデフォルトポートであるポート 8080 で自動的に実行されます

環境変数

アプリケーションの設定には、次の環境変数を使用します。

変数	説明	値の例	必須
POSTGRESQL_ADDON_URI	PostgreSQL の接続 URI（Clever Cloud によって自動的に提供されます）	postgresql://user:password@host:port/database	はい
PORT	サーバーがリッスンするポート	8080	いいえ（デフォルトは 8080）
LLM_API_KEY	OpenAI サービスの API キー	sk-...	はい
LLM_API_MODEL	LLM サービスで使用するモデル	gpt-4o-mini	いいえ（デフォルトは gpt-4o-mini）
LLM_API_URL	OpenAI 互換 API のベース URL	https://api.openai.com/v1	いいえ（デフォルトは OpenAI）

トラブルシューティング

問題が発生した場合は、次の項目を確認してください。

1. アプリケーションのログを確認します：clever logs
2. すべての環境変数が正しく設定されていることを確認します：clever env
3. アプリケーションが実行中であることを確認します：clever status

リソース

• Model Context Protocol のドキュメント
• LangChain.js のドキュメント
• Clever Cloud の Node.js 向けドキュメント
• Clever Cloud Console

ライセンス

このサンプルは MIT ライセンスの条件に基づいて提供されます。