gfi-scout
This server helps you discover and evaluate beginner-friendly open source issues on GitHub, so you can pick ones you're most likely to successfully contribute to.
find_issues – Search GitHub for “good first issue” labelled issues, scored by repo health, freshness, clarity, and merge likelihood. Filter by language, minimum stars, topics, labels, and sort by score or other criteria. Excludes already-assigned issues by default.
check_repo_health – Analyze a repository’s contributor-friendliness: merge rate, last commit date, maintainer response time, presence of contributing guide / code of conduct, CI configuration, and an overall A–F health grade.
check_issue_status – Check whether a specific GitHub issue is actually available: see if it’s assigned, has linked PRs (competitor PRs), is stale, and get an availability verdict (e.g., available, likely taken, stale).
get_contribution_guide – Pull and summarize a repo’s contribution guide and setup instructions: required tools, testing requirements, PR conventions, setup complexity, and source files to read.
Flexible invocation – Use it as an MCP server (stdio or streamable HTTP) for AI assistants, or as a standalone CLI / TUI via
gfi-scout-cliandgfi-scout-tui.Configurable scoring – All scoring weights and thresholds are stored in a JSON file inside the package, so you can tweak the algorithm without changing code.
Allows searching for beginner-friendly GitHub issues, checking repository health, verifying issue availability, and retrieving contribution guides from GitHub repositories.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@gfi-scoutFind me Python good first issues in repos with at least 500 stars"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
GFI Scout

An MCP server and standalone CLI that finds open source issues where beginners actually succeed — not just any issue tagged good first issue.
mcp-name: io.github.Rajveerx11/gfi-scout
Why this exists
Most "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.
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.
It ships as a Model Context Protocol server, plus a standalone CLI/TUI for terminal-first workflows.
Related MCP server: mcp-github
Features
🔎
find_issues— repo-first language + topic + star-range discovery with scored issue results🩺
check_repo_health— merge rate, last commit, CONTRIBUTING/CoC/CI probes → A-F grade⏱️
check_issue_status— assignment, linked PRs, staleness, maintainer confirmation →AVAILABLE/LIKELY_TAKEN/STALEverdict📘
get_contribution_guide— pulls and summarisesCONTRIBUTING.md, detects toolchain, estimates setup complexityTerminal commands via
gfi-scout-cliand an interactivegfi-scout-tui⚡ Parallel GitHub API fan-out (
asyncio.gather) + per-namespace TTL cache, with opt-in SQLite persistence across sessions🎛️ All scoring weights and thresholds live in
src/gfi_scout/data/scoring_weights.json— no magic numbers in code🧪 100+ tests (unit + integration),
mypy --strictclean,ruffclean
Requirements
Python | 3.12+ |
Package manager |
|
Auth | Optional — works without a token at 60 req/h; a PAT with |
Quick start
# 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-tuiInstall as a global uv tool
If 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:
# 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-scoutA 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.
Connecting to an MCP client
Claude Desktop
Add this to 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"
}
}
}
}Restart Claude Desktop, then try:
"Find me Python good first issues with at least 500 stars."
"Is this issue actually available? https://github.com/fastapi/fastapi/issues/12345"
"What's the setup complexity for
pallets/flask?"
Other clients
Cursor, Windsurf, and VS Code Copilot each support MCP servers — point them at the same uv run command. Detailed steps in docs/SETUP.md.
MCP tools
Tool | What it does |
Repo-first, scored search for beginner-friendly issues | |
A-F grade for a repository's contributor-friendliness | |
Is this specific issue actually available to work on? | |
Pulls + summarises |
See docs/TOOLS_REFERENCE.md for full parameter and return-shape specs.
CLI and 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-tuiEvery command supports --output json for scripts. See docs/CLI.md.
How scoring works
beginner_score = repo_health × 0.30
+ issue_freshness × 0.20
+ issue_clarity × 0.15
+ merge_friendliness × 0.25
+ setup_complexity_inv × 0.10Every weight and threshold is loaded from src/gfi_scout/data/scoring_weights.json. Want to retune the ranker? Edit the JSON and re-run — no code changes.
Full breakdown in docs/SCORING_ALGORITHM.md.
Documentation
Doc | What's in it |
Step-by-step install, env vars, client wiring | |
Current MCP connection examples for Codex, Claude Code, Cursor, Antigravity, Pi Agent, and Hermes Agent | |
Layering rules, request flow, caching, failure model | |
Standalone CLI and terminal UI usage | |
Parameters and return schemas for every MCP tool | |
How | |
How to file issues and ship PRs | |
Responsible-disclosure policy | |
Release notes | |
Original spec + phase plan |
Development
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 Inspectoruv.lock is committed — every contributor gets identical dependency versions.
Project layout
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)The scoring config lives inside the package at
src/gfi_scout/data/scoring_weights.jsonso it ships with the installed wheel — no separate top-levelconfig/directory. (The runtime settings modulegfi_scout/config.pyis unrelated;data/holds JSON,config.pyreads env vars.)
Layer rules and folder contracts: docs/ARCHITECTURE.md.
Troubleshooting
scoring config not found: .../Lib/config/scoring_weights.json
You're on an old install (≤ v0.1.0) where the scoring config wasn't bundled into the wheel. Fix:
uv tool install --force --from git+https://github.com/Rajveerx11/gfi-scout gfi-scoutIf 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.
Results are slow or you hit rate limit exceeded quickly
You'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).
Contributing
Issues and PRs welcome — practising what we preach. Start at CONTRIBUTING.md. Good first issues are labelled on the tracker.
By participating you agree to the Code of Conduct.
Security
Found a security issue? Please don't open a public issue — see SECURITY.md for the disclosure process.
GFI Scout only ever needs public_repo (read-only) scope on your GitHub token.
License
MIT — because the whole point is helping people contribute to open source.
Built with frustration, then determination. Because finding your first open source contribution shouldn't require a PhD in "how to navigate GitHub."
Available Tools
4 toolscheck_issue_statusA
Check whether a specific GitHub issue is actually available to work on.
Args:
issue_url: Full GitHub issue URL.
| Name | Required | Description | Default |
|---|---|---|---|
| issue_url | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| notes | No | |
| is_stale | Yes | |
| issue_url | Yes | |
| is_assigned | Yes | |
| has_linked_pr | Yes | |
| last_activity | Yes | |
| competitor_prs | Yes | |
| availability_verdict | Yes | |
| maintainer_confirmed | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only states the core purpose without disclosing behavioral details such as authentication requirements, what 'available' means (e.g., open, unassigned, not locked), or potential side effects. This leaves the agent to infer the tool's safety and conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, leading with the purpose, then the parameter definition. Every word is functional.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one parameter and an output schema, the description covers the basic operation but lacks context on what 'available' entails, when to choose this over find_issues, and any prerequisites. It is adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description clarifies that the parameter should be a 'Full GitHub issue URL' (not just an issue number), adding meaning beyond the schema's basic 'Issue Url' string. Since schema coverage is 0%, this compensation is helpful.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'check' and resource 'specific GitHub issue', clearly indicating it verifies availability of a single issue. It distinguishes itself from sibling tools like find_issues (searching) and check_repo_health (repo-level).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies it should be used when you have a specific issue URL and want to know if it's workable. However, it does not mention alternative tools or when not to use it, so it misses explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
check_repo_healthB
Analyse a repository's contributor-friendliness.
Args:
repo: Full repo name, e.g. "fastapi/fastapi".
| Name | Required | Description | Default |
|---|---|---|---|
| repo | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| notes | No | |
| merge_rate | No | |
| health_grade | Yes | |
| ci_configured | Yes | |
| repo_full_name | Yes | |
| last_commit_date | No | |
| has_code_of_conduct | Yes | |
| avg_merge_time_hours | No | |
| avg_review_time_hours | No | |
| has_contributing_guide | Yes | |
| active_contributors_30d | No | |
| maintainer_response_time_hours | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full responsibility for disclosing behavior. It only states the tool 'analyse[s]' a repository, but does not clarify whether this is read-only, whether it performs network calls, or what metrics are involved. No side effects, permissions, or return behavior are disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise and front-loaded: it states the purpose in one line and provides parameter documentation in another. Every word earns its place, with no fluff or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has one parameter and an output schema, so return-value details may be covered elsewhere. However, the description lacks any usage guidance relative to sibling tools and does not clarify what 'contributor-friendliness' means. It's minimally sufficient but leaves significant gaps in practical context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'repo' is described as 'Full repo name, e.g. "fastapi/fastapi"' which adds practical meaning beyond the schema's bare string type and required flag. The example clarifies the expected format, compensating well for the 0% schema description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the tool's function: 'Analyse a repository's contributor-friendliness.' This is a specific verb+resource that distinguishes it from sibling tools like check_issue_status or find_issues. However, it doesn't elaborate on what 'contributor-friendliness' entails, so it's clear but not maximally precise.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention exclusions, prerequisites, or sibling tools. The intended usage context is implied by the phrase 'contributor-friendliness' but never made explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
find_issuesA
Find beginner-friendly open source issues ranked by likelihood of success.
Searches GitHub for "good first issue" labelled issues, scores each by
repo health + freshness + clarity + merge friendliness + setup ease,
and returns the top results.
Args:
language: Programming language (e.g. "python", "typescript").
min_stars: Minimum repo stars. Default 50.
max_stars: Maximum repo stars. Default 50000.
labels: Issue labels to require. Default ["good first issue"].
max_results: How many results (1-25).
sort_by: "beginner_score" | "freshness" | "repo_health".
topic: Optional GitHub topic filter ("web", "cli", "data-science", ...).
unassigned_only: When True (default), excludes issues that already
have an assignee. Set False to widen the search when narrow
language/label/stars combos return zero hits.
| Name | Required | Description | Default |
|---|---|---|---|
| topic | No | ||
| labels | No | ||
| sort_by | No | beginner_score | |
| language | Yes | ||
| max_stars | No | ||
| min_stars | No | ||
| max_results | No | ||
| unassigned_only | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure and does well: it explains that it searches GitHub, factors the scoring (repo health, freshness, clarity, merge friendliness, setup ease), and describes the default behavior of unassigned_only. It does not mention rate limits or API auth, but for a search tool this is sufficient detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a concise summary paragraph followed by a clean Args list. Every sentence adds value, and the formatting makes the tool immediately scannable. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers all 8 parameters, the ranking logic, the search source, and an edge-case behavior (unassigned_only=False to widen searches). It does not document the return format, but an output schema exists, so that burden is satisfied elsewhere. For a tool of this complexity, this is fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description fully compensates by providing detailed parameter semantics: defaults, allowed values for sort_by, example values for language and topic, and a behavioral note for unassigned_only. This is exemplary parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Find beginner-friendly open source issues ranked by likelihood of success.' It clearly distinguishes from siblings (check_repo_health, check_issue_status, get_contribution_guide) by focusing on searching and ranking issues rather than checking individual repos or issue status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description makes the primary use case obvious (finding beginner-friendly issues) and gives contextual advice, such as setting unassigned_only=False to widen searches when narrow combinations return zero hits. However, it does not explicitly name alternatives or state when NOT to use this tool, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_contribution_guideA
Pull and summarise a repo's contribution guide + setup instructions.
Args:
repo: Full repo name, e.g. "fastapi/fastapi".
| Name | Required | Description | Default |
|---|---|---|---|
| repo | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| source_files | Yes | |
| pr_conventions | Yes | |
| repo_full_name | Yes | |
| required_tools | Yes | |
| setup_complexity | Yes | |
| setup_instructions | Yes | |
| contributing_summary | Yes | |
| testing_requirements | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action but gives no details about whether it is read-only, requires network access, or how it handles missing guides. There is no mention of side effects or failure modes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise, front-loading the core purpose in the first sentence and providing parameter details in the second. Every word earns its place without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter tool with an output schema, the description adequately covers the purpose and parameter format. It does not need to explain return values due to the output schema, though it could add a note about potential errors when no guide exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaningful value for the 'repo' parameter by specifying the expected format ('Full repo name') and providing an example. Since the schema only has a type and title with no description, this guidance is helpful.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with a specific verb ('Pull and summarise') and resource ('contribution guide + setup instructions'). It is easily distinguishable from sibling tools focused on repo health, issues, and finding issues.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description only implies when to use the tool (when contribution guide/setup instructions are needed) and does not explicitly mention alternatives or exclusions. While the sibling context makes the use case fairly obvious, explicit guidance is missing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
4 tool updates
v0.2.0- First observed
check_issue_status - First observed
check_repo_health - First observed
find_issues - First observed
get_contribution_guide
TDQS
Scored across 4 tools
Each tool targets a distinct task: repo health analysis, issue availability check, contribution guide retrieval, and issue search. There is no ambiguity or overlap between their purposes.
All tool names follow a consistent verb_noun pattern in snake_case (check_, check_, get_, find_), making the API predictable and easy to navigate.
With 4 tools, the server is well-scoped for its specialized purpose of scouting good first issues. Each tool serves a clear role and no tool feels superfluous or missing for the core workflow.
The tool set covers the key workflow: finding candidate issues, checking repo health, verifying issue availability, and getting setup guidance. A minor gap is lack of direct issue content retrieval, but the existing tools enable a complete scouting flow.
Maintenance
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Connectors
Create, deploy, and operate MCP servers directly from your GitHub repositories.
An MCP server that gives your AI access to the source code and docs of all public github repos
A MCP server built for developers enabling Git based project management with project and personal…
MCP server aggregating developer infrastructure deals, free tiers, and startup programs
Related MCP Servers
- AlicenseAqualityDmaintenanceAn MCP server that scouts truly beginner-friendly open-source issues from GitHub, checking availability and summarizing them for AI consumption.130MIT
- FlicenseNot gradedqualityDmaintenanceMCP server for GitHub operations, providing tools for repository management, issues, pull requests, and code search.-
- FlicenseNot gradedqualityCmaintenanceMCP server that triages GitHub issues by classifying, ranking priority, and assigning an engineer using a local LLM (Ollama) with full traceability.-
- AlicenseAqualityCmaintenanceMCP server that computes a GitHub repo maintenance/abandonment health score from live GitHub data, providing a 0-100 score and verdict via the check_repo_health tool.140MIT