Core

What @oss-scout/core does

@oss-scout/core helps identify GitHub issues that match a contributor's interests and are plausible candidates for a future pull request. It considers repositories where the user has previously had pull requests merged, preferred organizations, starred repositories, broad language and label searches, and maintained projects organized by topic.

The package assigns each candidate a viability score from 0 to 100. Scoring and vetting use signals such as repository activity, stars, contribution history, issue clarity, contribution guidance, existing pull requests, and whether someone has claimed the issue. It also filters patterns associated with label farming and templated issue titles.

The MCP server is part of the same package as the CLI and library. The provided documentation describes the shared issue discovery and vetting behavior, but does not specify a separate MCP transport, command, or tool name.

How it works

A search normally runs one strategy at a time and rotates between strategies on successive runs. Available strategies include:

• merged: repositories where the user has merged pull requests
• orgs: repositories in configured preferred organizations
• starred: the user's starred repositories
• broad: general searches filtered by labels and languages
• maintained: active repositories discovered by topic

The --full option runs every strategy in one search, while --strategy restricts the rotation set. Strategies without usable data are skipped. The starred strategy avoids running when the GitHub REST search quota is critically low; broad and maintained searches use GraphQL and are not affected by that condition.

Each candidate receives parallel checks for existing pull requests, claim comments, project health, implementation clarity, contribution instructions, and the user's merge history. Results are stored locally in ~/.oss-scout/state.json, deduplicated across searches, and can be re-vetted to detect transitions such as becoming claimed, having a pull request, or closing.

Setup and configuration

The package requires Node.js 20 or newer. GitHub access can come from an authenticated GitHub CLI session created with gh auth login, or from the GITHUB_TOKEN environment variable.

Run npx @oss-scout/core setup to configure preferences without a prior package installation, or install it globally with npm install -g @oss-scout/core. Interactive setup accepts preferred languages, issue labels, difficulty levels, a minimum star count, project categories, and repositories to exclude.

Run oss-scout bootstrap to import merged and closed pull requests plus starred repositories. This data gives later searches and scoring a record of the user's GitHub activity. Preferences can be viewed or changed with oss-scout config and oss-scout config set.

Optional gist persistence synchronizes preferences, repository scores, pull request history, and saved results between machines. It requires a GitHub token with the gist scope.

Tools and capabilities

The @oss-scout/core MCP server is suited to workflows that need to discover and assess contribution opportunities rather than simply list labeled issues. The package supports searching, inspecting saved results, vetting one issue, re-vetting all saved issues, and managing a skip list. JSON output is available for results and vet-list operations, including status transitions for automated processing.

Saved issues can be skipped permanently, and rejected issues are added to the skip list with a reason. results clear, skip remove, and skip clear provide explicit cleanup controls.

Limitations and notes

The package depends on GitHub API access and its available quotas. Search coverage is intentionally divided among strategies, so a normal search does not query every source at once. Results also depend on the quality and availability of GitHub history, issue comments, timelines, repository metadata, and contribution documentation.

The supplied material confirms Claude Code plugin support, but does not list MCP client compatibility beyond that. It also does not document MCP-specific configuration, transport details, or individually named MCP tools, so those details should be verified before deployment.