# MCP Parking Server

駐車場管理システム用の読み取り専用MCPサーバーです。
自然言語の質問に対して、データベースを参照し日本語で回答します。

## 機能

- 駐車場の検索（名前・コード・ID）
- 課金設定の取得（再課金猶予時間、夜間料金など）
- 読み取り専用SQLの実行
- スキーマコンテキストによる業務理解支援

## セットアップ

### 1. 依存関係のインストール

```bash
pip install -e .
```

### 2. 環境変数の設定

```bash
cp .env.example .env
# .env ファイルを編集してデータベース接続情報を設定
```

### 3. データベースユーザーの作成（推奨）

```sql
-- 読み取り専用ユーザーを作成
CREATE USER 'readonly_user'@'%' IDENTIFIED BY 'secure_password';

-- SELECT権限のみを付与
GRANT SELECT ON parking_system.parkings TO 'readonly_user'@'%';
GRANT SELECT ON parking_system.parking_configs TO 'readonly_user'@'%';
GRANT SELECT ON parking_system.parking_rates TO 'readonly_user'@'%';
GRANT SELECT ON parking_system.parking_sessions TO 'readonly_user'@'%';

FLUSH PRIVILEGES;
```

### 4. サーバーの起動

```bash
mcp-parking-server
```

## MCP クライアントからの接続

### Claude Desktop での設定例

`claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "parking": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/mcp-parking-server",
      "env": {
        "DB_HOST": "localhost",
        "DB_PORT": "3306",
        "DB_USER": "readonly_user",
        "DB_PASSWORD": "secure_password",
        "DB_NAME": "parking_system"
      }
    }
  }
}
```

## ツール一覧

| ツール名 | 説明 |
|---------|------|
| `search_parking` | 駐車場を検索（名前・コード・ID） |
| `get_parking_config` | 駐車場の設定を取得 |
| `get_night_rate_config` | 夜間料金設定を取得 |
| `execute_readonly_sql` | 読み取り専用SQLを実行 |
| `get_schema_context` | スキーマの業務コンテキストを取得 |
| `explain_term` | 業務用語を説明 |
| `suggest_approach` | クエリアプローチを提案 |

## プロジェクト構造

```
mcp-parking-server/
├── src/
│   ├── __init__.py
│   ├── server.py          # MCPサーバー本体
│   ├── database.py        # データベース接続
│   ├── schema_context.py  # スキーマコンテキスト管理
│   ├── sql_validator.py   # SQLバリデーション
│   └── tools.py           # ツール定義
├── config/
│   └── schema_context.json # スキーマ定義
├── docs/
│   └── examples.md        # 使用例
├── .env.example
├── pyproject.toml
└── README.md
```

## セキュリティ

詳細は下記「セキュリティガードレール」セクションを参照してください。

---

# セキュリティガードレール

このMCPサーバーは、エンタープライズ環境での安全な運用を前提に設計されています。

## 1. 多層防御アーキテクチャ

```
┌─────────────────────────────────────────────────────────┐
│                    MCP Client (Claude)                  │
└─────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│  Layer 1: ツールレベル制限                               │
│  - 事前定義されたツールのみ使用可能                       │
│  - 入力パラメータのバリデーション                        │
└─────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│  Layer 2: SQLバリデーション (sql_validator.py)          │
│  - SELECT文のみ許可                                      │
│  - 禁止キーワード・関数のブロック                        │
│  - テーブルホワイトリスト                                │
│  - LIMIT強制                                             │
└─────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│  Layer 3: データベース接続 (database.py)                │
│  - 読み取り専用トランザクション                          │
│  - クエリタイムアウト                                    │
│  - 接続プール制限                                        │
└─────────────────────────────────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│  Layer 4: データベースユーザー権限                       │
│  - SELECT権限のみ付与                                    │
│  - 対象テーブル限定                                      │
└─────────────────────────────────────────────────────────┘
```

## 2. SQLバリデーション詳細

### 2.1 禁止キーワード

以下のキーワードを含むクエリは拒否されます：

| カテゴリ | 禁止キーワード |
|---------|---------------|
| DML（データ変更） | INSERT, UPDATE, DELETE, REPLACE, TRUNCATE, MERGE |
| DDL（スキーマ変更） | CREATE, ALTER, DROP, RENAME |
| DCL（権限管理） | GRANT, REVOKE |
| トランザクション | COMMIT, ROLLBACK, SAVEPOINT |
| その他 | LOAD, HANDLER, CALL, EXECUTE, PREPARE |
| ファイル操作 | INTO OUTFILE, INTO DUMPFILE, LOAD_FILE |

### 2.2 禁止関数

SQLインジェクション対策として、以下の関数を禁止：

- `SLEEP()` - 時間ベース攻撃
- `BENCHMARK()` - 時間ベース攻撃
- `LOAD_FILE()` - ファイル読み取り

### 2.3 テーブルホワイトリスト

アクセス可能なテーブルを明示的に制限：

```python
ALLOWED_TABLES = [
    "parkings",
    "parking_configs",
    "parking_rates",
    "parking_sessions",
]
```

### 2.4 その他の制限

| 制限項目 | 内容 |
|---------|------|
| 複文実行 | セミコロンによる複数SQL実行を禁止 |
| コメント | `--`, `/**/`, `#` を禁止 |
| UNION | UNIONインジェクション対策として禁止 |
| サブクエリ | 最大1階層まで |
| LIMIT | 必須（自動付与）、最大1000件 |

## 3. データベースレベルの保護

### 3.1 読み取り専用トランザクション

```python
# 接続時に読み取り専用モードを設定
await cursor.execute("SET SESSION TRANSACTION READ ONLY")
```

### 3.2 タイムアウト制御

```python
# クエリタイムアウト（デフォルト30秒）
await asyncio.wait_for(
    cursor.execute(query, params),
    timeout=self.config.query_timeout
)
```

### 3.3 接続プール制限

```python
# 同時接続数を制限
pool_min_size=1
pool_max_size=5
```

## 4. 推奨されるデータベース設定

### 4.1 専用の読み取り専用ユーザー

```sql
-- 最小権限の原則に従ったユーザー作成
CREATE USER 'mcp_readonly'@'%' IDENTIFIED BY 'strong_password';

-- 必要なテーブルにのみSELECT権限を付与
GRANT SELECT ON parking_system.parkings TO 'mcp_readonly'@'%';
GRANT SELECT ON parking_system.parking_configs TO 'mcp_readonly'@'%';
GRANT SELECT ON parking_system.parking_rates TO 'mcp_readonly'@'%';
GRANT SELECT ON parking_system.parking_sessions TO 'mcp_readonly'@'%';

-- 権限を反映
FLUSH PRIVILEGES;
```

### 4.2 リードレプリカの使用（推奨）

本番環境では、リードレプリカに接続することを推奨します：

```
DB_HOST=replica.parking-db.internal
```

## 5. 監査とログ

### 5.1 アプリケーションログ

```python
# 全てのツール呼び出しをログ記録
logger.info(f"Tool called: {name} with args: {arguments}")
```

### 5.2 推奨される追加対策

- クエリログの永続化（CloudWatch Logs等）
- 異常なクエリパターンのアラート設定
- 定期的なアクセスログレビュー

## 6. プライバシー保護

### 6.1 個人情報の取り扱い

`parking_sessions.vehicle_number`（車両番号）は個人情報に該当する可能性があります。
スキーマコンテキストでこれを明示し、不必要なアクセスを抑制します：

```json
{
  "privacy_note": "vehicle_number は個人情報に該当する可能性があるため、必要最小限の参照に留める"
}
```

### 6.2 データマスキング（オプション）

必要に応じて、機密カラムのマスキングを実装できます：

```sql
-- マスキングの例
SELECT
    id,
    CONCAT(LEFT(vehicle_number, 2), '****') as vehicle_number_masked
FROM parking_sessions
```

## 7. 障害対策

| 障害シナリオ | 対策 |
|-------------|------|
| DB接続失敗 | 明確なエラーメッセージを返却 |
| クエリタイムアウト | 30秒でタイムアウト、エラー返却 |
| 不正なSQL | バリデーションエラーを返却 |
| 大量データ | LIMITによる件数制限 |

## 8. セキュリティチェックリスト

デプロイ前に以下を確認してください：

- [ ] データベースユーザーはSELECT権限のみ持っている
- [ ] 環境変数でパスワードを管理している（ハードコードしていない）
- [ ] リードレプリカまたは専用の参照用DBに接続している
- [ ] ネットワークアクセスが制限されている（VPC内など）
- [ ] アプリケーションログが有効になっている
- [ ] schema_context.json のテーブル一覧が実際のホワイトリストと一致している