# MCP GitHub Project Manager

<!-- Keywords: mcp server, model context protocol, github project management, ai agent orchestration, multi-agent coordination, autonomous coding agents, prd generator, sprint planning ai, issue triage automation, github projects v2 api, claude mcp, codex mcp, cursor mcp, llm tools, agentic task management, ai project manager, swarm coordination, github actions, github releases, branch protection, mcp resources, mcp prompts -->

**The agentic task substrate for AI coding agents.** An MCP server that turns GitHub Projects v2 into a fully autonomous project management platform — AI agents self-assign work, track progress, review each other, and ship code, all backed by GitHub-native storage.

> **Use case**: You have AI agents (Claude Code, Codex, Cursor, Windsurf, Roo). They need a task backbone. This is it.

[![npm version](https://img.shields.io/npm/v/mcp-github-project-manager.svg)](https://www.npmjs.com/package/mcp-github-project-manager)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/node/v/mcp-github-project-manager.svg)](https://nodejs.org/)

## Overview

This MCP server implements the [Model Context Protocol](https://modelcontextprotocol.io) to provide a complete **agentic project management layer** over GitHub Projects v2. AI agents register, self-assign tasks, coordinate via heartbeats, submit work products for review, and operate within token budgets — all through 20 compound tools exposing 169 actions. Human project managers get AI-powered PRD generation, sprint planning, issue triage, and roadmap creation. Everything is backed by GitHub-native storage (issues, project fields, comments) — no external infrastructure required.

## Why This Exists

AI coding agents are powerful but stateless — they don't know what to work on next, can't coordinate with other agents, and have no persistent task memory. This MCP server solves that by turning GitHub Projects into an **agentic operating layer**:

| Problem | Solution |
|---------|----------|
| Agents don't know what to work on | **Task checkout** with priority/skills/deadline strategies |
| Multiple agents step on each other | **Atomic claims** with TOCTOU guards + review workflow |
| No visibility into agent work | **Heartbeat monitoring** + activity dashboard + work product tracking |
| Agents burn unlimited tokens | **Per-agent token budgets** with warning thresholds and hard stops |
| Ideas don't become tasks | **PRD→Tasks→Issues pipeline** with AI-powered breakdown |
| Sprint planning is manual | **AI sprint planning** with capacity analysis and risk assessment |
| Issues pile up untriaged | **AI-powered triage** with auto-labeling and priority assignment |
| Need external databases | **Zero infra** — all state in GitHub issues, projects, and comments |

## Works With

| Agent / Client | Integration |
|---------------|-------------|
| **Claude Desktop** | Native MCP client — add to `claude_desktop_config.json` |
| **Claude Code** | MCP server via stdio transport |
| **Codex** | MCP-compatible — register as tool provider |
| **Cursor** | MCP server integration |
| **Windsurf** | MCP server integration |
| **Roo Code** | MCP server integration |
| **VS Code + Copilot** | Via MCP extension |
| **Custom harnesses** | Any MCP-compatible client — see `examples/basic/agent-loop.ts` |
| **Oh My Pi / OpenCode** | Native MCP harness with stdio transport |

### MCP v2 Protocol Support

Beyond tools, this server implements the full MCP v2 capability surface:

| Capability | Count | Examples |
|------------|-------|----------|
| **Tools** | 20 compound (169 actions) | manage_project, ai_generate, agent_work |
| **Resources** | 6 | github://projects, github://agents, github://config |
| **Prompts** | 6 | review-prd, triage-issue, analyze-sprint-risk |
| **Sampling** | ✓ | Client-side LLM for AI features when no API keys |

### What Makes This Special

- **Agentic-First Design**: Built as a task substrate for AI agents, not a human-facing PM tool retrofitted with an API
- **20 Compound Tools (169 actions)**: Progressive-disclosure API — agents see 20 tools, drill into 169 actions via `discover_tools`
- **Multi-Agent Swarm**: Agents register, claim tasks atomically, heartbeat, review each other, and converge projects
- **PRD→Production Pipeline**: Idea → PRD → tasks → GitHub issues → milestones → sprints — fully automated
- **Zero External Infrastructure**: All state lives in GitHub (issues, projects, comments) — no database, no Redis, no S3
- **AI-Powered Everything**: Triage, sprint planning, roadmap generation, complexity analysis, duplicate detection — all AI-augmented
- **Token Budget Enforcement**: Per-agent spending limits prevent runaway AI costs
- **Self-Healing**: Auto-reclaim tasks from crashed agents, stale heartbeat detection, registry cleanup

## Table of Contents

- [Overview](#overview)
- [Quick Start](#quick-start)
- [Key Features](#key-features)
- [Installation](#installation)
- [Configuration](#configuration)
- [Usage](#usage)
  - [As a command-line tool](#as-a-command-line-tool)
  - [Running from source with TypeScript](#running-from-source-with-typescript)
  - [As a Node.js module](#as-a-nodejs-module)
  - [Integration with MCP clients](#integration-with-mcp-clients)
  - [Installing in AI Assistants](#installing-in-ai-assistants)
    - [Claude](#install-in-claude)
    - [Roocode](#install-in-roocode)
    - [Windsurf](#install-in-windsurf)
    - [VS Code](#install-in-vs-code)
    - [Cursor](#install-in-cursor)
    - [Using Docker](#using-docker)
  - [Troubleshooting](#troubleshooting)
- [Agent Orchestration](#agent-orchestration)
- [Architecture](#architecture)
- [Contributing](#contributing)
- [License](#license)
- [References](#references)
- [Current Status](#current-status)

## Quick Start

### Using NPM
```bash
# Install the package globally
npm install -g mcp-github-project-manager

# Set up your environment variables
export GITHUB_TOKEN="your_github_token"
export GITHUB_OWNER="your_github_username_or_organization"
export GITHUB_REPO="your_repository_name"

# Run the MCP server
mcp-github-project-manager
```

### Using Docker
```bash
# Build the Docker image
docker build -t mcp-github-project-manager .

# Run with environment variables
docker run -it \
  -e GITHUB_TOKEN=your_github_token \
  -e GITHUB_OWNER=your_github_username_or_organization \
  -e GITHUB_REPO=your_repository_name \
  mcp-github-project-manager
```

## Key Features

### 🤖 AI-Powered Task Management
- **PRD Generation** (`generate_prd`): Transform project ideas into comprehensive Product Requirements Documents
- **Intelligent Task Breakdown** (`parse_prd`): AI-powered parsing of PRDs into actionable development tasks
- **Smart Feature Addition** (`add_feature`): Add new features with automatic impact analysis and task generation
- **Task Complexity Analysis** (`analyze_task_complexity`): Detailed AI analysis of task complexity, effort estimation, and risk assessment
- **Next Task Recommendations** (`get_next_task`): AI-powered recommendations for optimal task prioritization
- **Task Expansion** (`expand_task`): Break down complex tasks into manageable subtasks automatically
- **PRD Enhancement** (`enhance_prd`): Improve existing PRDs with AI-powered gap analysis and improvements
- **Task Materialization** (`materialize_tasks`): Convert generated tasks into real GitHub issues grouped into milestones and sprints with dependency-driven phase ordering

### 🎯 Enhanced Task Context Generation
- **Traceability-Based Context** (Default): Rich context from requirements traceability without AI dependency
- **AI-Enhanced Context** (Optional): Comprehensive business, technical, and implementation context using AI
- **Configurable Context Levels**: Choose between minimal, standard, and full context depth
- **Business Context**: Extract business objectives, user impact, and success metrics
- **Technical Context**: Analyze technical constraints, architecture decisions, and integration points
- **Implementation Guidance**: AI-generated step-by-step implementation recommendations
- **Contextual References**: Links to relevant PRD sections, features, and technical specifications
- **Enhanced Acceptance Criteria**: Detailed, testable criteria with verification methods
- **Graceful Degradation**: Works perfectly without AI keys, falls back to traceability-based context

### 🔗 Complete Requirements Traceability
- **End-to-End Tracking** (`create_traceability_matrix`): Full traceability from PRD business requirements → features → use cases → tasks
- **Bidirectional Links**: Complete bidirectional traceability with impact analysis
- **Use Case Management**: Professional actor-goal-scenario use case generation and tracking
- **Coverage Analysis**: Comprehensive coverage metrics with gap identification
- **Orphaned Task Detection**: Identify tasks without requirements links
- **Change Impact Analysis**: Track requirement changes and their impact across all levels

### 📊 Multi-Provider AI Support
- **Anthropic Claude**: Primary AI provider for complex reasoning
- **OpenAI GPT**: Alternative provider with fallback support
- **Google Gemini**: Additional AI capabilities
- **Perplexity**: Research and analysis tasks
- **Automatic Fallback**: Seamless switching between providers

### 🏗️ Core Project Management
- **Project Management**: Create and manage GitHub Projects (v2)
- **Issues and Milestones**: Full CRUD operations with advanced filtering
- **Sprint Planning**: Plan and manage development sprints with AI assistance
- **Custom Fields and Views**: Create different views (board, table, timeline, roadmap)
- **Resource Versioning**: Intelligent caching and optimistic locking

### ⚡ Advanced Features
- **MCP Implementation**: Full MCP specification compliance with Zod validation
- **GitHub Integration**: GraphQL API integration with intelligent rate limiting
- **Real-time Sync**: Bidirectional synchronization with GitHub
- **Webhook Integration**: Real-time updates via GitHub webhooks
- **Progress Tracking**: Comprehensive metrics and progress reporting
- **Event System**: Track and replay project events

### 🔧 GitHub API Coverage
- **GitHub Actions**: List workflows, trigger dispatches, monitor runs, download logs, cancel runs
- **Releases**: Create, update, delete releases with auto-generated notes
- **Branch Protection**: Get, update, delete branch protection rules; list branches
- **Projects v2**: Full field/view/item management, templates, linking
- **Issues & PRs**: CRUD, comments, sub-issues, advanced search, draft issues
- **Milestones & Sprints**: Planning, metrics, velocity tracking

### Agent Orchestration
- **Compound Tool API**: 20 tools with `action` routing replace 169 individual actions — simpler for AI agents
- **Agent Registry**: Register, list, and deregister autonomous AI agents
- **Task Checkout**: Claim tasks with configurable selection strategies (priority, age, skills, deadline)
- **Heartbeat Monitoring**: Periodic liveness and progress reporting with stale-agent detection
- **Work Product Tracking**: Submit code changes, PRs, test results, and review artifacts
- **Work Product Validation**: Reviewers inspect work against acceptance criteria — not rubber stamps
- **Budget Enforcement**: Per-agent token budgets with warning thresholds and hard stops
- **Activity Dashboard**: Real-time view of all agent statuses, tasks, and budget consumption
- **Subagent Hierarchy**: Parent-child agent relationships with cascade deregistration
- **Runtime Discovery**: `discover_tools` meta-tool for exploring available actions and schemas
- **PM Coordination**: Project managers can assign specific tasks, monitor swarm status, and rebalance workloads
- **Failure Recovery**: PM decomposes rejected tasks into subtasks, re-assigns to agents
- **Smart Task Routing**: Capability-matched, budget-aware assignment (`smart_assign`)
- **Project Convergence**: Auto-approve/reject/decompose in one call (`converge_project`)
- **Registry Cleanup**: Remove stale agents automatically
- **Task Materialization**: Bridge from PRD tasks to GitHub issues with milestones, sprints, and project assignment

## Installation

### Option 1: Install from npm (recommended)

```bash
# Install the package globally
npm install -g mcp-github-project-manager

# Or install in your project
npm install mcp-github-project-manager
```

### Option 2: Install from source

```bash
# Clone the repository
git clone https://github.com/kunwarVivek/mcp-github-project-manager.git
cd mcp-github-project-manager

# Install dependencies
npm install
# or
pnpm install

# Build the project
npm run build
```

### Set up environment variables

```bash
# Copy the example environment file
cp .env.example .env

# Edit .env with your GitHub token and details
```

## Configuration

### Required Environment Variables

#### GitHub Configuration
```env
GITHUB_TOKEN=your_github_token
GITHUB_OWNER=repository_owner
GITHUB_REPO=repository_name
```

The GitHub token requires these permissions:
- `repo` (Full repository access)
- `project` (Project access)
- `write:org` (Organization access)

#### AI Provider Configuration
AI keys are **optional** — without them, non-AI tools (project management, issues, sprints, agents) work fine. AI-powered features (`ai_generate`, `ai_analyze`, `ai_plan`) need at least one key.

```env
# Global AI provider keys (set the ones you have)
ANTHROPIC_API_KEY=your_anthropic_api_key_here
OPENAI_API_KEY=your_openai_api_key_here
GOOGLE_API_KEY=your_google_api_key_here
PERPLEXITY_API_KEY=your_perplexity_api_key_here

# AI Model Configuration (no defaults — configure what you want to use)
AI_MAIN_MODEL=claude-sonnet-4-20250514    # general tasks
AI_PRD_MODEL=claude-opus-5                # PRD generation
AI_RESEARCH_MODEL=sonar-pro               # research
AI_FALLBACK_MODEL=gpt-4o-mini             # fallback
```

#### Per-Role Provider Configuration (optional)
Each model role can independently use a different provider, API key, and endpoint.
Use `openai-compatible` for OpenRouter, Together, Groq, Ollama, or any OpenAI-protocol endpoint:

```env
# OpenRouter for cheap daily tasks
AI_MAIN_PROVIDER=openai-compatible
AI_MAIN_BASE_URL=https://openrouter.ai/api/v1
AI_MAIN_API_KEY=sk-or-v1-your-key
AI_MAIN_MODEL=deepseek/deepseek-chat

# Direct Anthropic for PRD generation
AI_PRD_PROVIDER=anthropic
AI_PRD_API_KEY=sk-ant-your-key
AI_PRD_MODEL=claude-opus-5

# Local Ollama as fallback
AI_FALLBACK_PROVIDER=openai-compatible
AI_FALLBACK_BASE_URL=http://localhost:11434/v1
AI_FALLBACK_API_KEY=ollama
AI_FALLBACK_MODEL=llama3.1
```

See the [Configuration Guide](docs/CONFIGURATION.md) for full per-role documentation.


### AI Provider Setup

#### Anthropic Claude
1. Sign up at [Anthropic Console](https://console.anthropic.com/)
2. Create an API key
3. Set `ANTHROPIC_API_KEY` in your environment

#### OpenAI
1. Sign up at [OpenAI Platform](https://platform.openai.com/)
2. Create an API key
3. Set `OPENAI_API_KEY` in your environment

#### Google Gemini
1. Sign up at [Google AI Studio](https://aistudio.google.com/)
2. Create an API key
3. Set `GOOGLE_API_KEY` in your environment

#### Perplexity
1. Sign up at [Perplexity API](https://www.perplexity.ai/settings/api)
2. Create an API key
3. Set `PERPLEXITY_API_KEY` in your environment

## Usage

### As a command-line tool

If installed globally:

```bash
# Start the MCP server using stdio transport
mcp-github-project-manager

# Start with environment variables
GITHUB_TOKEN=your_token mcp-github-project-manager

# Start with command line arguments
mcp-github-project-manager --token=your_token --owner=your_username --repo=your_repo

# Use a specific .env file
mcp-github-project-manager --env-file=.env.production

# Show verbose output
mcp-github-project-manager --verbose

# Display help information
mcp-github-project-manager --help
```

### Running from source with TypeScript

If you're developing or running from source:

```bash
# Use the npm dev script (watches for changes) — recommended
npm run dev

# Run directly with tsx
npx tsx src/index.ts

# Run with command line arguments
npx tsx src/index.ts --token=your_token --owner=your_username --repo=your_repo

# Display help information
npx tsx src/index.ts --help
```

#### Command Line Options

| Option | Short | Description |
|--------|-------|-------------|
| `--token <token>` | `-t` | GitHub personal access token |
| `--owner <owner>` | `-o` | GitHub repository owner (username or organization) |
| `--repo <repo>` | `-r` | GitHub repository name |
| `--env-file <path>` | `-e` | Path to .env file (default: .env in project root) |
| `--verbose` | `-v` | Enable verbose logging |
| `--help` | `-h` | Display help information |
| `--version` | | Display version information |

Command line arguments take precedence over environment variables.

### As a Node.js module

```javascript
import { Server } from "mcp-github-project-manager";

// Create and start an MCP server instance
const server = new Server({
  transport: "stdio", // or "http" for HTTP server
  config: {
    githubToken: process.env.GITHUB_TOKEN,
    githubOwner: process.env.GITHUB_OWNER,
    githubRepo: process.env.GITHUB_REPO
  }
});

server.start();
```

### Integration with MCP clients

```javascript
// Example using an MCP client library
import { McpClient } from "@modelcontextprotocol/client";
import { spawn } from "child_process";

// Create a child process running the MCP server
const serverProcess = spawn("mcp-github-project-manager", [], {
  env: { ...process.env, GITHUB_TOKEN: "your_token" }
});

// Connect the MCP client to the server
const client = new McpClient({
  transport: {
    type: "process",
    process: serverProcess
  }
});

// Call MCP tools (compound API)
const result = await client.callTool("manage_project", {
  action: "create",
  title: "My Project",
  owner: "myorg"
});
```

For more examples, see the [User Guide](docs/user-guide.md) and the [examples/](examples/) directory.

### Compound Tool API Examples

The MCP server exposes 20 compound tools (169 actions). Each tool accepts an `action` parameter that routes to the underlying operation. Use `discover_tools` to explore capabilities at runtime.

#### Quick Start Workflow
```json
// 1. Create a project
{"tool": "manage_project", "arguments": {"action": "create", "title": "My Project", "owner": "myorg"}}

// 2. Create an issue
{"tool": "manage_issues", "arguments": {"action": "create", "title": "First Issue", "body": "Description here"}}

// 3. Register an AI agent
{"tool": "agent_work", "arguments": {"action": "register", "name": "claude-eng-1", "role": "engineer"}}

// 4. Agent checks out a task
{"tool": "agent_work", "arguments": {"action": "checkout_task", "agentId": "agent-abc123", "strategy": "highest_priority"}}

// 5. Discover available tools at runtime
{"tool": "discover_tools", "arguments": {}}
{"tool": "discover_tools", "arguments": {"group": "manage_issues", "action": "create", "includeSchemas": true}}
```

#### AI-Powered Project Workflow
```json
// 1. Generate PRD from project idea
{"tool": "ai_generate", "arguments": {"action": "generate_prd", "projectIdea": "AI-powered task management with real-time collaboration", "projectName": "TaskAI Pro", "complexity": "high"}}

// 2. Parse PRD into tasks with traceability
{"tool": "ai_generate", "arguments": {"action": "parse_prd", "prdContent": "<generated PRD>", "maxTasks": 30, "createTraceabilityMatrix": true}}

// 3. Get next task recommendations
{"tool": "ai_generate", "arguments": {"action": "get_next_task", "sprintCapacity": 40, "teamSkills": ["react", "node.js", "typescript"]}}

// 4. Analyze task complexity
{"tool": "ai_generate", "arguments": {"action": "analyze_complexity", "taskTitle": "Implement real-time collaboration", "includeRisks": true}}

// 5. Break down complex tasks
{"tool": "ai_generate", "arguments": {"action": "expand_tas