GitHub 项目管理 MCP 服务器

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

概述

该服务器实现了 模型上下文协议，将 GitHub 项目功能暴露给 LLM 客户端。它通过 GitHub 的 GraphQL API 提供了管理和配置项目的工具，同时根据 MCP 规范维护状态并处理错误。

主要特性

• 项目管理

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

• 项目资源

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

• MCP 实现

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

• GitHub 集成

  • 带分页支持的 GraphQL API 集成
  • 智能速率限制处理
  • 乐观并发
  • Webhook 支持（计划中）

安装

# Install dependencies
npm install
# or
pnpm install

# Set up environment variables
cp .env.example .env
# Edit .env with your GitHub token and details

配置

必需的环境变量：

GITHUB_TOKEN=your_github_token
GITHUB_OWNER=repository_owner
GITHUB_REPO=repository_name

GitHub 令牌需要以下权限：

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

使用

# Start the MCP server
npm start

# Run tests
npm test
npm run test:e2e

请参阅 用户指南 获取详细的使用说明。

架构

服务器遵循 Clean Architecture 原则，具有明确的层次结构：

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

请参阅 ARCHITECTURE.md 获取详细的架构文档。

当前状态

核心功能

MCP 实现

最近的改进

• 增强资源系统：

  • 为所有资源类型添加了 Zod 模式验证
  • 实现了资源关系跟踪
  • 创建了一个集中的 ResourceFactory 以保持一致的资源访问

• 改进 GitHub API 集成：

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

• 高级工具系统：

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

• 丰富的响应格式：

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

已识别的功能缺口

尽管最近有所改进，但以下功能缺口仍然存在，并被优先考虑在未来开发中解决：

1. 持久缓存策略：

   • 尽管 ResourceCache 提供了内存缓存，但它缺乏跨服务器重启的持久性
   • 没有多实例部署的分布式缓存
   • 缺少用于内存管理的缓存淘汰策略

2. 实时事件处理：

   • 没有用于从 GitHub 获取实时更新的 webhook 集成
   • 缺少客户端的基于事件的订阅系统
   • 缺少用于流式更新的服务器发送事件 (SSE) 支持

3. 高级 GitHub Projects v2 功能：

   • 对自定义字段类型和验证的支持有限
   • 与 GitHub 较新的 Projects v2 字段类型集成不完全
   • 缺少自动化规则管理

4. 性能优化：

   • 没有关联资源的查询批处理
   • 缺少频繁访问资源的后台刷新
   • 关联资源的预取不完整

5. 数据可视化和报告：

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

详见 docs/mcp/gaps-analysis.md 了解详细的实施状态。

文档

• 用户指南 - 详细的使用说明
• API 参考 - 全面的工具文档
• 教程 - 分步指南
• 示例 - 常见任务的代码示例
• 架构 - 系统架构和设计
• 贡献指南 - 开发指南
• MCP 文档 - MCP 特定详情

交互式文档

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

开发

测试

# Unit tests
npm test

# Integration tests
npm run test:integration

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

代码质量

# Lint code
npm run lint

# Type check
npm run type-check

# Format code
npm run format

贡献

我们欢迎对 GitHub Project Manager MCP Server 的贡献！请参阅我们的 贡献指南，了解以下内容：

• 开发工作流程
• 代码标准
• 测试指南
• 文档指南

许可证

MIT