Content
# RepoPilot MCP
RepoPilot MCP is a TypeScript monorepo for experimenting with GitHub pull request analysis through a Model Context Protocol (MCP) workflow. It combines a Next.js interface, a Fastify API, a BullMQ worker, a custom read-only MCP server, and Prisma-backed trace storage so each analysis can be queued, executed, reviewed, and audited locally.
The current workflow accepts a GitHub pull request URL, creates an analysis session, runs a small MCP tool chain, stores the result, and shows both the recommendation and the underlying tool-call trace in the web app.
## Highlights
- Pull request URL parsing and validation with shared TypeScript contracts.
- Fastify API routes for creating analyses, polling session status, and fetching traces.
- BullMQ worker pipeline backed by Redis.
- Custom stdio MCP server with read-only tools:
- `get_pr_summary`
- `get_changed_files`
- `analyze_diff_risk`
- `suggest_tests`
- Prisma/PostgreSQL persistence for users, repositories, sessions, PR results, GitHub App installations, and tool calls.
- Fixture mode for local demos, plus optional GitHub App credentials for live repository reads.
- Next.js UI for submitting PRs and reviewing the analysis output.
## Architecture
```text
apps/
web/ Next.js App Router frontend.
api/ Fastify API for analysis/session/trace endpoints.
worker/ BullMQ worker that executes the PR analysis flow.
mcp-server/ Custom stdio MCP server exposing read-only PR tools.
packages/
shared/ Contracts, schemas, env parsing, redaction, GitHub helpers, and server utilities.
prisma/ Database schema, migrations, and seed script.
tests/ API, queue, parser, MCP, fixture, and GitHub App coverage.
```
At runtime the web app calls the API, the API stores a queued session and enqueues a job, the worker calls the MCP server tools, and the final result plus tool trace are persisted for the UI.
## Requirements
- Node.js 24 or newer
- npm 11 or newer
- Docker, for the local Postgres and Redis services
## Quick Start
Install dependencies and create a local environment file:
```sh
npm install
cp .env.example .env
```
Start Postgres and Redis:
```sh
docker compose up -d
```
Generate Prisma artifacts, run migrations, seed local data, and build the TypeScript packages:
```sh
npm run db:generate
npm run db:migrate
npm run db:seed
npm run build:ts
```
Run the app in three terminals:
```sh
npm run dev:api
npm run dev:worker
npm run dev:web
```
Open `http://localhost:3000/analyze/pr` and submit the fixture PR:
```text
https://github.com/repopilot-labs/demo-repo/pull/42
```
## Environment
The checked-in `.env.example` contains the values needed for local development:
```sh
NODE_ENV=development
DATABASE_URL=postgresql://repopilot:repopilot@localhost:5432/repopilot
REDIS_URL=redis://localhost:6379
API_HOST=0.0.0.0
PORT=4000
NEXT_PUBLIC_API_BASE_URL=http://localhost:4000
REPOPILOT_MCP_SERVER_COMMAND=node
REPOPILOT_MCP_SERVER_ARGS=["apps/mcp-server/dist/index.js"]
```
The real `.env` file is intentionally ignored. Keep GitHub App secrets, private key paths, and local credentials there only.
## GitHub App Mode
Without GitHub App configuration, the MCP server uses fixture-backed PR data so the workflow can run offline. To read real pull request metadata and changed files, create a GitHub App, install it on a test repository, and set these values in `.env`:
```sh
GITHUB_APP_ID=
GITHUB_APP_SLUG=
GITHUB_APP_CLIENT_ID=
GITHUB_APP_CLIENT_SECRET=
GITHUB_APP_PRIVATE_KEY_PATH=
GITHUB_TEST_OWNER=
GITHUB_TEST_REPO=
GITHUB_TEST_PR_NUMBER=
```
When this config is present, RepoPilot uses short-lived installation tokens for read-only PR access.
## Useful Scripts
```sh
npm run dev:web # Next.js frontend on port 3000
npm run dev:api # Fastify API on port 4000
npm run dev:worker # Queue worker
npm run dev:mcp-server # MCP server over stdio
npm run typecheck # TypeScript checks
npm run lint # TypeScript lint-style checks
npm test # Vitest suite
npm run build # TypeScript build plus web build
```
## Verification
Run the main checks before publishing changes:
```sh
npm run typecheck
npm run lint
npm test
npm run build
DATABASE_URL=postgresql://repopilot:repopilot@localhost:5432/repopilot npx prisma validate
```
Docker is required for the full database-backed workflow. The static checks and many route/unit tests can still run without Postgres or Redis.
## Current Scope
RepoPilot currently focuses on the pull request analysis slice. Full GitHub OAuth login, hosted deployment, model-backed reasoning, approval workflows, issue triage, CI log analysis, and comment posting are intentionally outside the current implementation.
