MCP GitHub项目经理

一个用Python构建的全面的模型上下文协议（MCP）服务器，提供高级的GitHub项目管理功能。通过MCP界面管理您的GitHub项目、问题、里程碑、冲刺等。

![License: MIT](https://opensource.org/licenses/MIT) ](https://www.python.org/) ](https://github.com/your-username/git_proj_manger_mcp)

概述

此服务器实现模型上下文协议通过GitHub的GraphQL API提供全面的GitHub项目管理。它提供了47多种工具，用于管理项目、问题、里程碑、冲刺、标签、注释、自定义字段和高级搜索/过滤，同时根据MCP规范维护状态和处理错误。

该服务器使用Python 3.8+构建，遵循干净架构原则，为GitHub项目管理操作提供可维护和可扩展的代码库。

🚀 主要特点

47+MCP工具：完成项目、问题、里程碑、冲刺、标签、注释等的CRUD操作
路线图创建：创建包含里程碑和问题的项目路线图
Sprint计划：通过指标跟踪计划和管理开发冲刺
项目管理：完全支持GitHub Projects v2，具有自定义字段和视图
整洁架构：遵循干净架构原则的结构良好的代码库
类型安全：所有工具的完整类型提示和Pydantic验证
错误处理：具有重试机制的全面错误处理

快速开始

先决条件

Python 3.8或更高版本
具有适当权限的GitHub个人访问令牌

安装

选项1：从源代码安装

# Clone the repository
git clone https://github.com/your-username/git_proj_manger_mcp.git
cd git_proj_manger_mcp

# Create a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

选项2：打包安装（即将推出）

pip install mcp-github-project-manager

备注：计划在未来的版本中发布软件包。

配置

创建一个 .env 项目根目录中的文件：

GITHUB_TOKEN=your_github_token
GITHUB_OWNER=your_github_username_or_organization
GITHUB_REPO=your_repository_name

所需的GitHub令牌权限：

repo （完全访问存储库）
project （项目访问权限）
write:org （组织访问权限，如适用）

运行服务器

# Run from source
python -m src

# Or with command line arguments
python -m src --token=your_token --owner=your_username --repo=your_repo

# With verbose logging
python -m src --verbose

主要特点

📊 项目管理

创建项目：创建具有自定义可见性的新GitHub项目（v2）
列出项目：列出存储库的所有项目
更新项目：更新项目详细信息、描述和可见性
删除项目：删除不再需要的项目

🎯 里程碑管理

创建里程碑：创建带有截止日期的项目里程碑
列出里程碑：列出所有具有筛选选项的里程碑
更新里程碑：更新里程碑详细信息和状态
删除里程碑：删除里程碑
指标：获取里程碑进度指标并跟踪逾期/即将到来的里程碑

📋 问题管理

创建问题：创建带有标签、受让人和优先级的GitHub问题
列出问题：按状态、受让人、标签和里程碑列出筛选问题
获取问题详细信息：检索有关特定问题的详细信息
更新问题：更新问题状态、描述和元数据
搜索问题：使用GitHub查询语法进行高级问题搜索（例如。， is:issue is:open label:bug)
问题评论：添加、列出、更新和删除对问题的评论

🏃 Sprint计划

创建精灵：创建带有开始/结束日期和目标的开发冲刺
计划冲刺：针对选定的问题规划冲刺
列出精灵：列出所有具有状态筛选的冲刺
获取当前Sprint：检索当前活动的冲刺
更新Sprints：更新冲刺详细信息和状态
管理Sprint问题：添加或删除冲刺中的问题
Sprint指标：跟踪冲刺进度和完成指标

🗺️ 路线图创建

创建路线图：制定包含里程碑和问题的全面项目路线图
里程碑指标：跟踪里程碑进度和完成情况
逾期里程碑：识别和跟踪逾期的里程碑
即将到来的里程碑：在时间框架内获取即将到来的里程碑

🏷️ 标签和组织

创建标签：创建带有颜色和描述的存储库标签
列表标签：列出存储库中的所有标签

📐 自定义字段和视图

项目字段：创建、列出和更新自定义项目字段
项目视图：创建不同的视图（板、表、时间线、路线图）
字段值：设置、获取和清除项目项的自定义字段值

🔗 项目项

添加项目：向项目添加问题或PR
删除项目：从项目中删除项目
列出项目：列出项目中的所有项目
筛选项目：按字段值筛选项目项（例如优先级、状态）
按字段查找：按特定项目字段值查找问题

安装

来源

# Clone the repository
git clone https://github.com/your-username/git_proj_manger_mcp.git
cd git_proj_manger_mcp

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

依赖项

该项目需要以下核心依赖关系：

mcp>=1.0.0 -模型上下文协议SDK
pydantic>=2.0.0 -数据验证
pygithub>=2.0.0 -GitHub API集成
click>=8.0.0 -CLI界面
httpx>=0.27.0 -HTTP客户端
python-dotenv>=1.0.0 -环境变量管理

看 requirements.txt 查看完整列表。

配置

环境变量

创建一个 .env 项目根目录中的文件：

# Required GitHub Configuration
GITHUB_TOKEN=your_github_token
GITHUB_OWNER=your_github_username_or_organization
GITHUB_REPO=your_repository_name

# Optional Configuration
SYNC_ENABLED=true
SYNC_TIMEOUT_MS=5000
CACHE_DIRECTORY=.cache
WEBHOOK_SECRET=your_webhook_secret
WEBHOOK_PORT=3000
SSE_ENABLED=false

命令行参数

您还可以通过命令行参数提供配置：

python -m src --token=your_token --owner=your_username --repo=your_repo --verbose

可用CLI选项：

-t, --token：GitHub个人访问令牌
-o, --owner：GitHub存储库所有者
-r, --repo：GitHub存储库名称
-e, --env-file：.env文件的路径（默认值：.env）
-v, --verbose：启用详细日志记录
--version：显示版本信息

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

用法

作为命令行工具

# Basic usage
python -m src

# With environment variables
GITHUB_TOKEN=your_token python -m src

# With command line arguments
python -m src --token=your_token --owner=your_username --repo=your_repo

# Verbose mode
python -m src --verbose

与MCP客户端集成

服务器按照MCP规范通过stdio传输进行通信。配置您的MCP客户端以运行：

python -m src

在AI助手中安装

在游标中安装

将此添加到您的Cursor MCP配置文件中(cursor-mcp-config.json):

{
  "mcpServers": {
    "github-project-manager": {
      "command": "python",
      "args": ["-m", "src"],
      "env": {
        "GITHUB_TOKEN": "your_github_token",
        "GITHUB_OWNER": "your_username",
        "GITHUB_REPO": "your_repo"
      }
    }
  }
}

在Claude桌面中安装

将此添加到您的Claude Desktop配置文件中：

{
  "mcpServers": {
    "github-project-manager": {
      "command": "python",
      "args": ["-m", "src"],
      "env": {
        "GITHUB_TOKEN": "your_github_token",
        "GITHUB_OWNER": "your_username",
        "GITHUB_REPO": "your_repo"
      }
    }
  }
}

在VS代码中安装

将此添加到您的VS代码MCP配置中：

{
  "servers": {
    "github-project-manager": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "src"],
      "env": {
        "GITHUB_TOKEN": "your_github_token",
        "GITHUB_OWNER": "your_username",
        "GITHUB_REPO": "your_repo"
      }
    }
  }
}

可用工具

服务器提供47多种MCP工具，分为以下几类：

项目工具

create_project -创建一个新的GitHub项目
list_projects -列出所有项目
get_project -获取项目详细信息
update_project -更新项目信息
delete_project -删除项目

里程碑工具

create_milestone -创建新的里程碑
list_milestones -列出所有里程碑
update_milestone -更新里程碑详细信息
delete_milestone -删除里程碑
get_milestone_metrics -获取里程碑进度指标
get_overdue_milestones -获取逾期的里程碑
get_upcoming_milestones -获取即将到来的里程碑

问题工具

create_issue -创建新问题
list_issues -列出过滤问题
get_issue -获取问题详细信息
update_issue -更新问题信息
search_issues -使用GitHub查询语法进行高级问题搜索

问题评论工具

add_issue_comment -在GitHub问题上添加评论
list_issue_comments -列出GitHub问题的所有评论
update_issue_comment -更新GitHub问题的评论
delete_issue_comment -从GitHub问题中删除评论

Sprint工具

create_sprint -创建一个新的sprint
list_sprints -列出所有冲刺
get_current_sprint -获得主动冲刺
update_sprint -更新冲刺详细信息
plan_sprint -计划一个有问题的冲刺
add_issues_to_sprint -在sprint中添加问题
remove_issues_from_sprint -从sprint中删除问题
get_sprint_metrics -获取冲刺进度指标

路线图工具

create_roadmap -创建包含里程碑和问题的项目路线图

标签工具

create_label -创建存储库标签
list_labels -列出所有标签

项目现场工具

create_project_field -创建自定义项目字段
list_project_fields -列出所有项目字段
update_project_field -更新项目字段

项目视图工具

create_project_view -创建项目视图
list_project_views -列出所有项目视图
update_project_view -更新项目视图
delete_project_view -删除项目视图

项目项工具

add_project_item -将项目添加到项目中
remove_project_item -从项目中删除项目
list_project_items -列出项目中的所有项目
filter_project_items -按字段值筛选项目项
find_issues_by_field -按项目字段值查找问题

现场价值工具

set_field_value -为项目项设置字段值
get_field_value -获取项目项的字段值
clear_field_value -清除项目项的字段值

建筑

该项目遵循清洁建筑原则，明确分离关注点：

域层 (src/domain/)：核心业务实体、类型和接口
基础设施层 (src/infrastructure/)：GitHub API集成、存储库和MCP实施
服务层 (src/services/)：业务逻辑和协调
工具层 (src/infrastructure/tools/)：MCP工具定义、处理程序和验证

看建筑.md 获取详细的架构文档。

发展

设置开发环境

# Clone the repository
git clone https://github.com/your-username/git_proj_manger_mcp.git
cd git_proj_manger_mcp

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies including dev dependencies
pip install -r requirements.txt

代码质量

# Format code with black
black src/

# Lint code with ruff
ruff check src/

# Type check with mypy
mypy src/

测试

# Run tests
pytest

# Run tests with coverage
pytest --cov=src --cov-report=html

故障排除

常见问题

未找到模块错误

- 确保安装了所有依赖项： pip install -r requirements.txt - 验证您的虚拟环境是否已激活

GitHub代币问题

- 验证您的令牌是否具有所需的权限(repo, project, write:org) - 检查令牌是否在您的 .env 文件或环境变量

导入错误

- 确保从项目根目录运行 - 验证Python版本是否为3.8或更高版本： python --version

连接问题

- 检查您的互联网连接 - 验证GitHub API是否可访问 - 检查速率限制问题

贡献

欢迎投稿！请看贡献.md 作为指导方针。

分叉存储库
创建要素分支： git checkout -b feature/amazing-feature
提交您的更改： git commit -m 'Add some amazing feature'
推到分支： git push origin feature/amazing-feature
打开拉取请求

许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

参考文献

模型上下文协议

致谢

该项目的灵感来自并使用通过 @孔瓦尔·维维克作为参考。最初的TypeScript/Node.js实现为MCP服务器架构、GitHub项目API集成和工具设计模式提供了有价值的见解。

本项目的变更

此Python实现采用了原始项目的概念和架构，并进行了以下关键更改：

语言迁移：从TypeScript/Node.js重新实现到Python 3.8+
类型验证：将Zod模式替换为Pydantic模型，用于Python本地验证
异步模式：在整个过程中实现了Python异步/等待模式
MCP-SDK：与Python MCP SDK集成，而不是TypeScript SDK
建筑：维护适用于Python的干净架构原则
依赖项：使用Python生态系统（pygithub、httpx、aiohttp）而不是Node.js包
工具系统：使用Python模式重新实现了47+MCP工具
错误处理：使用域错误类型的Python特定错误处理
缓存：使用Python数据类实现内存缓存
文档：更新了Python开发人员的所有文档

我们感谢最初的项目维护者和贡献者所做的出色工作，并将他们的代码库作为开源提供。

当前状态

✅ 已实现的功能

47+MCP工具所有核心项目管理工具均已全面实施
项目管理：完成GitHub Projects v2的CRUD操作
问题管理：带注释的完整问题生命周期管理
问题评论：完成评论管理（添加、列出、更新、删除）
高级搜索：基于GitHub查询语法的问题搜索
项目筛选：按字段值筛选项目项
里程碑管理：创建、更新、删除和跟踪里程碑
Sprint计划：Sprint创建、规划和指标跟踪
路线图创建：自动生成带有里程碑和问题的路线图
自定义字段和视图：支持自定义项目字段和视图
错误处理：具有重试机制的全面错误处理
缓存：支持TTL的内存资源缓存
事件系统：用于跟踪资源更改的事件存储

🔄 未来的增强功能

基于人工智能的任务生成和分析（基础设施就绪）
Webhook集成实现实时更新
持久缓存（Redis/数据库支持）
高级指标和报告
多存储库支持

文档

建筑 -系统架构与设计
用户指南 -详细的使用说明
教程 -分步指南
-集成详细信息

公用事业

清理脚本

为批量操作提供了实用程序脚本：

# Delete all projects and close all issues
python delete_all_projects_and_issues.py

git proj manger MCP

快速接入

详细介绍