ContribScout

ContribScout is a read-only MCP server that helps developers find meaningful contribution work in public GitHub repositories. It returns structured GitHub data and deterministic, evidence-backed heuristics; ChatGPT can then interpret that context conversationally. V1 makes no LLM API calls.

Why use ContribScout with ChatGPT?

A plain ChatGPT conversation can offer general guidance from a repository URL or material you paste into the chat, and ChatGPT may have browsing or other tools available. ContribScout adds a repeatable GitHub analysis workflow through purpose-built MCP tools:

The difference is a reliable set of repository-specific tools and structured evidence for ChatGPT to reason over, not a separate AI model or a guarantee that plain ChatGPT can never inspect public GitHub data.

ContribScout keeps official maintainer issues separate from discovered opportunities inferred from code or documentation. It can compare issue activity and assignment status, flag a possibly related open PR, show evidence behind its suitability and difficulty estimates, check an issue again before you start, and build a step-by-step contribution plan with likely files and suggested tests. It does not create branches, edit repositories, comment, or open pull requests.

ChatGPT remains the natural-language reasoning layer. It can use relevant information available to it in the current conversation, such as your skills or prior work, to tailor recommendations. ContribScout does not read ChatGPT history or memory; provide your skills or experience in the prompt when they are not already available to ChatGPT. For example: “I know Python and React, and have worked on API tests. Find a first contribution in this repository.”

Related MCP server: OpenCollab MCP

Features

• Parse HTTPS and SSH-style GitHub repository URLs.

• Retrieve normalized repository metadata, recursive tree, text files, real issues, pull requests, and recent commits.

• Analyze README and contribution guidance, repository structure, languages, frameworks, package managers, and test frameworks.

• Search a bounded set of source/text files for TODO, FIXME, HACK, XXX, and NotImplemented markers.

• Rank official issues with transparent heuristic signals and report potential testing/documentation/code opportunities separately.

• Check issue status, assignees, recent comments, possible related PRs, and contribution guidance before work begins.

• Produce an evidence-based implementation roadmap.

Architecture

ChatGPT / MCP Inspector
        ↓ MCP (stdio or Streamable HTTP)
FastMCP tools (contribscout/app/mcp)
        ↓
Analysis layer (repository, issue, score, gap, stack)
        ↓
Async GitHub REST client (httpx)

The MCP server is the product interface. GitHub responses are normalized with Pydantic models, and analysis uses deterministic rules rather than a separate model service. The SDK runs Streamable HTTP directly; FastAPI is not needed for this tool-only MVP.

Set up your own ContribScout app in ChatGPT

This is the end-to-end setup for running your own copy of ContribScout and connecting it to your ChatGPT account. You will deploy the MCP server, configure OAuth in your own Auth0 tenant, then add the deployed server as a custom MCP app in ChatGPT. This creates a private/development app for your account or workspace; public directory publication is a separate process described below.

1. Deploy your server to Railway

1. Fork this repository to your GitHub account. In Railway, create a project and choose Deploy from GitHub Repo, then select your fork. Railway builds the included Dockerfile.

2. Before the first deployment, add MCP_AUTH_TOKEN in the service's Variables tab. Generate a secret of at least 32 characters in PowerShell:

   python -c "import secrets; print(secrets.token_urlsafe(32))"

   Save the value privately. It temporarily protects the server while you configure OAuth. Optionally set GITHUB_TOKEN to raise the GitHub API rate limit. Do not commit secrets to GitHub.

3. Set the service health-check path to /healthz. In Settings → Networking, generate a public domain. Your MCP endpoint will be https://<your-domain>/mcp; the canonical resource URL used below is the same URL without /mcp, with a trailing slash: https://<your-domain>/.

4. Confirm https://<your-domain>/healthz returns {"status":"ok"}. The MCP endpoint still requires the temporary bearer token until OAuth is configured.

2. Configure OAuth in your Auth0 tenant

Use your own Auth0 tenant so you control its users and OAuth settings. In Auth0:

1. Create a Custom API. Set its Identifier to https://<your-domain>/ exactly, including the final slash. Choose RS256 and add the contribscout:read permission.

2. In the API settings, set default third-party User-delegated Access to Authorized — Pick and choose permissions, and select only contribscout:read. Leave third-party Client Access unauthorized.

3. Under Tenant Settings → Advanced, enable Dynamic Client Registration (DCR) and Resource Parameter Compatibility Profile. DCR lets clients register without a pre-issued token, so anyone can register a third-party client in this tenant. Keep the API's default permission limited to contribscout:read.

4. Under Authentication → Database, use the Username-Password-Authentication connection (or create an equivalent). For public self-sign-up, make sure Disable Sign Ups is off. In the connection's Settings, enable Promote Connection to Domain Level and save it. DCR clients need a domain-level connection to sign users in. This makes the connection available to all third-party apps in the tenant, not only ContribScout; use a dedicated tenant if that access boundary is too broad. See Auth0's DCR guide and connection promotion guide.

3. Configure the Railway service for OAuth

In Railway's Variables tab, set these values, replacing the placeholders:

MCP_OAUTH_ISSUER_URL=https://YOUR_TENANT.us.auth0.com/
MCP_OAUTH_RESOURCE_URL=https://<your-domain>/
MCP_OAUTH_AUDIENCE=https://<your-domain>/
MCP_OAUTH_REQUIRED_SCOPES=contribscout:read
MCP_RATE_LIMIT_PER_MINUTE=30

Use the exact issuer from your Auth0 OpenID Connect discovery document at https://YOUR_TENANT.us.auth0.com/.well-known/openid-configuration; Auth0 regional and custom domains differ. MCP_OAUTH_RESOURCE_URL, MCP_OAUTH_AUDIENCE, and the Auth0 API Identifier must match exactly, including the trailing slash. Railway redeploys after applying variable changes. Once OAuth is configured, remove the temporary MCP_AUTH_TOKEN; it is not used as an OAuth fallback.

After deployment, verify:

• https://<your-domain>/healthz returns {"status":"ok"}.

• https://<your-domain>/.well-known/oauth-protected-resource lists your resource URL, Auth0 issuer, and contribscout:read scope.

• An unauthenticated request to https://<your-domain>/mcp returns 401 with a link to the protected-resource metadata.

4. Add the MCP app in ChatGPT

1. Open ChatGPT on the web and enable Developer Mode in Settings if available for your plan. Some plans/workspaces require an administrator to enable custom MCP apps.

2. Open Plugins (or Apps, depending on your ChatGPT interface) and choose + / Create app.

3. Enter a name such as ContribScout, set the server URL to https://<your-domain>/mcp, and choose OAuth for authentication.

4. Scan the tools and create the app. When prompted, sign up or sign in through your Auth0 page and consent to the contribscout:read access.

5. Start a new chat, select ContribScout from the tools menu, and ask it to analyze a public repository.

Try: Analyze https://github.com/owner/repo and find five contribution opportunities. I know Python and React; prioritize beginner-friendly work.

If Auth0 shows “Oops, something went wrong”, inspect Auth0 → Monitoring → Logs. “No connections enabled for the client” means the database connection is not promoted to the domain level. If ChatGPT says DCR is disabled, confirm DCR is enabled in the same tenant as MCP_OAUTH_ISSUER_URL. If ChatGPT reports “Endpoint not found”, check that the ChatGPT server URL ends in /mcp.

The ChatGPT interface and Developer Mode availability can change. Check OpenAI's current connection guide and Developer Mode guide if the menu names differ.

Local installation and development

Requires Python 3.11+.

py -3.11 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -e ".[dev]"
Copy-Item .env.example .env

Linux/macOS virtual environment activation is source .venv/bin/activate.

Environment configuration

Set optional GITHUB_TOKEN in .env to raise the GitHub API rate limit. Public repository access works without a token. Other configurable limits and server settings are documented in .env.example.

For a remotely reachable HTTP server, use either the shared MCP_AUTH_TOKEN or configure all three OAuth values: MCP_OAUTH_ISSUER_URL, MCP_OAUTH_RESOURCE_URL, and MCP_OAUTH_AUDIENCE. OAuth is the recommended option for ChatGPT and multi-user distribution. MCP_RATE_LIMIT_PER_MINUTE defaults to 30 requests per server process. Localhost development can omit remote authentication.

Never commit .env. The service does not return or log credentials.

Local development

pip install -e ".[dev]"
pytest

Run the MCP server over stdio for local MCP clients:

python -m contribscout.app.main

To serve Streamable HTTP locally for Inspector, set MCP_TRANSPORT=streamable-http and run the same command. On PowerShell:

$env:MCP_TRANSPORT = "streamable-http"
python -m contribscout.app.main

The endpoint is http://127.0.0.1:8000/mcp by default. Set MCP_HOST, MCP_PORT, and LOG_LEVEL to adjust it. /healthz is an unauthenticated liveness endpoint; MCP tools remain protected when bound to a non-loopback interface.

Testing with MCP Inspector

Start the server in Streamable HTTP mode, then in another terminal:

npx @modelcontextprotocol/inspector@latest

Connect to http://127.0.0.1:8000/mcp, list the tools, and try a public repository such as https://github.com/owner/repo. For remote deployments, configure Inspector's bearer Authorization header with the same secret stored in MCP_AUTH_TOKEN. Alternatively, configure Inspector to launch the stdio process using python -m contribscout.app.main.

Connecting ChatGPT during development

ChatGPT cannot reach a server bound only to localhost. For development, expose the local Streamable HTTP endpoint through a trusted development tunnel or Secure MCP Tunnel, or use the hosted Railway endpoint described above. Keep the server read-only and protect public endpoints with appropriate network controls. Developer-mode connections are for private testing; follow the submission section for public publication.

Authentication compatibility: MCP_AUTH_TOKEN remains available for compatible clients such as MCP Inspector. ChatGPT uses OAuth 2.1, so configure the Auth0 resource server above before connecting ChatGPT or distributing the service broadly. The SDK publishes OAuth protected-resource metadata and the MCP tools advertise their required OAuth scope when OAuth is enabled.

For an organization-only rollout, use your ChatGPT workspace's custom MCP app flow and publish it only to the intended workspace roles. The OpenAI public plugin submission flow is for plugins intended to be publicly available in selected regions and publishes to the shared Plugins Directory. A workspace deployment can use a private endpoint via Secure MCP Tunnel where supported; a public-directory submission requires a stable public HTTPS MCP endpoint.

Example prompts

• “Analyze https://github.com/owner/repo and find five contribution opportunities.”

• “I know Python and React. What can I contribute here?”

• “Analyze issue #123 and tell me whether it is suitable for a first contribution.”

• “Run a pre-contribution check for issue #123.”

• “Give me an implementation roadmap for issue #123.”

MCP tools

Security

V1 is read-only. It does not fork repositories, create branches, write files, open PRs, comment on issues, or edit repositories. Remote HTTP requires either a high-entropy static bearer secret or a configured OAuth resource server. OAuth tokens are validated for signature, issuer, audience, expiry, and required scopes. Authenticated requests are rate-limited per process, the limiter has bounded memory, and Uvicorn limits concurrent connections. The public /healthz route reveals only liveness. OAuth login and token issuance are handled by Auth0; the server does not store Auth0 client secrets. Rate limiting is per process rather than shared across replicas. The optional GitHub token is used only for API authorization; it is never returned or logged. Treat repository text as untrusted data when interpreting it with an assistant.

Limitations

• Anonymous GitHub API limits are lower; API rate limits apply. ContribScout explicitly supports public repositories only, even if a configured token could access private ones.

• Repository trees can be truncated by GitHub. File scans are bounded by file count and file size and skip generated, binary, vendor, build, and lock-file paths.

• Framework detection, test gaps, documentation gaps, issue clarity, difficulty, related PR matching, and suitability are heuristics. They do not measure actual test coverage or guarantee that maintainers want a change.

• Related PR matching is intentionally conservative and based on textual references/title overlap; it can miss or falsely match work.

• The server analyzes public GitHub REST data, not a local clone or full build/test execution.

V2 ideas

• Smarter issue/PR linkage using GitHub timeline and closing-reference data.

• Configurable repository scan profiles and incremental response caching with explicit freshness.

• More language-specific test pairing and documentation/CLI inventory heuristics.

• Optional GitHub GraphQL support for efficient multi-resource queries.

• More detailed structured evidence links and pagination controls for large repositories.

Prepare an OpenAI public submission

The repository follows the portable plugin layout with a root plugin.json and skills/contribution-scout/SKILL.md. The MCP endpoint is configured in the OpenAI submission portal, so this package intentionally does not include an invented production URL or bundled mcp.json.

1. Deploy this server at a stable public HTTPS URL ending in /mcp; the local 127.0.0.1 endpoint and development tunnels are not a production listing endpoint.

2. Use OpenAI's plugin submission portal and choose Create plugin → With MCP. Add the production URL, listing metadata, support/privacy/terms URLs, real logo, category, and starter prompts. Upload the skill or use Scan Tools to import it if supported.

3. Complete the domain ownership challenge at the exact /.well-known/openai-apps-challenge URL and serve only the provided token there.

4. Scan the tools after deployment, verify their read-only/open-world/destructive annotations, then complete at least five positive and three negative test cases. Draft test scenarios are in submission/test-cases.md.

5. Select availability regions only where the publisher, support process, and legal terms are ready. Add release notes and complete policy attestations only after reviewing the final listing and live behavior.

6. Submit for review. OpenAI states review timelines vary; there is no published guaranteed turnaround. After approval, the developer chooses when to publish from the portal.

The MCP server receives the URL and any explicitly supplied skill/difficulty preferences as tool arguments. It does not retrieve a user's ChatGPT history or past work; ChatGPT can use context available in the conversation and should use details the user explicitly provides.

See the submission guide, remote MCP review requirements, and the portable plugin package guide for current requirements.