# Sakila MCP Server

MySQL（Sakilaデータベース）にアクセスするMCPサーバーのPython実装です。

## 概要

このプロジェクトは、[Model Context Protocol (MCP)](https://modelcontextprotocol.io/) を使用して、LLM（Claude等）からSakilaデータベースに自然言語でアクセスできるようにします。

**Intent-Based API設計**を採用し、データベーススキーマを非公開としながら、ビジネス意図ベースの18種類のツールを提供します。

### システム構成

```
┌─────────────────┐                         ┌─────────────────┐
│  ユーザー        │  自然言語               │  Claude (LLM)   │
│  (Human)        │ ─────────────────────► │  意図理解       │
└─────────────────┘                         └────────┬────────┘
                                                     │ ツール選択
                                                     ▼
┌─────────────────┐     MCP Protocol        ┌─────────────────┐
│  Claude Desktop │ ◄────────────────────► │  MCP Server     │
│  (Host)         │    stdio transport      │  (Python)       │
└─────────────────┘                         └────────┬────────┘
                                                     │ SQL生成・実行
                                                     │ aiomysql
                                                     ▼
                                            ┌─────────────────┐
                                            │  MySQL 8.0      │
                                            │  (Sakila DB)    │
                                            └─────────────────┘
```

### 設計思想

- **スキーマ非公開**: テーブル構造、カラム名、FK関係は一切公開しない
- **ビジネス意図ベース**: 「映画を検索する」「顧客詳細を取得する」などの意図に対応
- **セキュリティ重視**: パラメータ化クエリ、入力検証、エラーメッセージ制御

## 提供ツール（18種類）

### 映画検索・情報系

| ツール名 | 機能 | 主要パラメータ |
|---------|------|---------------|
| `search_films` | 映画検索（タイトル、カテゴリ、レーティング、俳優名） | title, category, rating, actor_name, limit |
| `get_film_details` | 映画詳細取得（出演者・在庫情報含む） | title |
| `list_categories` | カテゴリ一覧取得 | なし |
| `check_film_availability` | 在庫・貸出状況確認 | title, store_id |

### 顧客管理系

| ツール名 | 機能 | 主要パラメータ |
|---------|------|---------------|
| `search_customers` | 顧客検索 | name, email, store_id, active_only |
| `get_customer_details` | 顧客詳細取得（住所・履歴サマリー含む） | customer_id or email |

### レンタル業務系

| ツール名 | 機能 | 主要パラメータ |
|---------|------|---------------|
| `get_customer_rentals` | レンタル履歴取得 | customer_id, status |
| `get_overdue_rentals` | 延滞一覧取得 | store_id, days_overdue |

### 分析・レポート系

| ツール名 | 機能 | 主要パラメータ |
|---------|------|---------------|
| `get_popular_films` | 人気映画ランキング | period, category, store_id, limit |
| `get_revenue_summary` | 売上サマリー | group_by, store_id, period |
| `get_store_stats` | 店舗統計 | store_id |
| `get_actor_filmography` | 俳優の出演作品一覧 | actor_name |

### 顧客分析系

| ツール名 | 機能 | 主要パラメータ |
|---------|------|---------------|
| `get_top_customers` | 優良顧客ランキング | metric (rentals/spending), period, limit |
| `get_customer_segments` | 顧客セグメント分析 | なし（自動分類） |
| `get_customer_activity` | 顧客アクティビティ分析 | period |

### 在庫・商品分析系

| ツール名 | 機能 | 主要パラメータ |
|---------|------|---------------|
| `get_inventory_turnover` | 在庫回転率分析 | store_id, category |
| `get_category_performance` | カテゴリ別パフォーマンス | period, store_id |
| `get_underperforming_films` | 低稼働作品一覧 | days_not_rented, store_id |

## セットアップ

### 1. リポジトリのクローン

```bash
git clone <repository-url>
cd sakila-mcp-server
```

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

```bash
cp .env.example .env
# 必要に応じて .env を編集
```

### 3. MySQL の起動

```bash
docker compose up -d
```

初回起動時、Sakilaデータベースが自動的にインポートされます（約1-2分）。

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

```bash
uv sync
```

### 5. サーバーの起動（動作確認）

```bash
uv run sakila-mcp
```

## Claude Desktop への接続

`~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）または適切な設定ファイルに以下を追加：

```json
{
  "mcpServers": {
    "sakila": {
      "command": "uv",
      "args": ["--directory", "/path/to/sakila-mcp-server", "run", "sakila-mcp"]
    }
  }
}
```

## 使用例

Claude Desktopで以下のような質問ができます。

### 映画検索

- 「アクション映画を検索して」
- 「PG-13の映画を5本教えて」
- 「Tom Hanksが出演している映画は？」
- 「映画'ACADEMY DINOSAUR'の詳細を教えて」

### 顧客情報

- 「Smithという名前の顧客を検索して」
- 「顧客ID 1番の詳細情報を見せて」
- 「アクティブな顧客だけを検索して」

### レンタル業務

- 「顧客ID 1番のレンタル履歴を見せて」
- 「延滞している顧客は誰？」
- 「店舗1の延滞状況を確認して」

### 分析・レポート

- 「今月の人気映画ランキングを教えて」
- 「カテゴリ別の売上サマリーを見せて」
- 「店舗ごとの統計を比較して」
- 「優良顧客TOP10は？」

### 在庫分析

- 「在庫回転率が低い映画は？」
- 「カテゴリ別のパフォーマンスを分析して」
- 「30日以上レンタルされていない映画を教えて」

## 開発

### リント・フォーマット

```bash
# リント
uv run ruff check .

# リント（自動修正）
uv run ruff check --fix .

# フォーマット
uv run ruff format .

# フォーマットチェック
uv run ruff format --check .
```

### テスト

```bash
# 全テスト実行
uv run pytest

# ユニットテストのみ（DB不要）
uv run pytest -m "not integration"

# 統合テストのみ（DB起動後）
uv run pytest -m integration

# カバレッジ付き
uv run pytest --cov=sakila_mcp --cov-report=term-missing
```

## DB接続情報

| 項目 | 値 |
|------|-----|
| Host | localhost |
| Port | 3306 |
| Database | sakila |
| User | sakila_user |
| Password | sakila_pass |

## セキュリティ

### 実装済み対策

- **パラメータ化クエリ**: すべてのユーザー入力は`%s`プレースホルダー経由
- **入力検証**: 許可値リストによるバリデーション
  - rating: G, PG, PG-13, R, NC-17
  - store_id: 1, 2
  - period: all_time, last_month, last_week
  - 等
- **数値制限**: limitは最大50件
- **フィールド制限**: 返却JSONは必要フィールドのみ
- **エラーメッセージ**: SQLエラー詳細は非公開

## ディレクトリ構成

```
sakila-mcp-server/
├── CLAUDE.md             # 開発ガイド（Claude Code用）
├── README.md             # セットアップ手順（本ファイル）
├── docker-compose.yml    # MySQL 8.0 + Sakila自動セットアップ
├── init/
│   └── 01-init-sakila.sh # Sakila DB 初期化スクリプト
├── pyproject.toml        # 依存関係・ツール設定
├── .env.example          # 環境変数テンプレート
├── sakila_mcp/
│   ├── __init__.py
│   └── server.py         # MCPサーバー本体（18ツール実装）
└── tests/
    ├── __init__.py
    ├── conftest.py       # 共通fixtures
    └── test_server.py    # サーバーテスト（43テスト）
```

## ドキュメント

- [CLAUDE.md](CLAUDE.md) - 開発者向け詳細ガイド（アーキテクチャ、コーディング規約、テストパターン）
- [docs/SAKILA_DATABASE.md](docs/SAKILA_DATABASE.md) - Sakilaデータベース概要
- [docs/MCP_IMPLEMENTATION_PATTERNS.md](docs/MCP_IMPLEMENTATION_PATTERNS.md) - MCP実装パターンガイド

## 参考資料

- [MCP 公式ドキュメント](https://modelcontextprotocol.io/)
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
- [Sakila スキーマ](https://dev.mysql.com/doc/sakila/en/sakila-structure.html)

## ライセンス

MIT