Metadata-Version: 2.5
Name: horse-race-mcp
Version: 0.1.0
Summary: MCP server exposing the horse-race Turso DB and the V3 odds-pattern recommender to any MCP client (Claude Desktop, ChatGPT Desktop, Cursor, etc.)
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
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)** 経由で公開するサーバーです。

[Claude Desktop](https://claude.ai/download)、[ChatGPT Desktop](https://openai.com/chatgpt/desktop/)（2025年末〜MCP対応）、[Cursor](https://www.cursor.com/)、[Cline](https://cline.bot/) など MCP 対応のクライアントで横断利用できます。

## 提供ツール

### 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` を設定で有効 |

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

設定 → コネクタ → カスタム MCP サーバー:

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

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

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

ツール名と 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
