# ピティナ・ピアノ曲事典 MCP サーバー

[ピティナ・ピアノ曲事典](https://enc.piano.or.jp/) を「正典（マスター）」として、
コンサート・プログラムの**曲名・作曲家名の表記揺れを校正**するための MCP サーバー。

曖昧な曲名を投げると、本家の**正式タイトル・作曲家名・作品番号・演奏時間**が返る。

> ℹ️ ピティナ非公式の個人ツールです。曲事典の解説文などの著作権はピティナ／原著作者に帰属します。
> 個人利用・校正はOKですが、出力の転載や大量アクセスはしないでください。

## できること（ツール）

| ツール | 用途 |
| --- | --- |
| `search_pieces(keyword, limit=20)` | 曲名/作曲家のキーワードで楽曲検索。正式タイトル・作曲家・opus・演奏時間・曲IDの候補一覧（**校正の中心**） |
| `get_piece(piece_id)` | 楽曲IDから詳細（正式タイトル・原題・opus・解説冒頭） |
| `search_composers(name, limit=20)` | 作曲家名の正式表記・IDを検索 |
| `get_composer(composer_id)` | 作曲家プロフィール＋作品リスト |

### 校正の使い方（例）
プログラムに「ブルグミュラー 貴婦人の乗馬」とある →
`search_pieces("ブルグミュラー 貴婦人の乗馬")` →
正式タイトル `25の練習曲 貴婦人の乗馬`、作曲家 `ブルクミュラー（ブルグミュラー）`、
作品番号 `Op.100-25` が返る。これを正典として採用。

## セットアップ

```bash
cd /Users/miku/ptna-enc-mcp
python3 -m venv .venv
.venv/bin/pip install -e .
```

## Claude Code への登録

```bash
claude mcp add ptna-enc -- /Users/miku/ptna-enc-mcp/.venv/bin/ptna-enc-mcp
```

登録後、Claude Code の会話から「ピティナで『◯◯』の正式表記調べて」と頼めば使える。
確認: `claude mcp list` に `ptna-enc` が出ればOK。

## 動作確認

```bash
.venv/bin/python tests/test_parse.py        # パーサ単体テスト(ネット不要)
```

## 設定（環境変数・任意）

| 変数 | 既定 | 意味 |
| --- | --- | --- |
| `PTNA_ENC_MIN_INTERVAL` | `1.5` | 最小リクエスト間隔（秒） |
| `PTNA_ENC_CACHE_TTL` | `86400` | ページキャッシュ有効期間（秒）。`0`で無効 |
| `PTNA_ENC_CACHE_DIR` | `~/.cache/ptna-enc-mcp` | キャッシュ保存先 |
| `PTNA_ENC_USER_AGENT` | ツール名＋連絡先 | 送信 User-Agent |

## 設計・スクレイピングの方針

- API 非提供のサイトのため **HTML スクレイピング**。事前クロール／DB は持たず、
  TTL キャッシュで「一度見たページを覚える」だけ（運用ゼロ）。
- 都度1件のみ取得し、独自 User-Agent 明示＋リクエスト間隔を守る（礼儀レイヤ）。
- 高度フィルタ（ジャンル/調性/ステップレベル）はサイトが JS 描画するため v1 では未対応。

詳細は [`docs/superpowers/specs/2026-08-07-ptna-enc-mcp-design.md`](docs/superpowers/specs/2026-08-07-ptna-enc-mcp-design.md)。