Skip to main content
Glama

GFI Scout

gfi-scout Demo

An MCP server and standalone CLI that finds open source issues where beginners actually succeed — not just any issue tagged good first issue.

CI Python 3.12+ License: MIT Built with uv MCP Code style: ruff

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 / STALE verdict

  • 📘 get_contribution_guide — pulls and summarises CONTRIBUTING.md, detects toolchain, estimates setup complexity

  • Terminal commands via gfi-scout-cli and an interactive gfi-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 --strict clean, ruff clean


Requirements

Python

3.12+

Package manager

uv (all commands go through uv)

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


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-tui

Install 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-scout

A 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

find_issues

Repo-first, scored search for beginner-friendly issues

check_repo_health

A-F grade for a repository's contributor-friendliness

check_issue_status

Is this specific issue actually available to work on?

get_contribution_guide

Pulls + summarises CONTRIBUTING.md / README setup

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-tui

Every 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.10

Every 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

docs/SETUP.md

Step-by-step install, env vars, client wiring

docs/AGENT_CONNECTIONS.md

Current MCP connection examples for Codex, Claude Code, Cursor, Antigravity, Pi Agent, and Hermes Agent

docs/ARCHITECTURE.md

Layering rules, request flow, caching, failure model

docs/CLI.md

Standalone CLI and terminal UI usage

docs/TOOLS_REFERENCE.md

Parameters and return schemas for every MCP tool

docs/SCORING_ALGORITHM.md

How beginner_score is computed and graded

CONTRIBUTING.md

How to file issues and ship PRs

SECURITY.md

Responsible-disclosure policy

docs/CHANGELOG.md

Release notes

docs/Plan.md

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 Inspector

uv.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.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.)

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-scout

If 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 tools
check_issue_statusA

Check whether a specific GitHub issue is actually available to work on.

Args:
    issue_url: Full GitHub issue URL.
ParametersJSON Schema
NameRequiredDescriptionDefault
issue_urlYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
notesNo
is_staleYes
issue_urlYes
is_assignedYes
has_linked_prYes
last_activityYes
competitor_prsYes
availability_verdictYes
maintainer_confirmedYes

TDQS

A3.9/5.0
Behavior2/5

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.

Conciseness5/5

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.

Completeness3/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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".
ParametersJSON Schema
NameRequiredDescriptionDefault
repoYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
notesNo
merge_rateNo
health_gradeYes
ci_configuredYes
repo_full_nameYes
last_commit_dateNo
has_code_of_conductYes
avg_merge_time_hoursNo
avg_review_time_hoursNo
has_contributing_guideYes
active_contributors_30dNo
maintainer_response_time_hoursNo

TDQS

B3.2/5.0
Behavior2/5

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.

Conciseness5/5

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.

Completeness3/5

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.

Parameters4/5

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.

Purpose4/5

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.

Usage Guidelines2/5

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.
ParametersJSON Schema
NameRequiredDescriptionDefault
topicNo
labelsNo
sort_byNobeginner_score
languageYes
max_starsNo
min_starsNo
max_resultsNo
unassigned_onlyNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.6/5.0
Behavior4/5

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.

Conciseness5/5

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.

Completeness5/5

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.

Parameters5/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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".
ParametersJSON Schema
NameRequiredDescriptionDefault
repoYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
source_filesYes
pr_conventionsYes
repo_full_nameYes
required_toolsYes
setup_complexityYes
setup_instructionsYes
contributing_summaryYes
testing_requirementsYes

TDQS

A3.8/5.0
Behavior2/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines3/5

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.

  1. 4 tool updatesv0.2.0
    • First observedcheck_issue_status
    • First observedcheck_repo_health
    • First observedfind_issues
    • First observedget_contribution_guide

TDQS

A4/5.0

Scored across 4 tools

Disambiguation5/5

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.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern in snake_case (check_, check_, get_, find_), making the API predictable and easy to navigate.

Tool Count5/5

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.

Completeness4/5

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

ActivityMaintained
ResponsivenessWithin a week

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

Related MCP Servers

  • F
    license
    Not graded
    quality
    D
    maintenance
    MCP server for GitHub operations, providing tools for repository management, issues, pull requests, and code search.
    -
  • A
    license
    A
    quality
    C
    maintenance
    MCP 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.
    1
    40
    MIT