{
  "markdown": "<div align=\"center\">\n\n# GFI Scout\n\n![gfi-scout Demo](docs/assets/demo.gif)\n\n**An MCP server and standalone CLI that finds open source issues where beginners actually succeed — not just any issue tagged `good first issue`.**\n\n[![CI](https://github.com/Rajveerx11/gfi-scout/actions/workflows/ci.yml/badge.svg)](https://github.com/Rajveerx11/gfi-scout/actions/workflows/ci.yml)\n[![Python 3.12+](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/downloads/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Built with uv](https://img.shields.io/badge/built%20with-uv-261230.svg)](https://docs.astral.sh/uv/)\n[![MCP](https://img.shields.io/badge/protocol-MCP-7c3aed.svg)](https://modelcontextprotocol.io/)\n[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)\n\n</div>\n\n<!-- Official MCP Registry identifier — verifies PyPI package ownership. -->\nmcp-name: io.github.Rajveerx11/gfi-scout\n\n---\n\n## Why this exists\n\nMost \"good first issue\" finders are glorified GitHub search wrappers. They happily hand you issues from abandoned repos, issues already claimed by three other contributors, and issues maintainers will never review.\n\n**GFI Scout ranks results by *likelihood of success*** — repo health, merge rate, maintainer responsiveness, issue freshness, and setup complexity all feed a composite `beginner_score` (0-100). The dead repos sink to the bottom.\n\nIt ships as a [Model Context Protocol](https://modelcontextprotocol.io/) server, plus a standalone CLI/TUI for terminal-first workflows.\n\n---\n\n## Features\n\n- 🔎 **`find_issues`** — repo-first language + topic + star-range discovery with scored issue results\n- 🩺 **`check_repo_health`** — merge rate, last commit, CONTRIBUTING/CoC/CI probes → A-F grade\n- ⏱️ **`check_issue_status`** — assignment, linked PRs, staleness, maintainer confirmation → `AVAILABLE` / `LIKELY_TAKEN` / `STALE` verdict\n- 📘 **`get_contribution_guide`** — pulls and summarises `CONTRIBUTING.md`, detects toolchain, estimates setup complexity\n- Terminal commands via **`gfi-scout-cli`** and an interactive **`gfi-scout-tui`**\n- ⚡ Parallel GitHub API fan-out (`asyncio.gather`) + per-namespace TTL cache, with opt-in SQLite persistence across sessions\n- 🎛️ All scoring weights and thresholds live in [`src/gfi_scout/data/scoring_weights.json`](src/gfi_scout/data/scoring_weights.json) — no magic numbers in code\n- 🧪 100+ tests (unit + integration), `mypy --strict` clean, `ruff` clean\n\n---\n\n## Requirements\n\n| | |\n|---|---|\n| Python | **3.12+** |\n| Package manager | [`uv`](https://docs.astral.sh/uv/) (all commands go through `uv`) |\n| Auth | Optional — works without a token at 60 req/h; a PAT with **`public_repo`** scope (read-only) raises it to 5,000 req/h |\n\n---\n\n## Quick start\n\n```bash\n# Clone\ngit clone https://github.com/Rajveerx11/gfi-scout.git\ncd gfi-scout\n\n# Install uv (skip if you have it)\n# macOS / Linux:        curl -LsSf https://astral.sh/uv/install.sh | sh\n# Windows (PowerShell): irm https://astral.sh/uv/install.ps1 | iex\n\n# Install dependencies (creates .venv automatically)\nuv sync\n\n# Optional: add a GitHub token (60 req/h without one, 5,000 req/h with)\ncp .env.example .env\n# edit .env and paste your GitHub token\n\n# Run the MCP server (stdio transport)\nuv run gfi-scout\n\n# Or expose a local Streamable HTTP MCP endpoint\nuv run gfi-scout --transport streamable-http --host 127.0.0.1 --port 8000\n\n# Or use the standalone CLI/TUI\nuv run gfi-scout-cli find python --min-stars 500\nuv run gfi-scout-tui\n```\n\n### Install as a global `uv` tool\n\nIf you only want to run the MCP server / CLI and don't plan to hack on the code, install it once as a global tool. No checkout, no venv to keep around:\n\n```bash\n# Install (or update) directly from GitHub\nuv tool install --force --from git+https://github.com/Rajveerx11/gfi-scout gfi-scout\n\n# Then the binaries are on $PATH:\ngfi-scout                # MCP server (stdio)\ngfi-scout-cli find python --min-stars 500\ngfi-scout-tui\n\n# Upgrade later:\nuv tool install --force --from git+https://github.com/Rajveerx11/gfi-scout gfi-scout\n```\n\nA `GITHUB_TOKEN` in the environment (or a `.env` in the directory you run from) is optional — without one you run at GitHub's unauthenticated 60 requests/hour limit.\n\n---\n\n## Connecting to an MCP client\n\n### Claude Desktop\n\nAdd this to `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"gfi-scout\": {\n      \"command\": \"uv\",\n      \"args\": [\"run\", \"--directory\", \"/absolute/path/to/gfi-scout\", \"gfi-scout\"],\n      \"env\": {\n        \"GITHUB_TOKEN\": \"ghp_your_token_here\"\n      }\n    }\n  }\n}\n```\n\nRestart Claude Desktop, then try:\n\n> *\"Find me Python good first issues with at least 500 stars.\"*\n>\n> *\"Is this issue actually available? https://github.com/fastapi/fastapi/issues/12345\"*\n>\n> *\"What's the setup complexity for `pallets/flask`?\"*\n\n### Other clients\n\nCursor, Windsurf, and VS Code Copilot each support MCP servers — point them at the same `uv run` command. Detailed steps in [`docs/SETUP.md`](docs/SETUP.md).\n\n---\n\n## MCP tools\n\n| Tool | What it does |\n|---|---|\n| [`find_issues`](docs/TOOLS_REFERENCE.md#find_issues) | Repo-first, scored search for beginner-friendly issues |\n| [`check_repo_health`](docs/TOOLS_REFERENCE.md#check_repo_health) | A-F grade for a repository's contributor-friendliness |\n| [`check_issue_status`](docs/TOOLS_REFERENCE.md#check_issue_status) | Is this specific issue actually available to work on? |\n| [`get_contribution_guide`](docs/TOOLS_REFERENCE.md#get_contribution_guide) | Pulls + summarises `CONTRIBUTING.md` / README setup |\n\nSee [`docs/TOOLS_REFERENCE.md`](docs/TOOLS_REFERENCE.md) for full parameter and return-shape specs.\n\n---\n\n## CLI and TUI\n\n```bash\nuv run gfi-scout-cli find python --min-stars 500 --max-results 10\nuv run gfi-scout-cli health fastapi/fastapi\nuv run gfi-scout-cli status https://github.com/fastapi/fastapi/issues/12345\nuv run gfi-scout-cli guide pallets/flask\nuv run gfi-scout-tui\n```\n\nEvery command supports `--output json` for scripts. See [`docs/CLI.md`](docs/CLI.md).\n\n---\n\n## How scoring works\n\n```\nbeginner_score = repo_health        × 0.30\n               + issue_freshness    × 0.20\n               + issue_clarity      × 0.15\n               + merge_friendliness × 0.25\n               + setup_complexity_inv × 0.10\n```\n\nEvery weight and threshold is loaded from [`src/gfi_scout/data/scoring_weights.json`](src/gfi_scout/data/scoring_weights.json). Want to retune the ranker? Edit the JSON and re-run — no code changes.\n\nFull breakdown in [`docs/SCORING_ALGORITHM.md`](docs/SCORING_ALGORITHM.md).\n\n---\n\n## Documentation\n\n| Doc | What's in it |\n|---|---|\n| [`docs/SETUP.md`](docs/SETUP.md) | Step-by-step install, env vars, client wiring |\n| [`docs/AGENT_CONNECTIONS.md`](docs/AGENT_CONNECTIONS.md) | Current MCP connection examples for Codex, Claude Code, Cursor, Antigravity, Pi Agent, and Hermes Agent |\n| [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) | Layering rules, request flow, caching, failure model |\n| [`docs/CLI.md`](docs/CLI.md) | Standalone CLI and terminal UI usage |\n| [`docs/TOOLS_REFERENCE.md`](docs/TOOLS_REFERENCE.md) | Parameters and return schemas for every MCP tool |\n| [`docs/SCORING_ALGORITHM.md`](docs/SCORING_ALGORITHM.md) | How `beginner_score` is computed and graded |\n| [`CONTRIBUTING.md`](CONTRIBUTING.md) | How to file issues and ship PRs |\n| [`SECURITY.md`](SECURITY.md) | Responsible-disclosure policy |\n| [`docs/CHANGELOG.md`](docs/CHANGELOG.md) | Release notes |\n| [`docs/Plan.md`](docs/Plan.md) | Original spec + phase plan |\n\n---\n\n## Development\n\n```bash\nuv sync                              # install everything\nuv run pytest                        # 106 tests in ~2 s\nuv run ruff check src/ tests/        # lint\nuv run ruff format src/ tests/       # format\nuv run mypy src/                     # strict type-check\nuv run mcp dev src/gfi_scout/server.py  # MCP Inspector\n```\n\n`uv.lock` is committed — every contributor gets identical dependency versions.\n\n### Project layout\n\n```\nsrc/gfi_scout/\n├── server.py          # FastMCP entry, tool registration\n├── cli.py             # Standalone CLI + terminal UI\n├── config.py          # Env loading\n├── runtime.py         # Shared cache/client wiring\n├── tools/             # One file per MCP tool\n│   ├── find_issues.py\n│   ├── check_repo_health.py\n│   ├── check_issue_status.py\n│   └── get_contribution_guide.py\n├── services/          # GitHub client, scoring, cache\n├── models/            # Pydantic models\n└── utils/             # Pure helpers (validators, rate limiter, logger)\n\ntests/                 # mirrors src/ layout\ndocs/                  # markdown docs\nscripts/               # dev automation (setup.sh, seed_cache.py)\n```\n\n> The scoring config lives inside the package at `src/gfi_scout/data/scoring_weights.json` so it ships with the installed wheel — no separate top-level `config/` directory. (The runtime settings module `gfi_scout/config.py` is unrelated; `data/` holds JSON, `config.py` reads env vars.)\n\nLayer rules and folder contracts: [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md).\n\n---\n\n## Troubleshooting\n\n**`scoring config not found: .../Lib/config/scoring_weights.json`**\n\nYou're on an old install (≤ v0.1.0) where the scoring config wasn't bundled into the wheel. Fix:\n\n```bash\nuv tool install --force --from git+https://github.com/Rajveerx11/gfi-scout gfi-scout\n```\n\nIf a long-running MCP server process holds the install directory open on Windows (`Access is denied` during reinstall), stop the host (Claude Desktop / Claude Code / Cursor) or kill the `gfi-scout` Python process first, then re-run the command.\n\n**Results are slow or you hit `rate limit exceeded` quickly**\n\nYou're probably running without a token (60 requests/hour). Set `GITHUB_TOKEN` — from the environment or a `.env` file in the working directory — to get 5,000 requests/hour. For `uv tool` installs, either export it in your shell profile or set it in the MCP client's `env` block (see *Connecting to an MCP client* above).\n\n---\n\n## Contributing\n\nIssues and PRs welcome — practising what we preach. Start at [`CONTRIBUTING.md`](CONTRIBUTING.md). Good first issues are labelled on the [tracker](https://github.com/Rajveerx11/gfi-scout/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22).\n\nBy participating you agree to the [Code of Conduct](CODE_OF_CONDUCT.md).\n\n---\n\n## Security\n\nFound a security issue? Please **don't** open a public issue — see [`SECURITY.md`](SECURITY.md) for the disclosure process.\n\nGFI Scout only ever needs `public_repo` (read-only) scope on your GitHub token.\n\n---\n\n## License\n\n[MIT](LICENSE) — because the whole point is helping people contribute to open source.\n\n---\n\n<div align=\"center\">\n\n*Built with frustration, then determination. Because finding your first open source contribution shouldn't require a PhD in \"how to navigate GitHub.\"*\n\n</div>\n",
  "bytes": 10913,
  "sha": "fe0270604ceade1c691f5bd382d72823baef903b772b0c346d5c83af821c9220",
  "repo_slug": "rajveerx11/gfi-scout",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_rajveerx11_gfi_scout_2366f091/readme"
}