GitHub 项目管理 MCP 服务器

一个实现模型上下文协议（MCP）的服务器，通过标准化工具和资源提供 GitHub 项目的功能。该服务器允许 LLM 客户端通过 MCP 接口程序化地管理 GitHub 项目。

概述

此服务器实现了 Model Context Protocol，以便将 GitHub 项目的功能暴露给 LLM 客户端。它提供了管理和处理项目、里程碑、sprint 和指标的工具，通过 GitHub 的 GraphQL API 维护状态并根据 MCP 规范处理错误。

主要功能

• 项目管理

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

• 项目资源

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

• MCP 实现

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

• GitHub 集成

  • GraphQL API 集成与 Zod 验证
  • 相关资源的批量查询
  • 背景刷新功能

安装与配置

安装依赖

npm install mcp-server express graphql axios dotenv

环境变量

在项目根目录创建 .env 文件：

PORT=3000
DATABASE_URL=jdbc:mysql://localhost:3306/gpm_mcp?user=root&password=example
GRAPHQL_ENDPOINT=https://api.github.com/graphql

使用说明

启动服务器

node index.js

API 调用示例

使用 curl 或 Postman 发送 POST 请求到 http://localhost:3000/api：

{
  "tool": {
    "id": "github-projects",
    "name": "GitHub Projects Manager"
  },
  "command": "listProjects",
  "args": {
    "username": "your_github_username",
    "token": "your_github_token"
  }
}

系统架构

分层架构

1. 表现层：处理用户请求和响应。
2. 业务逻辑层：实现核心功能，如项目管理、数据处理。
3. 数据访问层：与数据库和外部 API（如 GitHub）交互。

关键组件

• MCPServer: 处理 HTTP 请求并解析工具指令。
• ProjectManager: 负责与 GitHub 项目相关的所有操作。
• DatabaseAdapter: 提供数据库连接和查询功能。
• GraphQLClient: 封装对 GitHub GraphQL API 的调用。

系统现状

已实现的功能

• 基于 MCP 协议的工具定义与执行。
• 多租户支持，通过用户标识符隔离数据。
• 详细的审计日志记录，默认启用。

待办事项

1. 实现指标和数据分析功能。
2. 添加可视化报告生成器。
3. 优化性能，引入查询批处理。

文档

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

交互式文档

在浏览器中打开 API 探索器 进行交互式 API 探索。

开发

测试

# 单元测试
npm test

# 集成测试
npm run test:integration

# 端到端测试
npm run test:e2e

代码质量

# 格式化代码
npm run format

# 类型检查
npm run type-check

# 编码规范检查
npm run lint

贡献

我们欢迎对 GitHub 项目管理 MCP 服务器的贡献！请查阅我们的 贡献指南 了解详细信息，包括：

• 开发流程
• 编码标准
• 测试规范
• 文档编写指南

许可证

MIT