sql-talk/docs/cursor-setup.md

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

# 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
```

### 2. 設定ファイルの準備

```bash
# 設定ファイルテンプレートを作成
npx mcp-db init-config

# データベース接続情報を設定
cp mcp-db.config.yaml config/mcp-db.config.yaml
```

`config/mcp-db.config.yaml` を編集：

```yaml
engine: postgres
connections:
  read_only:
    host: localhost
    port: 5432
    user: your_readonly_user
    password: your_readonly_password
    database: your_database
  ddl_comment:
    host: localhost  
    port: 5432
    user: your_comment_user
    password: your_comment_password
    database: your_database

limits:
  default_limit: 200
  max_limit: 10000
  timeout_ms: 5000

pii:
  column_patterns:
    - "name|氏名|名前"
    - "email|メール"
    - "phone|電話"
  masking:
    enabled: true
    strategy: partial

audit:
  sink: file
  path: ./logs/audit.ndjson
```

### 3. データベース接続テスト

```bash
# 接続確認
npx mcp-db test-connection -c config/mcp-db.config.yaml

# スキーマキャッシュの初期化
npx mcp-db refresh-schema -c config/mcp-db.config.yaml
```

### 4. Cursor MCP 設定

Cursorの設定ファイル（通常は `~/.cursor/mcp_servers.json` または Cursor設定内）に以下を追加：

```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"
      }
    }
  }
}
```

**重要**: パスは絶対パスで指定してください。

### 5. Cursor の再起動

設定を適用するため、Cursorを完全に再起動してください。

## 💡 使用方法

### 基本的な自然言語クエリ

Cursor内でAIチャットを開き、以下のように質問：

```
データベースの利用者テーブルから、最新の10件の利用者情報を取得して
```

```  
2024年9月の請求データを事業所別に集計して、件数の多い順で表示して
```

```
過去30日間のサービス利用状況を確認したい
```

### MCPツールの直接利用

#### スキーマ情報の取得
```
@nl-to-sql describe_schema コマンドでデータベーススキーマを表示して
```

#### SQL生成と実行
```
@nl-to-sql propose_sql で「今月の売上を事業所別に集計」のSQLを生成
```

```
@nl-to-sql execute_readonly で生成されたSQLを実行
```

#### コメント管理
```
@nl-to-sql propose_missing_comments でコメント不足のテーブル・カラムを確認
```

## 🔧 高度な設定

### 環境変数での設定

`.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/custom.yml
abbr:
  svc: サービス
  usr: ユーザー
  amt: 金額

synonym:
  user: 利用者
  service: サービス
  facility: 事業所
```

### 本番環境用設定

```json
{
  "mcpServers": {
    "nl-to-sql-prod": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/opt/mcp-nl-to-sql",
      "env": {
        "CONFIG_PATH": "/etc/mcp/production.config.yaml",
        "NODE_ENV": "production",
        "LOG_LEVEL": "warn"
      }
    }
  }
}
```

## 🛡️ セキュリティ考慮事項

### データベース権限設定

**読み取り専用ユーザー** (推奨):
```sql
-- PostgreSQLの例
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;
```

**コメント用ユーザー** (オプション):
```sql  
-- PostgreSQLの例
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;
```

### PII保護設定

本番環境では厳格なPIIマスキングを有効化：

```yaml
pii:
  column_patterns:
    - "name|氏名|名前|姓名"
    - "address|住所|所在地"  
    - "phone|tel|電話|携帯"
    - "email|メール|mail"
    - "birth|生年月日|誕生日"
    - "insurance|保険|被保険者"
  masking:
    enabled: true
    strategy: hash  # 本番ではハッシュ化推奨
```

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

### 接続エラー
```bash
# 設定テスト
npx mcp-db test-connection

# ログ確認
tail -f logs/combined.log
```

### スキーマが空の場合
```bash  
# 手動でスキーマ更新
npx mcp-db refresh-schema --scope all

# キャッシュ確認
npx mcp-db show-schema
```

### Cursorで認識されない場合
1. Cursorを完全再起動
2. パスが絶対パスか確認
3. Node.jsのバージョン確認 (20+必須)
4. ビルドが完了しているか確認

### 権限エラー
```bash  
# ディレクトリ権限確認
ls -la logs/
ls -la .cache/

# 必要に応じて権限修正
chmod 755 logs/ .cache/
```

## 📚 関連ドキュメント

- [設定リファレンス](../README.md#configuration-reference)
- [MCPツール仕様](../README.md#available-tools)
- [セキュリティガイド](../README.md#security-features)
- [API仕様](./api.md)