sql-talk

Version:

SQL Talk - 自然言語をSQLに変換するMCPサーバー（安全性保護・SSHトンネル対応） / SQL Talk - MCP Server for Natural Language to SQL conversion with safety guards and SSH tunnel support

424 lines (324 loc) • 9.81 kB

Markdown

# Cursor での MCP NL-to-SQL サーバー設定ガイド ## 📋 概要このガイドでは、CursorエディターにMCP NL-to-SQLサーバーを登録し、自然言語でデータベースクエリを実行する方法を説明します。 ## 🚀 セットアップ手順 ### 1. プロジェクトのビルド ```bash # プロジェクトディレクトリに移動 cd /path/to/mcp-nl-to-sql # 依存関係のインストール npm install # TypeScriptのビルド npm run build # または自動セットアップ npm run setup:cursor ``` ### 2. データベース準備 #### PostgreSQLの場合 ```sql -- 読み取り専用ユーザーの作成 CREATE USER mcp_readonly WITH PASSWORD 'secure_password'; GRANT USAGE ON SCHEMA public TO mcp_readonly; GRANT SELECT ON ALL TABLES IN SCHEMA public TO mcp_readonly; GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA public TO mcp_readonly; -- コメント用ユーザーの作成（オプション） CREATE USER mcp_comment WITH PASSWORD 'secure_password'; GRANT USAGE ON SCHEMA public TO mcp_comment; GRANT SELECT ON ALL TABLES IN SCHEMA public TO mcp_comment; -- 将来のテーブルにも権限を付与 ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO mcp_comment; ``` #### MySQLの場合 ```sql -- 読み取り専用ユーザーの作成 CREATE USER 'mcp_readonly'@'%' IDENTIFIED BY 'secure_password'; GRANT SELECT ON your_database.* TO 'mcp_readonly'@'%'; -- コメント用ユーザーの作成（オプション） CREATE USER 'mcp_comment'@'%' IDENTIFIED BY 'secure_password'; GRANT SELECT ON your_database.* TO 'mcp_comment'@'%'; GRANT ALTER ON your_database.* TO 'mcp_comment'@'%'; FLUSH PRIVILEGES; ``` ### 3. 設定ファイルの準備 ```bash # 設定ファイルテンプレートを作成 npx mcp-db init-config # データベース接続情報を設定 cp mcp-db.config.yaml config/mcp-db.config.yaml ``` `config/mcp-db.config.yaml` を編集： ```yaml engine: postgres # または mysql connections: read_only: host: localhost port: 5432 user: mcp_readonly password: secure_password database: your_database ssl: false ddl_comment: host: localhost port: 5432 user: mcp_comment password: secure_password database: your_database ssl: false limits: default_limit: 200 max_limit: 10000 timeout_ms: 5000 pii: column_patterns: - "name|氏名|名前" - "email|メール" - "phone|電話|tel" - "address|住所" - "birth|生年月日|誕生日" masking: enabled: true strategy: partial audit: sink: file path: ./logs/audit.ndjson ``` ### 4. 接続テスト ```bash # データベース接続の確認 npx mcp-db test-connection -c config/mcp-db.config.yaml # スキーマキャッシュの初期化 npx mcp-db refresh-schema -c config/mcp-db.config.yaml # スキーマ情報の確認 npx mcp-db show-schema -c config/mcp-db.config.yaml ``` ### 5. Cursor MCP 設定 Cursorの設定ファイルに以下を追加します。設定場所は以下のいずれかです： - `~/.cursor/mcp_servers.json` - Cursor設定画面内のMCP設定セクション ```json { "mcpServers": { "nl-to-sql": { "command": "node", "args": ["dist/index.js"], "cwd": "/absolute/path/to/mcp-nl-to-sql", "env": { "CONFIG_PATH": "/absolute/path/to/mcp-nl-to-sql/config/mcp-db.config.yaml", "NODE_ENV": "production" } } } } ``` **重要**: パスは必ず絶対パスで指定してください。 ### 6. Cursor の再起動設定を適用するため、Cursorを完全に再起動してください。 ## 💡 使用方法 ### 基本的な自然言語クエリ Cursor内でAIチャットを開き、以下のように質問： ``` データベースの利用者テーブルから、最新の10件の利用者情報を取得して ``` ``` 2024年9月の請求データを事業所別に集計して、件数の多い順で表示して ``` ``` 過去30日間のサービス利用状況を確認したい ``` ``` ユーザーテーブルで個人情報が含まれている可能性のあるカラムをチェックして ``` ### MCPツールの直接利用 #### スキーマ情報の取得 ``` @nl-to-sql describe_schema でデータベーススキーマを表示して ``` #### SQL生成と実行 ``` @nl-to-sql propose_sql で「今月の売上を事業所別に集計」のSQLを生成 ``` ``` 先ほど生成したSQLを @nl-to-sql execute_readonly で実行 ``` #### コメント管理 ``` @nl-to-sql propose_missing_comments でコメント不足のテーブル・カラムを確認 ``` ``` @nl-to-sql render_comment_sql でコメント追加用のSQLを生成 ``` ## 🔧 高度な設定 ### 環境変数での管理 `.env` ファイルを作成： ```bash # データベース設定 DB_HOST=localhost DB_RO_PASSWORD=your_readonly_password DB_COMMENT_PASSWORD=your_comment_password # ログレベル LOG_LEVEL=info # 設定ファイルパス CONFIG_PATH=./config/mcp-db.config.yaml ``` ### カスタムドメイン辞書業界特有の用語辞書を作成： ```yaml # domain_dict/healthcare.yml abbr: pt: 患者 dr: 医師 rx: 処方箋 dx: 診断 synonym: patient: 患者 doctor: 医師 nurse: 看護師 medication: 薬剤 style: date: "YYYY年MM月DD日" time: "HH時MM分" ``` 設定ファイルで辞書を指定： ```yaml comment_infer: style: verbose dictionary_paths: - ./domain_dict/healthcare.yml - ./domain_dict/common.yml ``` ### 開発・本番環境の使い分け #### 開発環境用設定 ```yaml # config/development.yaml limits: default_limit: 1000 # 開発では多め max_limit: 10000 timeout_ms: 30000 # 長いタイムアウト pii: masking: enabled: false # 開発では無効 audit: sink: stdout # コンソール出力 ``` #### 本番環境用設定 ```yaml # config/production.yaml limits: default_limit: 100 # 本番では控えめ max_limit: 1000 timeout_ms: 5000 # 短いタイムアウト pii: masking: enabled: true strategy: hash # 本番ではハッシュ化 audit: sink: file path: /var/log/mcp/audit.ndjson ``` ## 🛡️ セキュリティのベストプラクティス ### データベース権限の最小化 ```sql -- PostgreSQL: 必要最小限の権限のみ REVOKE ALL ON SCHEMA public FROM mcp_readonly; GRANT USAGE ON SCHEMA public TO mcp_readonly; GRANT SELECT ON specific_table1, specific_table2 TO mcp_readonly; ``` ### PII保護の強化 ```yaml pii: column_patterns: # 日本の個人情報パターンを網羅 - "name|氏名|名前|姓名|フリガナ|カナ" - "address|住所|所在地|居住地|自宅住所" - "phone|tel|電話|携帯|fax|連絡先" - "email|メール|mail" - "birth|生年月日|誕生日|年齢|生日" - "insurance|保険|被保険者|保険証|保険番号" - "medical|診療|カルテ|病歴|既往歴" - "family|家族|配偶者|親族|緊急連絡先" # マイナンバー関連 - "mynumber|マイナンバー|個人番号" - "ssn|社会保障|年金番号" masking: enabled: true strategy: hash ``` ### 承認トークンの管理 ```bash # 承認トークンファイルの作成 mkdir -p .secrets echo "approval-token-$(date +%s)" > .secrets/approval.token chmod 600 .secrets/approval.token ``` ## 🚨 トラブルシューティング ### 接続エラー ```bash # 設定の確認 npx mcp-db test-connection # 詳細なログ確認 DEBUG=mcp:* npx mcp-db test-connection # データベース接続の直接確認 psql -h localhost -U mcp_readonly -d your_database -c "SELECT 1;" ``` ### スキーマキャッシュの問題 ```bash # キャッシュファイルの確認 cat .cache/schema_cache.json # 手動でスキーマ更新 npx mcp-db refresh-schema --scope all # 特定のテーブルのみ更新 npx mcp-db refresh-schema --scope tables --target "public.users" ``` ### Cursor認識の問題 1. **Cursorを完全再起動** - Cursor を終了 → プロセス確認 → 再起動 2. **設定ファイルの確認** ```bash # 設定ファイルの構文チェック node -e "console.log(JSON.parse(require('fs').readFileSync('~/.cursor/mcp_servers.json')))" ``` 3. **パスの確認** ```bash # 絶対パスが正しいか確認 ls -la /absolute/path/to/mcp-nl-to-sql/dist/index.js ``` 4. **Node.jsバージョン確認** ```bash # Node.js 20+ が必要 node --version ``` ### ログの確認 ```bash # リアルタイムログ監視 tail -f logs/combined.log # エラーログのみ確認 tail -f logs/error.log # 監査ログの確認 tail -f logs/audit.ndjson | jq '.' ``` ## 📈 パフォーマンス最適化 ### スキーマキャッシュの最適化 ```yaml schema_cache: path: /tmp/mcp-schema-cache.json # 高速ストレージ refresh_on_start: false # 本番では手動更新 ``` ### データベース接続の最適化 ```yaml connections: read_only: # ... 基本設定 ... ssl: true # 本番では SSL 有効 max_connections: 5 # 接続プール設定 idle_timeout: 30000 # アイドルタイムアウト ``` ### クエリパフォーマンスの監視 ```bash # 実行時間の長いクエリをログから抽出 grep -E '"elapsed_ms":[0-9]{4,}' logs/audit.ndjson ``` ## 📚 参考資料 - [MCP仕様書](https://spec.modelcontextprotocol.io/) - [Cursor MCP ドキュメント](https://docs.cursor.com/mcp) - [PostgreSQL権限管理](https://www.postgresql.org/docs/current/user-manag.html) - [MySQL権限管理](https://dev.mysql.com/doc/refman/8.0/en/access-control.html)