MCP GitHub Project Manager

MCP GitHub Project Manager

面向 AI 编码 Agent 的 Agentic 任务底座。 一个 MCP 服务，可将 GitHub Projects v2 转变为完全自主的项目管理平台——AI Agent 自主认领工作、跟踪进度、相互审查并交付代码，所有数据均由 GitHub 原生存储提供支持。

使用场景：你有 AI Agent（Claude Code、Codex、Cursor、Windsurf、Roo）。它们需要一个任务支撑系统。就是它。

概述

此 MCP 服务实现了 Model Context Protocol，为 GitHub Projects v2 提供完整的Agentic 项目管理层。AI Agent 可注册、自主认领任务、通过心跳协调、提交工作成果以供审查，并在令牌预算内运行——这一切都通过 20 个组合工具提供的 169 项操作完成。项目经理可借助 AI 生成 PRD、规划冲刺、整理问题并创建路线图。所有数据均由 GitHub 原生存储（问题、项目字段、评论）提供支持——无需外部基础设施。

为什么要开发它

AI 编码 Agent 功能强大，却没有状态——它们不知道接下来要做什么，无法与其他 Agent 协调，也没有持久化的任务记忆。此 MCP 服务通过将 GitHub Projects 转变为Agentic 运营层来解决这一问题：

问题	解决方案
Agent 不知道接下来要做什么	采用优先级、技能和截止日期策略的任务签出
多个 Agent 相互干扰	带 TOCTOU 防护和审查工作流的原子认领
无法了解 Agent 的工作情况	心跳监控 + 活动仪表板 + 工作成果跟踪
Agent 消耗无限令牌	每个 Agent 的令牌预算，设有警告阈值和硬性限制
想法无法转化为任务	带 AI 驱动拆解的 PRD→任务→问题流程
冲刺规划需要手动完成	带容量分析和风险评估的 AI 冲刺规划
问题堆积且无人整理	带自动添加标签和分配优先级的 AI 驱动问题整理
需要外部数据库	零基础设施——所有状态都存储在 GitHub 问题、项目和评论中

兼容对象

Agent / 客户端	集成方式
Claude Desktop	原生 MCP 客户端——添加到 claude_desktop_config.json
Claude Code	通过 stdio 传输的 MCP 服务
Codex	兼容 MCP——注册为工具提供方
Cursor	MCP 服务集成
Windsurf	MCP 服务集成
Roo Code	MCP 服务集成
VS Code + Copilot	通过 MCP 扩展
自定义运行框架	任何兼容 MCP 的客户端——参见 examples/basic/agent-loop.ts
Oh My Pi / OpenCode	采用 stdio 传输的原生 MCP 运行框架

MCP v2 协议支持

除了工具，此服务还实现了完整的 MCP v2 能力集：

能力	数量	示例
工具	20 个组合工具（169 项操作）	manage_project、ai_generate、agent_work
资源	6	github://projects、github://agents、github://config
提示词	6	review-prd、triage-issue、analyze-sprint-risk
采样	✓	当没有 API 密钥时，使用客户端侧大模型实现 AI 功能

特别之处

• Agent 优先设计：构建为 AI Agent 的任务基础层，而非事后添加 API 的面向人工的项目管理工具
• 20 个复合工具（169 项操作）：渐进式披露 API——Agent 可看到 20 个工具，并通过 discover_tools 深入使用 169 项操作
• 多 Agent 群组：Agent 注册、原子化认领任务、发送心跳、互相评审，并推动项目达成一致
• 从 PRD 到生产的流程：创意 → PRD → 任务 → GitHub issue → 里程碑 → 冲刺——全自动化
• 无需外部基础设施：所有状态都存储在 GitHub（issue、项目、评论）中——无需数据库、Redis 或 S3
• AI 驱动一切：分诊、冲刺规划、路线图生成、复杂度分析、重复项检测——全部由 AI 增强
• 令牌预算强制机制：按 Agent 设置支出上限，避免 AI 成本失控
• 自我修复：自动回收崩溃 Agent 的任务、检测过期心跳、清理注册表

目录

• 概述
• 快速开始
• 主要功能
• 安装
• 配置
• 使用方法
  • 作为命令行工具
  • 使用 TypeScript 从源代码运行
  • 作为 Node.js 模块
  • 与 MCP 客户端集成
  • 在 AI 助手中安装
    • Claude
    • Roocode
    • Windsurf
    • VS Code
    • Cursor
    • 使用 Docker
  • 故障排除
• Agent 编排
• 架构
• 贡献
• 许可证
• 参考资料
• 当前状态

快速开始

使用 NPM

# 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

使用 Docker

# 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

主要功能

🤖 AI 驱动的任务管理

• PRD 生成（generate_prd）：将项目创意转化为完整的产品需求文档
• 智能任务拆分（parse_prd）：使用 AI 将 PRD 解析为可执行的开发任务
• 智能添加功能（add_feature）：添加新功能，并自动进行影响分析和任务生成
• 任务复杂度分析（analyze_task_complexity）：使用 AI 详细分析任务复杂度、估算工作量并评估风险
• 后续任务推荐（get_next_task）：使用 AI 推荐最佳任务优先级
• 任务扩展（expand_task）：自动将复杂任务拆解为易于管理的子任务
• PRD 增强（enhance_prd）：通过 AI 驱动的差距分析和改进来优化现有 PRD
• 任务实体化（materialize_tasks）：将生成的任务转换为实际的 GitHub issue，并按里程碑和冲刺分组，同时根据依赖关系安排阶段顺序

🎯 增强型任务上下文生成

• 基于可追溯性的上下文（默认）：从需求可追溯性中获取丰富上下文，无需依赖 AI
• AI 增强上下文（可选）：使用 AI 提供全面的业务、技术和实现上下文
• 可配置的上下文级别：可选择精简、标准或完整的上下文深度
• 业务上下文：提取业务目标、用户影响和成功指标
• 技术上下文：分析技术限制、架构决策和集成点
• 实现指导：由 AI 生成逐步实现建议
• 上下文参考：链接到相关的 PRD 章节、功能和技术规范
• 增强验收标准：提供详细、可测试的标准及验证方法
• 优雅降级：无需 AI 密钥也能正常运行，并回退到基于可追溯性的上下文

🔗 完整需求可追溯性

• 端到端跟踪（create_traceability_matrix）：从 PRD 业务需求 → 功能 → 用例 → 任务的完整可追溯性
• 双向链接：完整的双向可追溯性与影响分析
• 用例管理：专业的参与者-目标-场景用例生成与跟踪
• 覆盖率分析：全面的覆盖率指标与差距识别
• 孤立任务检测：识别没有需求链接的任务
• 变更影响分析：跟踪需求变更及其在各层级的影响

📊 多提供商 AI 支持

• Anthropic Claude：用于复杂推理的主要 AI 提供商
• OpenAI GPT：支持回退的备用提供商
• Google Gemini：提供额外的 AI 能力
• Perplexity：用于研究与分析任务
• 自动回退：在提供商之间无缝切换

🏗️ 核心项目管理

• 项目管理：创建和管理 GitHub Projects（v2）
• 议题与里程碑：支持高级筛选的完整 CRUD 操作
• 迭代规划：借助 AI 规划和管理开发迭代
• 自定义字段和视图：创建不同视图（看板、表格、时间线、路线图）
• 资源版本控制：智能缓存与乐观锁定

⚡ 高级功能

• MCP 实现：全面符合 MCP 规范，并使用 Zod 进行验证
• GitHub 集成：集成 GraphQL API，并进行智能速率限制
• 实时同步：与 GitHub 双向同步
• Webhook 集成：通过 GitHub Webhook 实时更新
• 进度跟踪：全面的指标与进度报告
• 事件系统：跟踪并重放项目事件

🔧 GitHub API 覆盖范围

• GitHub Actions：列出工作流、触发调度、监控运行、下载日志、取消运行
• 发布版本：创建、更新、删除发布版本，并自动生成说明
• 分支保护：获取、更新、删除分支保护规则；列出分支
• Projects v2：全面管理字段、视图和项目条目，支持模板与关联
• 议题和 PR：CRUD、评论、子议题、高级搜索、草稿议题
• 里程碑和迭代：规划、指标、速率跟踪

Agent 编排

• 复合工具 API：使用带 action 路由的 20 个工具，取代 169 个独立操作，让 AI Agent 更易使用
• Agent 注册表：注册、列出和注销自主 AI Agent
• 任务领取：根据可配置的选择策略（优先级、时长、技能、截止时间）领取任务
• 心跳监控：定期报告存活状态和进度，并检测失联 Agent
• 工作成果跟踪：提交代码变更、PR、测试结果和评审材料
• 工作成果验证：评审者根据验收标准检查成果，而非走过场
• 预算执行：为每个 Agent 设置令牌预算，支持警告阈值和硬性上限
• 活动仪表板：实时查看所有 Agent 的状态、任务和预算消耗
• 子 Agent 层级：支持父子 Agent 关系，并可级联注销
• 运行时发现：通过 discover_tools 元工具探索可用操作和架构
• 项目管理协调：项目经理可以分配特定任务、监控 Agent 集群状态并重新平衡工作负载
• 故障恢复：项目经理将被拒绝的任务分解为子任务，并重新分配给 Agent
• 智能任务路由：根据能力匹配并考虑预算进行分配（smart_assign）
• 项目收敛：通过一次调用自动批准、拒绝或分解任务（converge_project）
• 注册表清理：自动移除失联 Agent
• 任务实例化：将 PRD 任务转化为 GitHub 议题，并关联里程碑、迭代和项目

安装

选项 1：从 npm 安装（推荐）

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

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

选项 2：从源代码安装

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

# Install dependencies (npm or pnpm - use whichever you have)
pnpm install

# Build the project
pnpm run build

设置环境变量

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

# Edit .env with your GitHub token and details

配置

必需的环境变量

GitHub 配置

GITHUB_TOKEN=your_github_token
GITHUB_OWNER=repository_owner
GITHUB_REPO=repository_name

GitHub 令牌需要以下权限：

• repo（完整的仓库访问权限）
• project（项目访问权限）
• write:org（组织访问权限）

AI 提供商配置

AI 密钥可选——没有密钥时，非 AI 工具（项目管理、议题、冲刺、Agent）仍可正常使用。AI 驱动的功能（ai_generate、ai_analyze、ai_plan）至少需要一个密钥。

# 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

按角色配置提供商（可选）

每个模型角色都可以独立使用不同的提供商、API 密钥和端点。 对于 OpenRouter、Together、Groq、Ollama 或任何 OpenAI 协议端点，请使用 openai-compatible：

# 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

有关按角色配置的完整文档，请参阅配置指南。

AI 提供商设置

Anthropic Claude

1. 在 Anthropic Console 注册
2. 创建 API 密钥
3. 在环境中设置 ANTHROPIC_API_KEY

OpenAI

1. 在 OpenAI Platform 注册
2. 创建 API 密钥
3. 在环境中设置 OPENAI_API_KEY

Google Gemini

1. 在 Google AI Studio 注册
2. 创建 API 密钥
3. 在环境中设置 GOOGLE_API_KEY

Perplexity

1. 在 Perplexity API 注册
2. 创建 API 密钥
3. 在环境中设置 PERPLEXITY_API_KEY

使用方法

作为命令行工具

如果已全局安装：

# 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

使用 TypeScript 从源代码运行

如果你正在开发或从源代码运行：

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

# Run directly with tsx
pnpm exec tsx src/index.ts

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

# Display help information
pnpm exec tsx src/index.ts --help

命令行选项

选项	简写	描述
--token <token>	-t	GitHub 个人访问令牌
--owner <owner>	-o	GitHub 仓库所有者（用户名或组织）
--repo <repo>	-r	GitHub 仓库名称
--env-file <path>	-e	.env 文件路径（默认：项目根目录中的 .env）
--verbose	-v	启用详细日志记录
--help	-h	显示帮助信息
--version		显示版本信息

命令行参数的优先级高于环境变量。

作为 Node.js 模块

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();

集成 MCP 客户端

// 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"
});

更多示例请参阅用户指南和 examples/ 目录。

复合工具 API 示例

MCP 服务提供 20 个复合工具（169 项操作）。每个工具都接受一个 action 参数，用于路由到底层操作。使用 discover_tools 可在运行时探索功能。

快速入门工作流

// 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 驱动的项目工作流

// 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_task", "taskTitle": "Build analytics dashboard", "currentComplexity": 8, "targetComplexity": 3}}

功能添加工作流

// Add new feature with complete lifecycle
{"tool": "ai_generate", "arguments": {"action": "add_feature", "featureIdea": "Advanced Analytics Dashboard", "description": "Real-time analytics with AI insights", "expandToTasks": true}}
// Automatically creates: business requirements, use cases, tasks with traceability, lifecycle tracking

// Create traceability matrix
{"tool": "ai_generate", "arguments": {"action": "create_traceability_matrix", "projectId": "task-ai-pro", "validateCompleteness": true}}

工具发现

// List all compound tools
{"tool": "discover_tools", "arguments": {}}

// Explore a specific tool's actions
{"tool": "discover_tools", "arguments": {"group": "ai_generate"}}

// Get full schema for a specific action
{"tool": "discover_tools", "arguments": {"group": "ai_generate", "action": "generate_prd", "includeSchemas": true}}

MCP_TOOL_GROUPS 配置

控制向 MCP 客户端公开哪些复合工具：

# Default: all tools exposed
MCP_TOOL_GROUPS=all

# Expose only project management tools
MCP_TOOL_GROUPS=core

# Add AI tools
MCP_TOOL_GROUPS=core,ai

无论此设置如何，discover_tools 始终可用。

上下文生成级别：

• 最小：仅包含基本可追溯性上下文（速度最快）
• 标准：可追溯性 + 基本业务上下文（默认）
• 完整：包含实现指导的完整 AI 增强上下文

🧪 测试增强型上下文生成

增强型上下文生成功能包含全面的测试覆盖：

创建的测试文件：

• src/__tests__/TaskContextGenerationService.test.ts - 核心上下文生成服务测试
• src/__tests__/TaskGenerationService.enhanced.test.ts - 增强型任务生成集成测试
• src/__tests__/ParsePRDTool.enhanced.test.ts - 工具级上下文生成测试

测试覆盖范围：

• 基于可追溯性的上下文生成（默认行为）
• AI 增强型上下文生成（AI 可用时）
• AI 服务不可用时的优雅回退
• 配置验证和环境变量处理
• 错误处理和韧性测试
• 与现有任务生成流程的集成测试

运行上下文生成测试：

# Run all AI-related tests (includes context generation)
pnpm run test:ai

# Run specific context generation tests
pnpm test TaskContextGeneration
pnpm test enhanced

# Run all tests
pnpm test

🧪 全面的端到端测试套件

MCP GitHub Project Manager 包含全面的端到端测试套件，可通过实际的 MCP 接口，使用模拟 API 调用和真实 API 调用测试所有 MCP 工具。

测试覆盖范围：

• ✅ 20 个复合工具（169 项操作） - 完整的项目、里程碑、问题、冲刺、标签等 CRUD 操作
• ✅ 9 项 AI 驱动的操作 - PRD 生成、任务解析、复杂度分析、功能管理和可追溯性
• ✅ 复杂工作流集成 - 多工具工作流和真实项目管理场景
• ✅ 真实 API 测试 - 可选的 GitHub 和 AI API 实际测试
• ✅ 架构验证 - 对所有工具进行全面的参数验证
• ✅ 错误处理 - 对错误处理和恢复进行测试，确保处理过程平稳

快速开始：

# Run comprehensive E2E tests (mocked APIs)
pnpm run test:e2e:tools

# Run with real APIs (requires credentials)
pnpm run test:e2e:tools:real

# Use the interactive test runner
pnpm run test:e2e:runner

# Run specific test categories
pnpm run test:e2e:tools:github     # GitHub tools only
pnpm run test:e2e:tools:ai         # AI tools only
pnpm run test:e2e:tools:workflows  # Integration workflows

测试运行器选项：

# Interactive test runner with options
node scripts/run-e2e-tests.js --help

# Examples:
node scripts/run-e2e-tests.js --real-api --github-only
node scripts/run-e2e-tests.js --build --verbose --timeout 120
node scripts/run-e2e-tests.js --ai-only --real-api

真实 API 测试的环境配置：

GitHub API（GitHub 工具必需）：

GITHUB_TOKEN=ghp_your_github_token
GITHUB_OWNER=your-github-username
GITHUB_REPO=your-test-repository

AI API（AI 工具必需）：

# At least one AI API key required
ANTHROPIC_API_KEY=sk-ant-your-anthropic-key
OPENAI_API_KEY=sk-your-openai-key
GOOGLE_API_KEY=your-google-ai-key
PERPLEXITY_API_KEY=pplx-your-perplexity-key

启用真实 API 测试：

E2E_REAL_API=true pnpm run test:e2e:tools:real

测试功能：

• 工具注册验证 - 确认所有工具均已使用正确的架构完成注册
• MCP 协议合规性 - 确保所有工具遵循 MCP 规范
• 响应格式验证 - 验证工具响应是否符合预期格式
• 工作流集成测试 - 测试复杂的多工具工作流
• 凭据管理 - 平稳处理缺失的凭据
• 性能监控 - 跟踪工具执行性能
• 全面的错误测试 - 验证错误处理和恢复

文档：

• 📖 全面的端到端测试指南 - 详细的测试文档
• 🔧 测试配置 - 用于端到端测试的 Jest 配置
• 🛠️ 测试工具 - 可重用的测试工具

端到端测试套件可确保所有 MCP 工具单独使用和在复杂工作流中均能正常工作，让您确信整个系统可靠且集成良好。

涵盖的测试场景：

• ✅ 基于可追溯性的默认上下文（无需 AI）
• ✅ AI 增强的业务上下文生成
• ✅ AI 增强的技术上下文生成
• ✅ 实现指导生成
• ✅ 上下文合并与冲突解决
• ✅ 错误处理与优雅降级
• ✅ 配置验证与默认值
• ✅ 工具级参数验证
• ✅ 与现有可追溯性系统集成

在 AI 助手中安装

在 Claude 中安装

在 Claude Desktop 中安装 MCP 服务：

{
  "mcpServers": {
    "github-project-manager": {
      "command": "npx",
      "args": ["-y", "mcp-github-project-manager"],
      "env": {
        "GITHUB_TOKEN": "your_github_token",
        "GITHUB_OWNER": "your_username",
        "GITHUB_REPO": "your_repo",
        "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"
      }
    }
  }
}

或使用直接提供商密钥（更简单）：

{
  "mcpServers": {
    "github-project-manager": {
      "command": "npx",
      "args": ["-y", "mcp-github-project-manager"],
      "env": {
        "GITHUB_TOKEN": "your_github_token",
        "GITHUB_OWNER": "your_username",
        "GITHUB_REPO": "your_repo",
        "ANTHROPIC_API_KEY": "your_anthropic_api_key"
      }
    }
  }
}

对于 Claude Code CLI，请运行：

claude mcp add github-project-manager -- pnpm dlx mcp-github-project-manager

在 Roocode 中安装

将以下内容添加到 Roocode 配置中：

{
  "mcpServers": {
    "github-project-manager": {
      "command": "npx",
      "args": ["-y", "mcp-github-project-manager"],
      "env": {
        "GITHUB_TOKEN": "your_github_token",
        "GITHUB_OWNER": "your_username",
        "GITHUB_REPO": "your_repo"
      }
    }
  }
}

在 Windsurf 中安装

将以下内容添加到 Windsurf MCP 配置文件中：

{
  "mcpServers": {
    "github-project-manager": {
      "command": "npx",
      "args": ["-y", "mcp-github-project-manager"],
      "env": {
        "GITHUB_TOKEN": "your_github_token",
        "GITHUB_OWNER": "your_username",
        "GITHUB_REPO": "your_repo"
      }
    }
  }
}

有关更多信息，请参阅 Windsurf MCP 文档。

在 VS Code 中安装

将以下内容添加到 VS Code MCP 配置文件中：

{
  "servers": {
    "github-project-manager": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-github-project-manager"],
      "env": {
        "GITHUB_TOKEN": "your_github_token",
        "GITHUB_OWNER": "your_username",
        "GITHUB_REPO": "your_repo"
      }
    }
  }
}

有关更多信息，请参阅 VS Code MCP 文档。

在 Cursor 中安装

将以下内容添加到 Cursor MCP 配置文件中：

{
  "mcpServers": {
    "github-project-manager": {
      "command": "npx",
      "args": ["-y", "mcp-github-project-manager"],
      "env": {
        "GITHUB_TOKEN": "your_github_token",
        "GITHUB_OWNER": "your_username",
        "GITHUB_REPO": "your_repo"
      }
    }
  }
}

有关更多信息，请参阅 Cursor MCP 文档。

使用 Docker

如果你更希望在 Docker 容器中运行 MCP 服务：

1. 构建 Docker 镜像：

docker build -t mcp-gh-project .

2. 运行容器：

docker run -d \
  -e GITHUB_TOKEN=your_github_token \
  -e GITHUB_OWNER=your_github_owner \
  -e GITHUB_REPO=your_repository_name \
  mcp-gh-project:latest

或者使用 CLI 参数：

docker run -d mcp-gh-project:latest \
  --github_token your_github_token \
  --github_owner your_owner \
  --github_repo your_repo

3. 配置 MCP 客户端：

{
  "mcpServers": {
    "github-project-manager": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "GITHUB_TOKEN", "-e", "GITHUB_OWNER", "-e", "GITHUB_REPO", "mcp-gh-project:latest"],
      "env": {
        "GITHUB_TOKEN": "your_token",
        "GITHUB_OWNER": "your_owner",
        "GITHUB_REPO": "your_repo"
      }
    }
  }
}

     "env": {
       "GITHUB_TOKEN": "your_github_token",
       "GITHUB_OWNER": "your_username",
       "GITHUB_REPO": "your_repo"
     }
   }
 }

}

### Troubleshooting

#### Common Issues

1. **Module Not Found Errors**

If you encounter module resolution issues, try using `bunx` instead of `npx`:

```json
{
  "mcpServers": {
    "github-project-manager": {
      "command": "bunx",
      "args": ["-y", "mcp-github-project-manager"]
    }
  }
}

2. Windows 专属配置

   在 Windows 上，你可能需要使用 cmd 来运行命令：

   {
     "mcpServers": {
       "github-project-manager": {
         "command": "cmd",
         "args": [
           "/c",
           "npx",
           "-y",
           "mcp-github-project-manager"
         ]
       }
     }
   }
   

3. 权限问题

   如果遇到权限问题，请确保你的 GitHub 令牌具备配置部分中列出的所需权限。

Agent 编排

Agent 编排层支持自主 AI Agent（Claude Code、Codex、Cursor 等）自行认领任务、报告进度、提交工作成果，并在令牌预算内运行，所有数据均由 GitHub 原生存储支持。

工作原理

Agent 通过两个组合工具与编排层交互：agent_work（任务生命周期）和 agent_manage（管理）：

┌─────────────────────────────────────────────────────────────────────┐
│                    Agent Orchestration Layer                        │
│                                                                     │
│  ┌───────────┐  ┌──────────────┐  ┌─────────────┐  ┌────────────┐  │
│  │  Agent     │  │  Task        │  │  Work       │  │  Budget    │  │
│  │  Registry  │  │  Checkout    │  │  Products   │  │  Manager   │  │
│  └───────────┘  └──────────────┘  └─────────────┘  └────────────┘  │
│         │              │                │                │          │
│         ▼              ▼                ▼                ▼          │
│  ┌─────────────────────────────────────────────────────────────┐    │
│  │           GitHub-Native Storage (Issues + Projects)         │    │
│  │  • Agent registry → pinned issue (label: agent-registry)   │    │
│  │  • Task claims   → project custom fields                   │    │
│  │  • Work products → structured issue comments               │    │
│  │  • Budgets       → agent registry metadata                 │    │
│  └─────────────────────────────────────────────────────────────┘    │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Agent 组合工具

工具	操作	用途
agent_work	register	注册 AI Agent，并指定角色、运行时和能力
agent_work	checkout_task	使用选择策略认领下一个可用任务
agent_work	release_task	将任务退回任务池（受阻、技能不匹配等）
agent_work	complete_task	将任务标记为已完成并附上摘要
agent_work	heartbeat	报告存活状态、进度百分比、分支和阻碍因素
agent_work	check_work_status	查看已提交工作的审核／合并状态
agent_work	get_task_context	获取任务的增强上下文
agent_manage	list	列出已注册的 Agent，并按角色或状态筛选
agent_manage	deregister	从注册表中移除 Agent
agent_manage	get_activity	所有 Agent 的仪表板：任务、进度、心跳、预算
agent_manage	submit_work_product	提交代码更改，并提供分支、PR、文件和测试结果
agent_manage	get_budget	查看 Agent 的令牌预算（已使用、剩余、警告）
agent_manage	set_budget	配置令牌预算、警告阈值、硬性上限和重置周期

快速入门：自主 Agent 循环

// 1. Register the agent
{"tool": "agent_work", "arguments": {"action": "register", "name": "claude-eng-1", "role": "engineer", "runtime": "claude-code", "capabilities": ["typescript", "react", "testing"]}}
// → { id: "agent-abc123", status: "idle", ... }

// 2. Check out a task
{"tool": "agent_work", "arguments": {"action": "checkout_task", "agentId": "agent-abc123", "strategy": "highest_priority"}}
// → { success: true, issueNumber: 42, issueTitle: "Add login form", branchSuggestion: "feat/42-add-login-form" }

// 3. Get full context
{"tool": "agent_work", "arguments": {"action": "get_task_context", "issueNumber": 42}}
// → { issue: {...}, milestone: {...}, acceptanceCriteria: [...], codingStandards: "..." }

// 4. Work on the task, sending heartbeats periodically
{"tool": "agent_work", "arguments": {"action": "heartbeat", "agentId": "agent-abc123", "status": "working", "taskId": "issue-42", "progress": 60, "progressSummary": "Tests passing, working on edge cases", "currentBranch": "feat/42-add-login-form"}}

// 5. Submit the work product
{"tool": "agent_manage", "arguments": {"action": "submit_work_product", "agentId": "agent-abc123", "taskId": "issue-42", "issueNumber": 42, "branch": "feat/42-add-login-form", "prNumber": 99, "summary": "Added login form with email/password validation"}}

// 6. Complete the task
{"tool": "agent_work", "arguments": {"action": "complete_task", "agentId": "agent-abc123", "taskId": "issue-42", "summary": "Implemented login form with validation and tests"}}

// 7. Repeat: checkout next task
{"tool": "agent_work", "arguments": {"action": "checkout_task", "agentId": "agent-abc123", "strategy": "highest_priority"}}

子 Agent 层级结构

Agent 可以使用 parentAgentId 注册子 Agent，从而实现多 Agent 架构：

// Parent agent registers itself
{"tool": "agent_work", "arguments": {"action": "register", "name": "lead-agent", "role": "pm", "runtime": "claude-code"}}
// → { id: "agent-lead" }

// Parent spawns a sub-agent
{"tool": "agent_work", "arguments": {"action": "register", "name": "worker-1", "role": "engineer", "runtime": "claude-code", "parentAgentId": "agent-lead", "capabilities": ["typescript", "testing"]}}

// Deregistering the parent cascades to all children
{"tool": "agent_manage", "arguments": {"action": "deregister", "agentId": "agent-lead"}}
// → Removes lead-agent and worker-1

预算执行

令牌预算可防止 AI 成本失控：

// Set a daily budget with 80% warning
{"tool": "agent_manage", "arguments": {"action": "set_budget", "agentId": "agent-abc123", "totalTokens": 500000, "warningThreshold": 0.8, "hardStop": true, "resetPeriod": "daily"}}

// Check budget status before expensive operations
{"tool": "agent_manage", "arguments": {"action": "get_budget", "agentId": "agent-abc123"}}
// → { usedTokens: 350000, remainingTokens: 150000, usagePercent: 70, isWarning: false, isExhausted: false }

GitHub 原生数据模型

所有编排状态都保存在你的 GitHub 仓库中，无需外部数据库：

数据	存储位置	详情
Agent 注册表	置顶议题	带有 agent-registry 标签的议题中的 JSON 正文
任务认领记录	项目自定义字段	agent_claimed_by、agent_claimed_at、agent_status、agent_work_branch、agent_pr_number
工作成果	议题评论	包含 `` 标记的结构化评论
预算	Agent 元数据	与每条 Agent 记录一起存储在 Agent 注册表中
心跳	Agent 元数据	Agent 记录上的 lastHeartbeat 时间戳

配置

常量	默认值	说明
心跳超时	30 分钟	超过此时间后，Agent 将被视为失去响应
默认预算	500,000 个令牌	每个 Agent 的初始令牌预算
注册表标签	agent-registry	Agent 注册表对应的 GitHub 议题标签

详细参数说明请参阅工具参考。

架构

该服务遵循整洁架构原则，采用清晰的分层结构：

• 领域层：核心实体、仓库接口和 Zod 模式
• 基础设施层：GitHub API 集成与实现
• 服务层：业务逻辑协调
• MCP 层：工具定义和请求处理

贡献

欢迎贡献！请参阅 CONTRIBUTING.md 了解指南。

1. Fork 此仓库
2. 创建功能分支：git checkout -b feature/amazing-feature
3. 提交更改：git commit -m 'Add some amazing feature'
4. 推送到分支：git push origin feature/amazing-feature
5. 创建 Pull Request

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

参考资料

• Model Context Protocol
• GitHub Projects API

当前状态

核心功能

功能	状态	说明
项目创建	✅ 完成	全面支持 v2 项目
里程碑管理	✅ 完成	已实现 CRUD 操作
Sprint 规划	✅ 完成	包含指标跟踪
Issue 管理	✅ 完成	支持自定义字段
资源版本控制	✅ 完成	支持乐观锁定和模式验证
Webhook 集成	✅ 完成	实时更新；故障关闭式 HMAC 签名验证 + SSE 流式传输

AI 驱动的功能

功能	状态	说明
PRD 生成	✅ 完成	支持多个 AI 提供商，可全面创建 PRD
任务生成	✅ 完成	由 AI 驱动，将 PRD 解析为可执行任务
功能添加	✅ 完成	智能添加功能并进行影响分析
任务复杂度分析	✅ 完成	由 AI 进行详细分析并评估风险
任务推荐	✅ 完成	由 AI 驱动的下一项任务推荐
任务拆分	✅ 完成	将复杂任务拆分为子任务
PRD 增强	✅ 完成	由 AI 驱动的 PRD 改进和差距分析
需求可追溯性	✅ 完成	端到端可追溯性矩阵及覆盖率分析

需求可追溯性

功能	状态	说明
业务需求提取	✅ 完成	从 PRD 目标和成功指标中提取
用例生成	✅ 完成	包含参与者-目标-场景结构及备选方案
可追溯性链接	✅ 完成	双向链接及影响分析
覆盖率分析	✅ 完成	识别差距并检测孤立任务
变更跟踪	✅ 完成	分析需求变更的影响
验证跟踪	✅ 完成	测试用例映射和验证状态

MCP 实现

组件	状态	说明
工具定义	✅ 完成	已实现所有核心工具，并使用 Zod 验证
资源管理	✅ 完成	完整的 CRUD 操作和版本控制
安全性	✅ 完成	令牌验证、故障关闭式 Webhook 签名验证、文件挂载的密钥（SECRETS_DIR）
错误处理	✅ 完成	符合 MCP 规范
传输	✅ 完成	支持 Stdio 和 HTTP

请参阅 .planning/STATUS.md 了解详细的实现状态。 | 资源管理 | ✅ 完成 | 支持乐观锁定和关系跟踪 | | 响应处理 | ✅ 完成 | 支持多种内容类型的丰富内容格式 | | 错误处理 | ✅ 完成 | 将错误全面映射到 MCP 错误代码 | | 状态管理 | ✅ 完成 | 支持冲突解决和速率限制 |

最新改进

• 依赖项与 SDK 现代化（2026-07-15）：

  • 迁移到 Vercel AI SDK v7 和 Zod v4（同步升级；MCP SDK 1.29 支持 Zod 4）
  • 将 Octokit 类型包与 @octokit/rest 22 对齐
  • 修复严重的 Handlebars 漏洞和所有高危安全公告

• 架构与可靠性（2026-07-15）：

  • 拆分 ProjectManagementService 门面（提取 IssueService、RoadmapService；自动化功能委托给 ProjectAutomationService）
  • 解决循环依赖；健康检查现在会实际探测 GitHub 速率限制
  • Webhook 签名验证失败时默认拒绝；支持文件挂载的密钥（SECRETS_DIR）及密钥轮换
  • 按大小限制缓存淘汰（MAX_CACHE_ENTRIES），并修复命名空间索引清理问题

• 增强的资源系统：

  • 为所有资源类型添加 Zod 架构验证
  • 实现资源关系跟踪
  • 创建集中式 ResourceFactory，确保一致的资源访问方式

• 改进的 GitHub API 集成：

  • 添加智能速率限制与自动节流
  • 为 REST 和 GraphQL API 实现分页支持
  • 通过特定错误类型增强错误处理

• 高级工具系统：

  • 创建带 Zod 验证的工具定义注册表
  • 实现标准化的工具响应格式
  • 为所有工具添加基于示例的文档

• 丰富的响应格式：

  • 添加对多种内容类型（JSON、Markdown、HTML、Text）的支持
  • 为长时间运行的操作实现进度更新
  • 为大型结果集添加分页支持

已发现的功能缺口

按优先级排列的剩余缺口，供未来开发使用（更新于 2026-07-15）。实时且经代码验证的状态见 docs/remediation/GAP-TRACKER.md。

1. 分布式缓存：

   • ResourceCache 现已支持持久化（CachePersistence）和按大小限制、优先淘汰最旧条目的策略（MAX_CACHE_ENTRIES）。目前仍仅支持单实例部署——多实例部署尚无分布式／共享缓存。

2. 性能优化：

   • 缺少相关资源的查询批处理
   • 缺少对频繁访问资源的后台刷新
   • 相关资源的预取功能不完整

3. 数据可视化与报告（路线图第 11 阶段，尚未构建）：

   • 没有内置的指标可视化生成器
   • 缺少报告生成能力
   • 时间序列数据分析能力有限

自早期快照以来已解决：实时 Webhook 集成与 SSE 流式传输、自动化规则管理、缓存持久化与淘汰，以及默认拒绝的 Webhook 签名检查。

文档

入门

• 部署指南 - 安装、Docker 和 MCP 客户端设置
• 配置指南 - 所有配置选项
• 故障排除指南 - 常见问题与解决方案

参考

• 工具参考 - 已记录 20 个复合工具（169 个操作）
• 架构 - 系统设计与模式
• API 参考 - 服务与基础设施 API

指南

• 教程 - 分步指南
• 用户指南 - 详细使用说明
• 测试指南 - 测试套件文档

开发

• 参与贡献 - 开发指南
• MCP 集成 - MCP 专属详情

交互式文档

如需交互式探索 API，请在浏览器中打开 API Explorer。

开发

测试

# Unit tests
pnpm test

# AI service/tool tests
pnpm run test:ai

# End-to-end tests
pnpm run test:e2e

# E2E MCP tool suite (mocked GitHub/AI)
pnpm run test:e2e:tools

代码质量

# Lint code
pnpm run lint

# Type check
pnpm exec tsc --noEmit

# Format code
pnpm run format

贡献

欢迎为 GitHub Project Manager MCP Server 做出贡献！详情请参阅我们的贡献指南：

• 开发工作流
• 代码规范
• 测试指南
• 文档指南

许可证

MIT