MCP Sql

🚀 MCP Database Assistant

このプロジェクトは、OpenAIのGPTモデルとModel Context Protocol (MCP) を用いて構築されたAI搭載のマルチデータベースアシスタントです。自然言語でのリクエストを理解し、MySQL、Oracle、SQLiteデータベースを横断して完全なスキーマ認識を持ったSQLクエリを実行できる、インテリジェントなデータベースクエリインターフェースの作成方法を実証しています。

✨ 主な機能

• 🤖 AI搭載のSQLアシスタント - OpenAI GPT-4oを使用した自然言語からSQLクエリへの変換
• 🔧 モデルコンテキストプロトコルの統合 - シームレスなツール呼び出しとコンテキスト管理
• 🗄️ マルチデータベースサポート - MySQL、Oracle、SQLiteデータベースで動作
• 🌐 モダンなWebインターフェース - クリーンでレスポンシブなチャットインターフェースとリアルタイムクエリ処理
• 📊 スキーマ探索 - 自動的なデータベース構造の探索と検証
• 🔍 スマート検索 - キーワードでテーブルと列を検索
• 💾 セッション管理 - ブラウザセッション中の永続的なチャット履歴
• ⚡ リアルタイム処理 - 高速なクエリ実行のための非同期処理
• 🛡️ 安全なクエリ実行 - エラーハンドリング付きの保護されたSQL実行
• 🔄 デュアルAPIサポート - 異なるフロントエンドの要件に対応する複数のエンドポイント形式

📋 前提条件

• Python 3.12以上 (.python-versionで指定)
• OpenAI APIキー - OpenAI Platform から取得
• データベース - 以下のいずれか:
  • SQLiteデータベースファイル (.db)
  • アクセス可能なデータベースを持つMySQLサーバー
  • 適切な接続文字列のあるOracleデータベース

📦 インストール

1. uvをインストールする (まだインストールしていない場合)

macOS/Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows:

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

代替方法 (pipを使用):

pip install uv

2. プロジェクトをクローンしてセットアップする

git clone https://github.com/sharansahu/mcp-sql
cd mcp-sql

# 仮想環境を作成し、依存関係をインストールする
uv sync

3. 環境構成

プロジェクトのルートに.envファイルを作成し、データベースの構成を設定します。

SQLiteの場合:

# OpenAI構成
OPENAI_API_KEY=your_openai_api_key_here

# データベース構成
DB_TYPE=sqlite
DB_PATH=./dod_synthetic.db

MySQLの場合:

# OpenAI構成  
OPENAI_API_KEY=your_openai_api_key_here

# データベース構成
DB_TYPE=mysql
DB_HOST=localhost
DB_PORT=3306
DB_NAME=your_database_name
DB_USER=your_username
DB_PASSWORD=your_password

Oracleの場合:

# OpenAI構成
OPENAI_API_KEY=your_openai_api_key_here

# データベース構成
DB_TYPE=oracle
DB_USER=your_username
DB_PASSWORD=your_password
DB_DSN=hostname:port/service_name

📁 プロジェクト構造

mcp-database-assistant/
├── README.md           # プロジェクトドキュメント
├── mcp_client.py       # Flaskウェブアプリケーション (メインエントリポイント)
├── servers/            # MCPサーバーの実装
│   ├── mcp_server_sqlite.py   # データベースツール付きのSQLite MCPサーバー
│   ├── mcp_server_mysql.py    # データベースツール付きのMySQL MCPサーバー  
│   └── mcp_server_oracle.py   # データベースツール付きのOracle MCPサーバー
├── dod_synthetic.db    # サンプルSQLiteデータベース (SQLiteを使用する場合)
├── pyproject.toml      # プロジェクトの依存関係と構成
├── .env                # 環境変数 (これを作成する)
├── .python-version     # Pythonバージョンの指定
├── static/             # ウェブインターフェースファイル
│   ├── index.html      # メインウェブインターフェース
│   ├── script.js       # フロントエンドJavaScript
│   └── styles.css      # インターフェースのスタイリング
├── .gitignore          # Gitの無視ファイル
└── .venv/              # 仮想環境 (uvによって作成される)

💻 使用例

ウェブインターフェース (推奨)

1. Flaskアプリケーションを起動する:

   uv run python mcp_client.py
   

2. ウェブインターフェースにアクセスする: ブラウザを開き、以下のURLにアクセスします: http://localhost:10000

3. クエリを開始する:

   • データベースに関する自然言語の質問を入力します。
   • 例: "データベース内のすべてのテーブルを表示してください"
   • 例: "過去90日間にタンクのメンテナンスに従事した人員を検索してください"
   • 例: "usersテーブルの構造を教えてください"

クエリ例

AIアシスタントは、さまざまなタイプのデータベースクエリを処理できます。

スキーマ探索

• "このデータベースで利用可能なテーブルは何ですか？"
• "personnelテーブルの構造を説明してください"
• "メンテナンスに関連するテーブルを検索してください"
• "すべてのテーブルのスキーマを表示してください"

データ分析

• "各テーブルには何件のレコードがありますか？"
• "最初の5件のpersonnelレコードを表示してください"
• "タイプが'tank'のすべての機器を検索してください"
• "ordersテーブルの列名は何ですか？"

複雑なクエリ

• "過去90日間にタンクのメンテナンスを行った人員を表示してください"
• "1人あたりの平均メンテナンスタスク数は何ですか？"
• "最近メンテナンスされていない機器を一覧表示してください"
• "注文金額の上位10人の顧客を検索してください"

🛠️ データベースツール

MCPサーバーは、データベースとのやり取りのためのいくつかの強力なツールを提供します。

• get_schema() - サンプルデータ付きの完全なデータベーススキーマを取得する
• list_tables() - 利用可能なすべてのテーブルを一覧表示する
• describe_table(table_name) - 列とサンプルデータを含む詳細なテーブル情報を取得する
• search_tables(keyword) - キーワードでテーブル/列を検索する
• query_data(sql) - SQLクエリを安全に実行する

📡 APIエンドポイント

Flaskアプリは、いくつかのREST APIエンドポイントを提供します。

• GET / - メインウェブインターフェースを提供する
• POST /api/query - 自然言語クエリを処理する (詳細なステータスを返す)
• POST /api/chat - 代替のクエリエンドポイント (簡略化されたレスポンスを返す)
• POST /api/clear - チャットセッションの履歴をクリアする
• GET /api/history - チャット履歴を取得する
• GET /health - ヘルスチェックエンドポイント

🔍 仕組み

1. データベースタイプの検出 - システムはDB_TYPE環境変数に基づいて適切なMCPサーバーをロードします。
2. ユーザー入力 - ウェブインターフェースを介した自然言語クエリ
3. スキーマ探索 - AIはMCPツールを使用してデータベース構造を探索します。
4. クエリ生成 - AIはスキーマとデータベースタイプに基づいて適切なSQLを生成します。
5. 安全な実行 - SQLクエリは適切なエラーハンドリングで実行されます。
6. 結果の整形 - 結果は整形され、ユーザーに返されます。
7. セッション管理 - 会話履歴はコンテキストのために維持されます。

🔧 データベース固有の機能

SQLite

• ファイルベースのデータベースサポート
• 完全なスキーマイントロスペクション
• サンプルデータのプレビュー

MySQL

• コネクションプーリング
• 適切な照合順序でのUTF-8サポート
• 主キーの検出
• 行カウントとサンプルデータ

Oracle

• 大文字小文字を区別するテーブル/列の処理
• ROWNUMベースのページネーション
• 主キー制約の検出
• ユーザースキーマの認識

🚨 トラブルシューティング

一般的な問題

"Invalid DB_TYPE"エラー

• DB_TYPEがsqlite、mysql、またはoracleのいずれかに設定されていることを確認してください。
• .envファイルが正しくフォーマットされていることを確認してください。

"No module named 'openai'"

uv sync  # 依存関係を再インストールする

"OPENAI_API_KEY not found"

• .envファイルが存在し、APIキーが含まれていることを確認してください。
• APIキーが有効で、十分なクレジットがあることを確認してください。

データベース接続エラー

• SQLite: DB_PATHがデータベースファイルを指していることを確認してください。
• MySQL: DB_HOST、DB_PORT、DB_NAME、DB_USER、およびDB_PASSWORDを確認してください。
• Oracle: DB_USER、DB_PASSWORD、およびDB_DSNの形式を確認してください。

ウェブインターフェースが読み込まれない

• Flaskが正しいポート (10000) で実行されていることを確認してください。
• 静的ファイルがstatic/ディレクトリにあることを確認してください。

データベース固有の問題

MySQL接続問題:

• MySQLサーバーが実行中であることを確認してください。
• ユーザーが適切な権限を持っていることを確認してください。
• リモートで接続する場合は、ファイアウォールの設定を確認してください。

Oracle接続問題:

• Oracle Instant Clientがインストールされていることを確認してください。
• TNS名の構成を確認してください。
• DSN内のサービス名が正しいことを確認してください。

デバッグモード

追加のログを表示して実行するには、以下のコマンドを使用します。

FLASK_DEBUG=True uv run python mcp_client.py

🛡️ セキュリティに関する考慮事項

• 実際の資格情報を含む.envファイルを決してコミットしないでください。
• 本番環境では環境変数または安全なボールトを使用してください。
• 適切なデータベースユーザー権限を実装してください。
• SQLインジェクション保護 (MCPツールに組み込まれています) を検討してください。
• 本番環境ではHTTPSを使用してください。

🚀 デプロイメント

ローカル開発

現在の設定は、Flask開発サーバーを使用したローカル開発に最適化されています。

📄 ライセンス

このプロジェクトはMITライセンスの下でライセンスされています。詳細については、LICENSE ファイルを参照してください。