Metadata-Version: 2.5
Name: horse-race-mcp
Version: 0.2.0
Summary: MCP server exposing the horse-race Turso DB and the V3 odds-pattern recommender to any MCP client (Claude Desktop, ChatGPT Developer Mode, Cursor, etc.). Supports stdio (local) and SSE/HTTP (remote) transports.
Project-URL: Homepage, https://github.com/yukito5669/horse-race
Project-URL: Issues, https://github.com/yukito5669/horse-race/issues
Author: yukito5669
License: MIT
Keywords: horse-racing,jra,libsql,mcp,turso
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: libsql-client>=0.3.1
Requires-Dist: mcp<2.0.0,>=1.0.0
Requires-Dist: pydantic>=2.0
Requires-Dist: starlette>=0.37
Requires-Dist: uvicorn>=0.30
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=7.4; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Description-Content-Type: text/markdown

# horse-race-mcp

JRA 競馬データベースと **V3 オッズパターン戦略**（累計 ROI 121.9%／16年中10年で100%超、`analysis/simulation_log.md` の全26仮説検証結果に基づく推奨戦略）を **Model Context Protocol (MCP)** 経由で公開するサーバーです。

**トランスポート両対応:**
- **stdio** — [Claude Desktop](https://claude.ai/download), [Cursor](https://www.cursor.com/), [Cline](https://cline.bot/) などローカルクライアント向け
- **SSE/HTTP** — [ChatGPT Developer Mode](https://chatgpt.com/) などリモートクライアント向け

## 提供ツール

### V3 戦略（DB 不要・純ロジック）

| ツール | 説明 |
|---|---|
| `classify_odds_pattern` | 単勝オッズから A:断然 / B:やや断然 / C:2強 / D:混戦 / E:大混戦 を機械判定 |
| `build_buy_order` | V3 戦略に基づくメイン買い目 + サブ(7-8番人気単勝 各100円) を組み立て。重馬場なら全見送り |

### データ検索（Turso DB 必要）

| ツール | 説明 |
|---|---|
| `query_races` | `race_information` を名前/年/グレード/競馬場で検索 |
| `get_race_results` | 1レースの全着順 + 払戻を取得 |
| `get_race_odds` | `race_odds` から確定単勝オッズを取得 |
| `get_current_entrants` | `jra_race_code` から、V3 ツール用の entrants 形式で返す |

### 統計分析

| ツール | 説明 |
|---|---|
| `get_popularity_roi` | 人気別の推定回収率を計算（グレード絞り込み可能） |
| `get_race_specific_roi` | レース名部分一致でそのレースの人気別 ROI（仮説#006 の判定基礎データ） |
| `get_condition_roi` | 馬場状態別の人気別 ROI |

### 馬券収支管理

| ツール | 説明 |
|---|---|
| `list_bet_records` | 購入履歴を日付範囲で取得 |
| `get_bet_summary` | 年次サマリー（投資額・払戻・損益・ROI） |
| `add_bet_record` | 新規購入を記録（`HORSE_RACE_MCP_ALLOW_WRITE=1` 必須） |
| `update_bet_result` | 結果確定後の更新（`HORSE_RACE_MCP_ALLOW_WRITE=1` 必須） |

## インストール

### PyPI から（公開後）

```bash
pip install horse-race-mcp
```

### GitHub から直接

```bash
pip install "horse-race-mcp @ git+https://github.com/yukito5669/horse-race.git#subdirectory=mcp-server"
```

### 開発用（ローカルclone）

```bash
cd mcp-server
pip install -e ".[dev]"
pytest
```

## 環境変数

| 変数 | 必須 | 説明 |
|---|---|---|
| `TURSO_URL` | DB系ツールを使う場合 | `libsql://[db-name]-[org].turso.io` |
| `TURSO_TOKEN` | DB系ツールを使う場合 | Turso 認証トークン |
| `HORSE_RACE_MCP_ALLOW_WRITE` | `add_bet_record`/`update_bet_result` を使う場合 | `1` を設定で有効 |
| `HORSE_RACE_MCP_API_KEY` | HTTP モード時に強く推奨 | Bearer トークン。設定されると全リクエストで `Authorization: Bearer <key>` を要求 |
| `HORSE_RACE_MCP_TRANSPORT` | — | `stdio`（既定）/ `http`。CLI `--transport` でも指定可 |
| `PORT` / `HORSE_RACE_MCP_PORT` | — | HTTP ポート（既定 8000、Fly.io は `PORT` を注入） |

V3 戦略ツール (`classify_odds_pattern`, `build_buy_order`) は環境変数なしで動作します。

## クライアント設定例

### Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "horse-race": {
      "command": "horse-race-mcp",
      "env": {
        "TURSO_URL": "libsql://your-db.turso.io",
        "TURSO_TOKEN": "eyJ..."
      }
    }
  }
}
```

### ChatGPT Desktop

ChatGPT (Pro/Business/Enterprise) は **remote MCP (SSE/HTTP)** が前提で、stdio は未対応です。
下記の「ChatGPT (Developer Mode) 接続 — Fly.io へのデプロイ」セクションを参照してください。

### Cursor (`.cursor/mcp.json`)

```json
{
  "mcpServers": {
    "horse-race": {
      "command": "horse-race-mcp",
      "env": {
        "TURSO_URL": "libsql://your-db.turso.io",
        "TURSO_TOKEN": "eyJ..."
      }
    }
  }
}
```

### Cline (VSCode 拡張 `cline_mcp_settings.json`)

```json
{
  "mcpServers": {
    "horse-race": {
      "command": "horse-race-mcp",
      "env": {
        "TURSO_URL": "libsql://your-db.turso.io",
        "TURSO_TOKEN": "eyJ..."
      }
    }
  }
}
```

### 書き込み権限付き（馬券記録もエージェント経由で）

```json
{
  "mcpServers": {
    "horse-race": {
      "command": "horse-race-mcp",
      "env": {
        "TURSO_URL": "libsql://your-db.turso.io",
        "TURSO_TOKEN": "eyJ...",
        "HORSE_RACE_MCP_ALLOW_WRITE": "1"
      }
    }
  }
}
```

## ChatGPT (Developer Mode) 接続 — Fly.io へのデプロイ

ChatGPT (Pro/Business/Enterprise) の **Developer Mode** は remote MCP サーバーを HTTPS/SSE で登録します。stdio ではなく HTTP サーバーが必要なので、Fly.io 等にホスティングします。

### 1. Fly.io CLI セットアップ

```bash
brew install flyctl
fly auth login
```

### 2. デプロイ

```bash
cd mcp-server

# 初回: アプリ作成（デプロイはしない）
fly launch --no-deploy --copy-config --name horse-race-mcp-<unique-suffix>
#   ↑ "horse-race-mcp" は世界で一意な名前が必要。例: horse-race-mcp-yukito

# シークレット設定（Bearer トークンは好きな長さの乱数を生成）
fly secrets set HORSE_RACE_MCP_API_KEY="$(openssl rand -hex 32)"
fly secrets set TURSO_URL="libsql://your-db.turso.io"
fly secrets set TURSO_TOKEN="eyJ..."

# 本番デプロイ
fly deploy
```

### 3. ヘルスチェック

```bash
curl https://horse-race-mcp-<suffix>.fly.dev/healthz
# → {"status":"ok","service":"horse-race-mcp","version":"0.2.0",...}
```

認証確認（トークン無しは 401）:

```bash
curl -I https://horse-race-mcp-<suffix>.fly.dev/sse
# → HTTP/2 401 unauthorized

curl -I -H "Authorization: Bearer <your-token>" \
    https://horse-race-mcp-<suffix>.fly.dev/sse
# → HTTP/2 200
```

### 4. ChatGPT に登録

1. https://chatgpt.com → 設定 → **Connectors** → **Create new connector**
2. **Custom MCP server** を選択
3. 入力:
   - **Name**: `horse-race`
   - **Description**: `JRA competitive horse racing V3 strategy`
   - **MCP Server URL**: `https://horse-race-mcp-<suffix>.fly.dev/sse`
   - **Authentication**:
     - Type: `Custom header`
     - Header: `Authorization`
     - Value: `Bearer <your-token>`
4. 保存すると接続テストが走り、成功すれば `horse-race` が Connector 一覧に追加
5. チャット画面の `+` → `Use connector` → `horse-race` を選択して会話開始

### 5. 使用例

ChatGPT に話しかける:

> 「2026年の天皇賞秋の予想して。1番人気クロワデュノール 2.5倍、2番人気マスカレードボール 2.9倍、3番人気レガレイラ 8.4倍」

→ ChatGPT が `classify_odds_pattern` ツールを呼び出し、`C:2強` 判定と推奨買い目を返します。

### 運用 Tips

- **コスト**: 無料枠で運用可能。`auto_stop_machines="stop"` でアイドル時に停止し、リクエスト時に起動（最初の呼び出しに 1〜2秒の cold start）
- **ログ**: `fly logs` でリアルタイム監視
- **再デプロイ**: コード変更後に `fly deploy` だけでOK
- **バージョン固定**: Dockerfile で `pip install horse-race-mcp==0.2.0` のように固定すれば、ローカル変更の影響を受けない

## クライアント設定例

### Claude Desktop (`~/Library/Application Support/Claude/claude_desktop_config.json`)

## 使い方（任意のエージェントから）

ツール名と JSON 入力の例：

```jsonc
// 1. 発走前オッズのパターン判定
{
  "tool": "classify_odds_pattern",
  "input": {
    "entrants": [
      {"popularity": 1, "odds": 2.5, "horse_number": 1, "horse_name": "クロワデュノール"},
      {"popularity": 2, "odds": 2.9, "horse_number": 7, "horse_name": "マスカレードボール"},
      {"popularity": 3, "odds": 8.4, "horse_number": 3, "horse_name": "レガレイラ"}
    ]
  }
}
// → {"pattern":"C:2強", "bet_type":"複勝", "target":1, ...}

// 2. そのまま買い目生成
{
  "tool": "build_buy_order",
  "input": {
    "race": {"race_name":"天皇賞（秋）", "entrants":[...], "condition":"稍重"},
    "base_amount": 1000
  }
}
// → メイン1000円 + サブ各100円 の買い目リスト

// 3. 過去データで裏取り
{
  "tool": "get_race_specific_roi",
  "input": {"race_name": "天皇賞（秋）", "bet_type": "単勝"}
}
// → 人気別の歴代 ROI
```

## V3 戦略の判定ルール

| 条件 | パターン | 買い方 |
|---|---|---|
| `pop1_odds ≤ 2.0` | **A:断然** | 単勝3番人気 |
| `pop1_odds ≤ 3.5 かつ ratio ≥ 1.5` | **B:やや断然** | 見送り |
| `pop1_odds ≤ 3.5 かつ ratio < 1.5` | **C:2強** | 複勝1番人気 |
| `3.5 < pop1_odds ≤ 6.0` | **D:混戦** | 単勝4番人気 |
| `pop1_odds > 6.0` | **E:大混戦** | 見送り |
| `condition = "重"` | — | 全見送り |

- `ratio = pop2_odds / pop1_odds`
- 累計 ROI 121.9%（G1 367レース 2010–2026、`simulation_log.md` 仮説#011b V3）
- サブ戦略: 全G1で単勝 7番人気 + 8番人気 各100円（長期 ROI 113.7%）

## セキュリティ

- 既定で **read-only**。書き込みツール (`add_bet_record` / `update_bet_result`) は `HORSE_RACE_MCP_ALLOW_WRITE=1` を明示的に設定したときだけ有効
- 認証情報 (`TURSO_TOKEN`) はクライアント設定ファイルに平文で入るため、ファイル権限 (`chmod 600`) で保護推奨
- Turso の read-only トークンを使えばさらに安全

## 開発

```bash
# テスト
pytest

# フォーマット/lint
ruff check src tests
ruff format src tests

# PyPI 公開（メンテナ向け）
python -m build
twine upload dist/*
```

## ライセンス

MIT
