gfi-scout

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

---

为什么开发这个项目

大多数“适合初学者的问题”查找工具，不过是给 GitHub 搜索套了层包装。它们会把问题从已弃用的仓库、已被其他三位贡献者认领的问题，以及维护者永远不会审核的问题中找出来，毫不在意。

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 req/h；使用具有 public_repo 权限范围的 PAT（只读）后，限额提高至 5,000 req/h

---

快速开始

# 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 和终端界面的用法
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

如果长期运行的 MCP 服务进程在 Windows 上占用了安装目录（重新安装时出现 Access is denied），请先停止宿主应用（Claude Desktop / Claude Code / Cursor），或结束 gfi-scout Python 进程，然后重新运行命令。

结果速度较慢，或很快遇到 rate limit exceeded

你可能没有使用令牌（每小时 60 个请求）。设置 GITHUB_TOKEN——可以通过环境变量或工作目录中的 .env 文件设置——即可获得每小时 5,000 个请求。对于 uv tool 安装，可在 shell 配置文件中导出该变量，或在 MCP 客户端的 env 区块中设置（请参阅上文 连接到 MCP 客户端）。

---

贡献

欢迎提交问题和 PR——我们言行一致。从 CONTRIBUTING.md 开始。适合新手的问题已在问题跟踪器中标记。

参与即表示你同意行为准则。

---

安全

发现安全问题？请不要公开提交问题——信息披露流程请参阅 SECURITY.md。

GFI Scout 仅需要你的 GitHub 令牌具有 public_repo（只读）权限范围。

---

许可证

MIT — 因为帮助人们为开源项目做贡献才是重点。

---