gfi-scout

mcp-name: io.github.Rajveerx11/gfi-scout

---

開発の背景

多くの「初心者向け課題」検索ツールは、GitHub 検索をそのまま包んだだけのものです。放置されたリポジトリの課題や、すでにほかの3人の貢献者が取り組んでいる課題、メンテナーが決してレビューしない課題まで、平気で提示します。

GFI Scout は、成功の可能性に基づいて結果をランク付けします。リポジトリの健全性、マージ率、メンテナーの応答性、課題の新しさ、セットアップの複雑さを組み合わせて、総合的な beginner_score（0～100）を算出します。放置されたリポジトリは下位に表示されます。

Model Context Protocol サーバーとして提供されるほか、ターミナル中心のワークフロー向けにスタンドアロン CLI/TUI も用意されています。

---

機能

• 🔎 find_issues — 言語、トピック、スター数の範囲でリポジトリを優先して検索し、スコア付きの課題を表示
• 🩺 check_repo_health — マージ率、最終コミット、CONTRIBUTING/CoC/CI の有無を確認し、A～F で評価
• ⏱️ check_issue_status — 担当状況、関連 PR、最終更新からの経過、メンテナーの確認を調べ、AVAILABLE / LIKELY_TAKEN / STALE の判定を表示
• 📘 get_contribution_guide — CONTRIBUTING.md を取得して要約し、ツールチェーンを検出してセットアップの複雑さを推定
• gfi-scout-cli によるターミナルコマンドと、対話型の gfi-scout-tui
• ⚡ GitHub API を並列に呼び出し（asyncio.gather）、名前空間ごとの TTL キャッシュを使用。オプションでセッションをまたいだ SQLite への永続化にも対応
• 🎛️ すべてのスコアリングの重みとしきい値は src/gfi_scout/data/scoring_weights.json に記載されており、コード内にマジックナンバーはありません
• 🧪 100 件以上のテスト（ユニット＋統合）、mypy --strict と ruff のチェックに合格

---

要件

Python	3.12+
パッケージマネージャー	uv（すべてのコマンドは uv 経由で実行します）
認証	任意 — トークンなしでも毎時60リクエストまで利用できます。public_repo スコープ（読み取り専用）の PAT を使うと、毎時5,000リクエストまで利用できます

---

クイックスタート

# Clone
git clone https://github.com/Rajveerx11/gfi-scout.git
cd gfi-scout

# Install uv (skip if you have it)
# macOS / Linux:        curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows (PowerShell): irm https://astral.sh/uv/install.ps1 | iex

# Install dependencies (creates .venv automatically)
uv sync

# Optional: add a GitHub token (60 req/h without one, 5,000 req/h with)
cp .env.example .env
# edit .env and paste your GitHub token

# Run the MCP server (stdio transport)
uv run gfi-scout

# Or expose a local Streamable HTTP MCP endpoint
uv run gfi-scout --transport streamable-http --host 127.0.0.1 --port 8000

# Or use the standalone CLI/TUI
uv run gfi-scout-cli find python --min-stars 500
uv run gfi-scout-tui

グローバル uv ツールとしてインストール

MCP サーバーまたは CLI の実行だけが目的で、コードを変更する予定がない場合は、グローバルツールとして一度インストールしてください。リポジトリのチェックアウトも、維持する仮想環境も不要です。

# Install (or update) directly from GitHub
uv tool install --force --from git+https://github.com/Rajveerx11/gfi-scout gfi-scout

# Then the binaries are on $PATH:
gfi-scout                # MCP server (stdio)
gfi-scout-cli find python --min-stars 500
gfi-scout-tui

# Upgrade later:
uv tool install --force --from git+https://github.com/Rajveerx11/gfi-scout gfi-scout

環境変数に GITHUB_TOKEN を設定するか、実行するディレクトリに .env を用意できます（いずれも任意）。どちらも設定しない場合は、GitHub の未認証時の上限である毎時60リクエストで利用します。

---

MCP クライアントへの接続

Claude Desktop

claude_desktop_config.json に以下を追加してください。

{
  "mcpServers": {
    "gfi-scout": {
      "command": "uv",
      "args": ["run", "--directory", "/absolute/path/to/gfi-scout", "gfi-scout"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

Claude Desktop を再起動してから、次のように試してください。

「スター数が500以上の、Python の初心者向け課題を探してください。」

「この課題は本当に着手可能ですか？ https://github.com/fastapi/fastapi/issues/12345」

「pallets/flask のセットアップはどのくらい複雑ですか？」

その他のクライアント

Cursor、Windsurf、VS Code Copilot はいずれも MCP サーバーに対応しています。同じ uv run コマンドを指定してください。詳しい手順は docs/SETUP.md をご覧ください。

---

MCP ツール

ツール	機能
find_issues	リポジトリを優先し、初心者向けの課題をスコア付きで検索します
check_repo_health	リポジトリの貢献しやすさをA〜Fで評価します
check_issue_status	この特定の課題に実際に取り組めるかを確認します
get_contribution_guide	CONTRIBUTING.md／README のセットアップ手順を取得して要約します

パラメーターと戻り値の形式の仕様については、docs/TOOLS_REFERENCE.md を参照してください。

---

CLI と TUI

uv run gfi-scout-cli find python --min-stars 500 --max-results 10
uv run gfi-scout-cli health fastapi/fastapi
uv run gfi-scout-cli status https://github.com/fastapi/fastapi/issues/12345
uv run gfi-scout-cli guide pallets/flask
uv run gfi-scout-tui

すべてのコマンドで、スクリプト用の --output json を指定できます。詳細は docs/CLI.md を参照してください。

---

スコアリングの仕組み

beginner_score = repo_health        × 0.30
               + issue_freshness    × 0.20
               + issue_clarity      × 0.15
               + merge_friendliness × 0.25
               + setup_complexity_inv × 0.10

すべての重みとしきい値は src/gfi_scout/data/scoring_weights.json から読み込まれます。ランキングの調整には、JSON を編集して再実行するだけで済み、コードの変更は不要です。

詳しい内訳は docs/SCORING_ALGORITHM.md を参照してください。

---

ドキュメント

ドキュメント	内容
docs/SETUP.md	インストール、環境変数、クライアントの接続設定を順を追って説明します
docs/AGENT_CONNECTIONS.md	Codex、Claude Code、Cursor、Antigravity、Pi Agent、Hermes Agent の最新の MCP 接続例
docs/ARCHITECTURE.md	レイヤーのルール、リクエストの流れ、キャッシュ、障害モデル
docs/CLI.md	スタンドアロン CLI とターミナル UI の使い方
docs/TOOLS_REFERENCE.md	すべての MCP ツールのパラメーターと戻り値のスキーマ
docs/SCORING_ALGORITHM.md	beginner_score の計算方法と評価基準
CONTRIBUTING.md	課題の報告と PR の提出方法
SECURITY.md	責任ある脆弱性開示に関するポリシー
docs/CHANGELOG.md	リリースノート
docs/Plan.md	オリジナルの仕様とフェーズ計画

---

開発

uv sync                              # install everything
uv run pytest                        # 106 tests in ~2 s
uv run ruff check src/ tests/        # lint
uv run ruff format src/ tests/       # format
uv run mypy src/                     # strict type-check
uv run mcp dev src/gfi_scout/server.py  # MCP Inspector

uv.lock はコミットされているため、すべてのコントリビューターが同じ依存関係のバージョンを使用できます。

プロジェクトの構成

src/gfi_scout/
├── server.py          # FastMCP entry, tool registration
├── cli.py             # Standalone CLI + terminal UI
├── config.py          # Env loading
├── runtime.py         # Shared cache/client wiring
├── tools/             # One file per MCP tool
│   ├── find_issues.py
│   ├── check_repo_health.py
│   ├── check_issue_status.py
│   └── get_contribution_guide.py
├── services/          # GitHub client, scoring, cache
├── models/            # Pydantic models
└── utils/             # Pure helpers (validators, rate limiter, logger)

tests/                 # mirrors src/ layout
docs/                  # markdown docs
scripts/               # dev automation (setup.sh, seed_cache.py)

スコアリング設定はパッケージ内の src/gfi_scout/data/scoring_weights.json に置かれています。インストール済みの wheel に含まれるため、トップレベルに別途 config/ ディレクトリを用意する必要はありません。（実行時設定モジュールの gfi_scout/config.py とは無関係です。data/ には JSON が格納され、config.py は環境変数を読み込みます。）

レイヤーのルールとフォルダーの規約については、docs/ARCHITECTURE.md を参照してください。

---

トラブルシューティング

scoring config not found: .../Lib/config/scoring_weights.json

古いインストール（≤ v0.1.0）を使用しています。このバージョンでは、スコアリング設定が wheel に含まれていませんでした。次の手順で修正してください。

uv tool install --force --from git+https://github.com/Rajveerx11/gfi-scout gfi-scout

Windows で長時間実行中の MCP サーバープロセスがインストールディレクトリを開いたままにしている場合（再インストール時に Access is denied が発生する場合）は、ホスト（Claude Desktop／Claude Code／Cursor）を停止するか、先に gfi-scout の Python プロセスを終了してから、コマンドを再実行してください。

結果の表示が遅い、またはすぐに rate limit exceeded が発生する

トークンなしで実行している可能性があります（1時間あたり60リクエスト）。環境変数または作業ディレクトリ内の .env ファイルで GITHUB_TOKEN を設定すると、1時間あたり5,000リクエストを利用できます。uv tool でインストールした場合は、シェルのプロファイルでエクスポートするか、MCP クライアントの env ブロックで設定してください（上記の MCP クライアントへの接続 を参照）。

---

コントリビュート

課題の報告や PR を歓迎します。自ら掲げる方針を実践しています。CONTRIBUTING.md から始めてください。初心者向けの課題には、トラッカーでラベルが付いています。

参加することで、行動規範に同意したものとみなされます。

---

セキュリティ

セキュリティ上の問題を見つけた場合は、公開の課題として報告しないでください。開示手順については SECURITY.md を参照してください。

GFI Scout が GitHub トークンに必要とするスコープは、public_repo（読み取り専用）のみです。

---

ライセンス

MIT — オープンソースへの貢献を支援することが、何よりの目的だからです。

---