KRA Racing Data Analysis MCP Server

KRA Racing Data Analysis MCP Server

韓国馬事会（Korea Racing Authority）の公共 API を活用した競馬データ分析 MCP サーバー

このプロジェクトは、Model Context Protocol（MCP）を使用して韓国馬事会の競馬データを分析し、インサイトを提供するサーバーです。

🏇 主な機能

🔧 分析ツール（Tools）

• analyze-race：競走分析（日付、競走番号、競馬場別）
• analyze-horse-performance：馬の成績分析と調子の評価
• get-jockey-stats：騎手の統計と成績分析
• get-jockey-info：騎手情報の取得
• analyze-odds：オッズ分析とパターン認識

📁 データリソース（Resources）

• schedule://{date}：競走スケジュール情報（今日／明日）
• horses://{horseName}：馬の詳細情報と記録
• tracks://{trackCode}：競馬場情報（ソウル／釜山／済州）
• config://kra-api：KRA API の設定と構成

💬 分析プロンプト（Prompts）

• predict-race：競走予測分析（基本／詳細／統計）
• horse-performance-report：馬の成績詳細レポート
• market-analysis：馬券市場分析（オッズ／取引量／トレンド）

🎯 活用分野

• 競走予測：データに基づく競走結果の予測
• 投資分析：馬券投資戦略の策定
• 成績評価：馬、騎手、調教師の成績分析
• 市場分析：オッズと取引量のパターン分析
• リスク管理：投資リスクの評価と管理

📦 インストールと設定

必要条件

• Node.js 18.0.0 以上
• npm または yarn
• 韓国馬事会の公共 API へのアクセス権 ✅ 実際の連携が完了しています

KRA API キーの設定（必須）

1. 公共データポータルに申請

   • 公共データポータルにアクセス
   • 「韓国馬事会競走記録情報」API を検索して申請
   • 承認後、サービスキーを取得

2. 環境変数の設定

   # Windows (PowerShell)
   $env:KRA_SERVICE_KEY="YOUR_SERVICE_KEY_HERE"
   
   # macOS/Linux
   export KRA_SERVICE_KEY="YOUR_SERVICE_KEY_HERE"
   
   # 또는 .env 파일 생성
   echo "KRA_SERVICE_KEY=YOUR_SERVICE_KEY_HERE" > .env
   

3. サービスキーの確認

   • URL エンコードされたキーを使用する必要があります
   • 特殊文字が含まれている場合はエンコードが必要です

プロジェクトのインストール

# 저장소 클론
git clone <repository-url>
cd kra-mcp

# 의존성 설치
npm install

# KRA API 키 설정 (위 참조)
export KRA_SERVICE_KEY="your_service_key"

🏃‍♂️ 実行方法

開発モード

npm run dev

監視モード（ファイル変更時に自動で再起動）

npm run watch

プロダクションビルドと実行

npm run build
npm start

🔧 MCP クライアントの登録

Cursor IDE での使用

~/.cursor/mcp.json ファイルに追加：

{
  "mcpServers": {
    "kra-racing-analysis": {
      "command": "npx",
      "args": ["tsx", "src/index.ts"],
      "cwd": "/path/to/kra-mcp"
    }
  }
}

プロダクション版を使用する場合：

{
  "mcpServers": {
    "kra-racing-analysis": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/path/to/kra-mcp"
    }
  }
}

Cursor を再起動すると使用できます。

🧪 テストと検証

MCP Inspector の使用

npx @modelcontextprotocol/inspector npx tsx src/index.ts

ツールのテスト例

# 경주 분석 테스트
analyze-race --raceDate="2024-01-15" --raceNumber="3" --trackCode="seoul"

# 말 성적 분석 테스트
analyze-horse-performance --horseName="우승마" --period="1year"

📂 プロジェクト構成

kra-mcp/
├── src/
│   └── index.ts              # 메인 서버 파일
├── dist/                     # 빌드된 JavaScript 파일
├── package.json              # 프로젝트 설정
├── tsconfig.json             # TypeScript 설정
├── .gitignore               # Git 제외 파일
└── README.md                # 프로젝트 문서

🔍 使用例

1. 競走分析のリクエスト

{
  "method": "tools/call",
  "params": {
    "name": "analyze-race",
    "arguments": {
      "raceDate": "2024-01-15",
      "raceNumber": 5,
      "trackCode": "seoul"
    }
  }
}

2. 馬の情報の取得

{
  "method": "resources/read",
  "params": {
    "uri": "horses://우승마"
  }
}

3. 競走予測プロンプト

{
  "method": "prompts/get",
  "params": {
    "name": "predict-race",
    "arguments": {
      "raceDate": "2024-01-15",
      "raceNumber": "5",
      "analysisType": "detailed"
    }
  }
}

🛠️ 開発ガイド

新しい分析ツールの追加

server.tool("new-analysis-tool",
  { 
    param1: z.string(),
    param2: z.number().optional()
  },
  async ({ param1, param2 }) => ({
    content: [{ 
      type: "text", 
      text: `분석 결과: ${param1} ${param2 || ''}` 
    }]
  })
);

新しいデータリソースの追加

server.resource(
  "new-resource",
  new ResourceTemplate("resource://{id}", { list: undefined }),
  async (uri, { id }) => ({
    contents: [{
      uri: uri.href,
      text: JSON.stringify({ id, data: "..." }, null, 2)
    }]
  })
);

🌐 API 連携状況

✅ 現在連携済みの API：

• 韓国馬事会の公共 API：競走情報、出走馬データ、騎手情報
• API214_1：競走の詳細結果と分析データ
• API12_1：騎手情報の取得
• API299：競走統計と予測情報

⏳ 今後連携予定：

• リアルタイムオッズ API：オッズの変化を追跡
• 気象情報 API：馬場状態の影響を分析

📊 データ分析機能

対応する分析タイプ

• テクニカル分析：過去の成績に基づくパターン分析
• 統計分析：確率モデルと回帰分析
• 市場分析：オッズと取引量の分析
• 比較分析：馬、騎手、調教師の比較

予測モデル（計画中）

• 機械学習モデル：過去のデータに基づく予測
• アンサンブルモデル：複数のモデルを組み合わせた予測
• リアルタイム分析：競走当日のリアルタイムデータ分析

🔒 セキュリティと遵守事項

• 韓国馬事会 API の利用規約を遵守
• 個人情報保護法を遵守
• API キーを安全に管理
• データ使用量の制限を遵守

📚 参考資料

• 韓国馬事会公式サイト
• Model Context Protocol ドキュメント
• MCP TypeScript SDK
• Zod スキーマ検証

📄 ライセンス

MIT License

---

⚠️ 重要：実際の KRA 公共 API と連携して動作します。API キーの設定が必要です。

💡 ヒント：Context7 と併用すると、より正確な競馬データ分析を得られます！プロンプトに use context7 を追加してみてください。