KinielaGPT

KinielaGPT - キニエラの試合予測ツール

KinielaGPT は、データの高度な分析によってキニエラの予測を支援する MCP（Model Context Protocol）サーバーです。LAE の公式確率と、対戦履歴、直近の連勝・連敗、順位、ホームまたはアウェイでの成績に関する詳細な状況分析を組み合わせています。3 つの予測戦略、番狂わせの検出、試合ごとの詳細な分析を提供します。

🎯 特徴

🎲 試合結果の予測

保守的（最も確率が高い結果）、リスク重視（確率と状況をバランスよく考慮）、またはカスタム（「1」「X」「2」の数を指定）の 3 つの戦略で予測を生成します。

📊 試合の総合分析

LAE の確率、対戦履歴（過去 10 年間）、連勝・連敗、順位、試合状況を統合し、根拠のある予測を提供します。

🔍 番狂わせの検出

公式確率と実際の成績（連勝・連敗、対戦履歴、調子）の食い違いを検出し、番狂わせの可能性を予測します。

👥 チームの調子

直近のスコア、継続中の連勝・連敗、ホーム／アウェイでの成績、順位の傾向など、詳細なパフォーマンスを評価します。

📈 柔軟なデータ参照

解釈付きの分析だけでなく、生データにもアクセスできるため、独自の結論を導き出せます。

🔌 ネイティブ MCP サーバー

Claude Desktop、VS Code、その他の MCP クライアントと完全に互換性のある、7 つの専用ツールが含まれています。

🏁 KinielaGPT を使い始める手順

以下の手順に従って、KinielaGPT をお使いのコンピューターで利用できるようにします。

1. PC に UV または Python 3.10+ をインストールします。
2. KinielaGPT をインストールします。
3. MCP サーバーを設定し、クライアントとして Claude または VS Code を選択します。

これらの手順が完了したら、KinielaGPT で予測と分析を始められます！

✅ UV または Python 3.10+ のインストール

KinielaGPT を使用する前に、UV（推奨）または Python 3.10+ をインストールする必要があります。

以下に 2 つの方法を示しますが、どちらか一方を選んでください。

オプション 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 の設定

お使いの OS に応じて、次の場所にある設定ファイル 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を設定したら、自然言語でLLM（Claude、GPT、Geminiなど）とやり取りできます。次のような質問をするだけです。

利用可能なツール

合計：利用可能なMCPツールは7個です

パラメーターや使用例の詳細については、完全なドキュメントを参照してください。

📚 ドキュメント

完全なドキュメントは、https://ricardomoya.github.io/KinielaGPT/ でご覧いただけます。

内容：

• クイックスタートガイド： 環境でKinielaGPTを使用するためのインストール、設定、初期手順。
• インストールマニュアル： UVまたはpipを使ったインストール手順と前提条件の詳細。
• 高度な設定： KinielaGPTをClaude Desktop、VS CodeなどのMCPクライアントに接続する方法。
• 使い方と例： よくある質問、コマンド例、推奨ワークフロー。
• APIリファレンス： 利用可能なすべてのMCPツール、パラメーター、使用例の説明。
• 貢献： プロジェクトへの貢献、issueの作成、プルリクエストの送信方法。
• ライセンスとクレジット： 法的情報と著者および協力者への謝辞。

🧪 テスト

このプロジェクトには、主要な機能をすべて網羅する自動テストスイートが含まれています。テストはモジュールごとに整理されており、実行には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. リポジトリをフォークします
2. 機能追加用のブランチを作成します（git checkout -b feature/AmazingFeature）
3. 変更をコミットします（git commit -m 'Add some AmazingFeature'）
4. ブランチにプッシュします（git push origin feature/AmazingFeature）
5. プルリクエストを作成します

📝 ライセンス

このプロジェクトは、GNU Affero General Public License v3.0 (AGPL-3.0) の下でライセンスされています。

以下のことができます。

• ✅ コードを自由に使用する（商用利用も含む）
• ✅ プロジェクトを変更、改変する
• ✅ コピーや改変版を配布する

ただし、次の条件に従う必要があります。

• 📝 コピーレフト：変更を加えた場合も AGPL-3.0 にする必要があります
• 🌐 ネットワークでの使用：このコードをサーバー／サービスで使用する場合、ソースコードを共有する必要があります
• 📦 オープンソース：改変版はすべて、ソースコードとともに配布する必要があります
• ©️ 帰属表示：著作権表示を維持する必要があります

特別な保護：AGPL-3.0 は「サーバーの抜け穴」を塞ぎます。バイナリを配布せずにこのコードをウェブサービスとして実行する場合でも、ユーザーにソースコードを提供する必要があります。

法的文書の全文については、LICENSE ファイルをご覧ください。

重要

このプロジェクトは、娯楽のみを目的としています。予測は結果を保証するものではなく、賭けに関する判断の唯一の根拠として使用しないでください。責任を持ってプレイしてください。

👨‍💻 作者 - Ricardo Moya

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

📧 お問い合わせ

ご質問、ご提案、問題の報告はこちらからどうぞ。

• 📝 GitHub の問題
• 💬 GitHub のディスカッション

⚽ Ricardo Moya が、すべての quiniela を知恵と戦略、データを活用して楽しめるように作成したプロジェクトです。