@oss-autopilot/mcp

MCP server for OSS Autopilot — exposes PR tracking, issue discovery, and contribution management as MCP tools for any MCP-compatible client.

What It Provides

| Feature | Count | Description | |---------|-------|-------------| | Tools | 28 | daily, status, search, vet, vet-list, track, compliance-score, repo-vet, comments, post, claim, config, init, setup, check-setup, startup, shelve, unshelve, dismiss, undismiss, move, state-show, state-sync, state-unlink, guidelines-get, guidelines-store, guidelines-reset, guidelines-fetch-corpus | | Resources | 6 | oss://status, oss://config, oss://prs, oss://prs/shelved, oss://pr/{owner}/{repo}/{number}, oss://repo/{owner}/{repo}/guidelines | | Prompts | 4 | triage (PR prioritization), respond-to-pr (draft response), find-issues (discover issues), extract-learnings (distill per-repo guidance from past PR feedback) |

Supports stdio (default) and Streamable HTTP transports.

Prerequisites

• Node.js 22+
• GitHub CLI authenticated (gh auth login)

Quick Start

# 1. Add the server to your MCP client (see config examples below)

# 2. From your MCP client, call the `init` tool once with your GitHub username
#    (this writes ~/.oss-autopilot/state.json).

# 3. Use the other tools — e.g. `daily` to check your PRs, `search` to find issues.

Client Configuration

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "oss-autopilot": {
      "command": "npx",
      "args": ["@oss-autopilot/mcp@latest"]
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project or global config:

{
  "mcpServers": {
    "oss-autopilot": {
      "command": "npx",
      "args": ["@oss-autopilot/mcp@latest"]
    }
  }
}

Codex CLI

codex mcp add oss -- npx @oss-autopilot/mcp@latest

Windsurf

Add to your Windsurf MCP config:

{
  "mcpServers": {
    "oss-autopilot": {
      "command": "npx",
      "args": ["@oss-autopilot/mcp@latest"]
    }
  }
}

Streamable HTTP (any client)

Run the server in HTTP mode instead of stdio:

npx @oss-autopilot/mcp@latest --http --port 3001

The server listens at http://127.0.0.1:3001/mcp and accepts POST requests.

Authentication

HTTP mode requires a bearer token on every request (stdio mode does not — it inherits the parent process identity). On first --http startup, the server generates a random 32-byte token and writes it to ~/.oss-autopilot/mcp.token with 0600 permissions. The path and "newly generated" marker are logged to stderr at startup.

Every HTTP client must send:

Authorization: Bearer <contents of ~/.oss-autopilot/mcp.token>

Requests without a valid Authorization header return 401. The Bearer scheme is case-insensitive per RFC 7235; the token value itself is compared byte-for-byte in constant time. Requests with a non-loopback Host header return 403 (DNS-rebinding defense). Requests must declare a numeric Content-Length ≤ 1 MiB — missing, non-numeric, or oversize Content-Length values return 413.

The token persists across restarts. To rotate, delete the file and restart — a new token will be generated. To relocate the token (e.g. for multi-user or CI setups), set OSS_AUTOPILOT_MCP_TOKEN_PATH to the desired absolute path before starting the server.

Tools Reference

| Tool | Description | Read-only | |------|-------------|-----------| | daily | Run daily PR monitoring check with prioritized summary | No | | status | Show current PR tracking status | Yes | | search | Search GitHub for contributable issues | Yes | | vet | Analyze an issue for contribution suitability | Yes | | vet-list | Re-vet all available issues in the curated issue list | No | | track | Fetch metadata for a pull request (informational; nothing persists) | No | | compliance-score | Score a PR against opensource.guide best practices (#1245) | Yes | | repo-vet | Compute the repo health rubric (1–10 + verdict) for owner/repo (#1271) | Yes | | comments | Fetch and display PR comments | Yes | | post | Post a comment on an issue or PR | No | | claim | Claim an issue by posting a comment | No | | config | Get or set configuration values | No | | init | Initialize with a GitHub username | No | | setup | Configure preferences (languages, interests) | No | | check-setup | Check if setup is complete | Yes | | startup | Run startup checks (auth, state, config) | No | | shelve | Temporarily hide a PR from daily checks | No | | unshelve | Return a shelved PR to active monitoring | No | | dismiss | Dismiss an issue from notifications | No | | undismiss | Re-enable notifications for a dismissed issue | No | | move | Move a PR between states (attention, waiting, shelved, auto) | No | | state-show | Show current state persistence mode (local or Gist) and sync status | Yes | | state-sync | Force push current state to the backing Gist | No | | state-unlink | Disconnect from Gist persistence and switch to local-only mode | No | | guidelines-get | Read per-repo learning guidelines extracted from past PR feedback | Yes | | guidelines-store | Persist per-repo guidelines (8 KB cap; requires Gist mode) | No | | guidelines-reset | Tombstone the guidelines file for a repo | No | | guidelines-fetch-corpus | Fetch raw PR comment bundles for the host's extract-learnings prompt to consume | No |

Resources Reference

| Resource URI | Description | |-------------|-------------| | oss://status | PR tracking status (cached local state) | | oss://config | Current configuration | | oss://prs | Active open PRs from last daily digest | | oss://prs/shelved | Shelved PRs | | oss://pr/{owner}/{repo}/{number} | Detail for a specific PR | | oss://repo/{owner}/{repo}/guidelines | Per-repo learning guidelines (markdown) |

Prompts Reference

| Prompt | Args | Description | |--------|------|-------------| | triage | none | Fetches daily digest and builds a prioritized triage list | | respond-to-pr | prUrl | Fetches PR comments and context for drafting a response | | find-issues | maxResults? | Searches for issues ranked by viability score | | extract-learnings | repo, corpus, existingGuidelines? | Distills durable per-repo guidance from raw PR comment bundles (#867) |

Programmatic Usage

The server can also be imported and used as a library:

import { createServer } from '@oss-autopilot/mcp';

const server = createServer();
// Connect to your own transport

More Information

See the main repository README for the full documentation, including the Claude Code plugin, CLI usage, dashboard, and contributing guide.

License

MIT