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

   • 访问公共数据门户
   • 搜索并申请“韩国马事会赛马记录信息”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。