GitHub 项目管理器 MCP 服务器

一个模型上下文协议 (MCP) 服务器实现，通过标准化的工具和资源提供 GitHub 项目功能。该服务器使 LLM 客户端能够通过 MCP 接口以编程方式管理 GitHub 项目。

概述

该服务器实现了 模型上下文协议，以向 LLM 客户端公开 GitHub 项目功能。它提供了通过 GitHub 的 GraphQL API 管理项目、里程碑、sprint 和指标的工具，同时根据 MCP 规范维护状态和处理错误。

主要特性

• 项目管理

  • 创建和管理 GitHub 项目 (v2)
  • 处理项目设置和配置
  • 管理项目可见性和访问权限

• 项目资源

  • 问题和里程碑管理
  • Sprint 计划和跟踪
  • 自定义字段和视图
  • 资源版本控制和锁定

• MCP 实现

  • 完全符合 MCP 规范
  • 标准化的工具定义
  • 资源状态管理
  • 渐进式响应处理
  • 全面的错误处理

• GitHub 集成

  • GraphQL API 集成
  • 速率限制处理
  • 乐观并发
  • Webhook 支持（计划中）

安装

# 安装依赖
npm install
# 或
pnpm install

# 设置环境变量
cp .env.example .env
# 使用您的 GitHub 令牌和详细信息编辑 .env

配置

必需的环境变量：

GITHUB_TOKEN=your_github_token
GITHUB_OWNER=repository_owner
GITHUB_REPO=repository_name

GitHub 令牌需要以下权限：

• repo (完全仓库访问权限)
• project (项目访问权限)
• write:org (组织访问权限)

用法

# 启动 MCP 服务器
npm start

# 运行测试
npm test
npm run test:e2e

有关详细的使用说明，请参阅 用户指南。

架构

该服务器遵循清洁架构原则，具有不同的层：

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

有关详细的架构文档，请参阅 ARCHITECTURE.md。

当前状态

核心特性

特性	状态	备注
项目创建	✅ 完成	完全支持 v2 项目
里程碑管理	✅ 完成	已实现 CRUD 操作
Sprint 计划	✅ 完成	包括指标跟踪
问题管理	✅ 完成	支持自定义字段
资源版本控制	🏗️ 进行中	已实现基本版本控制
Webhook 集成	📅 计划中	实时更新

MCP 实现

组件	状态	备注
工具定义	✅ 完成	已实现所有核心工具
资源管理	✅ 完成	具有乐观锁定
响应处理	🏗️ 进行中	渐进式响应正在进行中
错误处理	🏗️ 进行中	全面的错误映射
状态管理	✅ 完成	具有冲突解决

有关详细的实现状态，请参阅 docs/mcp/gaps-analysis.md。

文档

• 用户指南 - 详细的使用说明
• 架构 - 系统架构和设计
• 贡献 - 开发指南
• MCP 文档 - MCP 特定的详细信息

开发

测试

# 单元测试
npm test

# 集成测试
npm run test:integration

# 端到端测试
npm run test:e2e

代码质量

# Lint 代码
npm run lint

# 类型检查
npm run type-check

# 格式化代码
npm run format

贡献

有关开发指南，请参阅 CONTRIBUTING.md。

许可证

MIT