KinielaGPT

KinielaGPT - Kiniela 比赛预测工具

KinielaGPT 是一款 MCP（Model Context Protocol）服务，旨在通过高级数据分析提升你的 Quiniela 预测能力。它将 LAE 的官方概率与深入的背景分析相结合，涵盖交锋历史、近期连胜连败、排名以及主客场表现。它提供三种预测策略、冷门检测功能，以及对每场比赛的详细分析。

🎯 特性

🎲 比赛结果预测

通过三种策略生成预测：保守型（选择概率最高的结果）、冒险型（平衡概率与背景信息）或自定义型（指定“1”“X”“2”的数量）。

📊 全面比赛分析

综合 LAE 概率、交锋历史（近 10 年）、连胜连败、排名及背景信息，提供有理有据的预测。

🔍 冷门检测

检测官方概率与实际表现（连胜连败、历史交锋、状态）之间的差异，以预测可能出现的冷门。

👥 球队状态

详细评估球队表现：近期比分、当前连胜连败、主客场表现及排名趋势。

📈 灵活的数据查询

既可获取解读后的分析，也可访问原始数据，以便自行得出结论。

🔌 原生 MCP 服务

包含 7 个专用工具，完全兼容 Claude Desktop、VS Code 及其他 MCP 客户端。

🏁 KinielaGPT 入门步骤

按照以下步骤，在你的设备上安装并运行 KinielaGPT：

1. 在你的电脑上安装 UV 或 Python 3.10+。
2. 安装 KinielaGPT。
3. 配置 MCP 服务，并选择 Claude 或 VS Code 作为客户端。

完成这些步骤后，就可以开始使用 KinielaGPT 进行预测和分析了！

✅ 安装 UV 或 Python 3.10+

使用 KinielaGPT 前，你需要安装 UV（推荐）或 Python 3.10+。

下面介绍两种方式的安装方法，不过你必须二选一：

选项 1：UV（推荐）⚡

UV 是一款超快速的 Python 包和项目管理器，可简化 Python 工具的安装与运行。无需预先安装 Python。

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

uv --version

curl -LsSf https://astral.sh/uv/install.sh | sh

uv --version

如果你已安装 Python，并且更喜欢传统方式，可以使用 pip（Python 包管理器）。要求系统已安装 Python 3.10 或更高版本。

python --version
pip --version

python3 --version
pip3 --version

sudo apt update
sudo apt install python3.10 python3-pip python3.10-venv

python3 --version
pip3 --version

🚀 安装

选项 1：使用 UV（推荐）

安装 UV 后，无需安装 KinielaGPT。你将使用 uvx 直接运行它——请参阅配置。

选项 2：使用 pip

从 PyPI 安装 KinielaGPT：

pip install kinielagpt

🔧 配置

🤖 为 Claude.app 配置

编辑配置文件 claude_desktop_config.json。该文件因操作系统而异，位于以下位置：

• Windows： %APPDATA%\Roaming\Claude\claude_desktop_config.json
• macOS/Linux： ~/Library/Application Support/Claude/claude_desktop_config.json

根据安装方式，添加以下其中一种配置：

{
  "mcpServers": {
    "kinielagpt": {
      "command": "uvx",
      "args": ["kinielagpt"]
    }
  }
}

{
  "mcpServers": {
    "kinielagpt": {
      "command": "python",
      "args": ["-m", "kinielagpt"]
    }
  }
}

💻 为 VS Code 配置

快速安装（一键）：

点击下方按钮，在 VS Code 中自动安装 MCP 服务：

手动安装：

打开命令面板（Ctrl + Shift + P），运行 MCP: Open User Configuration，然后添加以下其中一种配置：

{
  "mcpServers": {
    "kinielagpt": {
      "command": "uvx",
      "args": ["kinielagpt"]
    }
  }
}

{
  "mcpServers": {
    "kinielagpt": {
      "command": "python",
      "args": ["-m", "kinielagpt"]
    }
  }
}

提示

你也可以在工作区中创建 .vscode/mcp.json 文件，以便与他人共享配置。更多详情请参阅 VS Code MCP 官方文档。

📖 如何使用 KinielaGPT？

配置好 MCP 后，你可以用自然语言与大模型（Claude、GPT、Gemini 等）交互。只需提出以下问题即可：

可用工具

共提供 7 个 MCP 工具

如需了解参数和示例的完整详情，请参阅完整文档。

📚 文档

完整文档请访问：https://ricardomoya.github.io/KinielaGPT/

内容包括：

• 快速入门指南： 在你的环境中安装和配置 KinielaGPT，并了解如何开始使用。
• 安装手册： 使用 UV 或 pip 安装的详细说明及前置要求。
• 高级配置： 如何将 KinielaGPT 连接到 Claude Desktop、VS Code 和其他 MCP 客户端。
• 使用方法和示例： 常见问题、命令示例和推荐工作流。
• API 参考： 介绍所有可用的 MCP 工具、参数和使用示例。
• 参与贡献： 为项目做贡献、提交 issue 和发送 pull request 的指南。
• 许可证和致谢： 法律信息，以及对作者和贡献者的致谢。

🧪 测试

项目包含一套完整的自动化测试，覆盖所有主要功能。测试按模块组织，并使用 pytest 运行。

可用测试

在本地运行测试

# Ejecutar todos los tests
pytest tests/ -v

# Ejecutar con cobertura
pytest tests/ -v --cov=kinielagpt --cov-report=term-missing

# Ejecutar un módulo específico
pytest tests/test_predictor.py -v

# Ejecutar tests en paralelo (si tienes pytest-xdist)
pytest tests/ -v -n auto

代码覆盖率

测试覆盖了主要代码。当前各模块的覆盖率如下：

CI/CD

测试会通过 GitHub Actions 自动运行：

• 每次向 main 和 develop 分支推送或提交 PR 时
• 定时运行：每周四上午 9:00（UTC 时间）
• 测试矩阵：Ubuntu 上的 Python 3.10、3.11、3.12、3.13
• 通知：定时运行时自动发送包含结果的邮件

如需查看 CI 结果，请访问仓库的 Actions 选项卡。

🤝 贡献

欢迎贡献！请按以下步骤操作：

1. Fork 仓库
2. 为你的功能创建分支（git checkout -b feature/AmazingFeature）
3. Commit 你的更改（git commit -m 'Add some AmazingFeature'）
4. Push 到该分支（git push origin feature/AmazingFeature）
5. 创建 Pull Request

📝 许可证

本项目采用 GNU Affero General Public License v3.0 (AGPL-3.0) 许可。

这意味着你可以：

• ✅ 自由使用代码（包括商业用途）
• ✅ 修改和改编项目
• ✅ 分发副本和修改后的版本

但须遵守以下条件：

• 📝 Copyleft：任何修改也必须采用 AGPL-3.0
• 🌐 网络使用：如果你在服务器/服务中使用此代码，必须共享源代码
• 📦 开源：所有修改后的版本都必须随源代码一同分发
• ©️ 署名：必须保留版权声明

特别保护：AGPL-3.0 弥补了“服务器漏洞”——即使你将此代码作为 Web 服务运行而不分发二进制文件，也必须向用户提供源代码。

完整法律文本请参阅 LICENSE 文件。

重要

本项目仅供娱乐。预测结果不作保证，不应作为投注决策的唯一依据。请理性投注。

👨‍💻 作者 - Ricardo Moya

🐙 GitHub：@RicardoMoya
💼 LinkedIn：Ricardo Moya, PhD

📧 联系方式

如有问题、建议或需要报告 issue：

• 📝 GitHub Issues
• 💬 GitHub Discussions

⚽ Ricardo Moya 创建本项目，希望每场 quiniela 都能凭理性、策略和数据来玩。