GitHub issues

GitHub Issue Shepherd-MCP服务器

一个模型上下文协议（MCP）服务器，帮助开发人员发现要处理的GitHub问题，克隆存储库，并在指导下创建拉取请求。

特性

• 🔍 智能问题发现：在特定存储库或GitHub上搜索问题
• 🏷️ 基于技能的匹配：查找与您的技能和兴趣相匹配的问题
• 📦 安全存储库克隆：自信地验证路径和克隆存储库
• 📝 公关创作指导：创建pull请求的分步说明
• 🤖 可选自动化：使用GitHub API自动创建PR和分叉
• 🛡️ 安全第一：令牌编校和安全文件系统操作

安装

先决条件

• Python 3.10或更高版本
• Git已安装并位于PATH中
• （可选）GitHub个人访问令牌，用于更高的速率限制和自动化

设置

1. 克隆或下载此存储库:

git clone https://github.com/BrachaLeah1/mcp_server_github_issues.git
cd mcp_server_github_issues

1. 创建和激活虚拟环境:

python -m venv venv

# On Windows
venv\Scripts\activate

# On Unix/MacOS
source venv/bin/activate

1. 安装依赖项:

pip install -e .

1. （可选）设置GitHub令牌:

# On Unix/MacOS
export GITHUB_TOKEN=your_github_token_here

# On Windows (Command Prompt)
set GITHUB_TOKEN=your_github_token_here

# On Windows (PowerShell)
$env:GITHUB_TOKEN="your_github_token_here"

要创建GitHub令牌，请执行以下操作：

1. 首选https://github.com/settings/tokens
2. 点击“生成新令牌（经典）”
3. 给它一个描述性的名称
4. 选择范围： repo, workflow （用于自动化功能）
5. 点击“生成令牌”并复制

通过MCP检查员进行测试

npx @modelcontextprotocol/inspector python src/server.py

运行服务器

服务器使用stdio传输（标准输入/输出）运行：

python -m src.server

或者直接：

python src/server.py

⚙️ MCP客户端配置

此服务器与任何 MCP兼容代码代理.\ 将其添加到客户端的MCP配置文件中，然后重新启动客户端。

______________________________________________________________________

示例：游标IDE

1. 按 Ctrl + Shift + P
2. 打开 光标设置
3. 引导到 工具和MCP
4. 添加具有以下配置的新MCP服务器：

{
  "mcpServers": {
    "mcp_github_issues": {
      "command": "C:/absolute/path/to/mcp_server_github_issues/venv/Scripts/python.exe",
      "args": [
        "C:/absolute/path/to/mcp_server_github_issues/src/server.py"
      ],
      "cwd": "C:/absolute/path/to/mcp_server_github_issues",
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

可用工具

1.发现_实证

发现流行的、成熟的GitHub存储库来做出贡献。当你没有特定的存储库，但想找到符合你兴趣的高质量项目时，可以使用它。

按以下条件筛选存储库:

• 最少1000颗星 （100+贡献者和积极维护的强指标）
• 仅限活动项目 （不包括存档/废弃的存储库）
• 公共仓库

参数:

• language：编程语言过滤器（例如“python”、“javascript”、“rust”）
• topics：项目主题列表（例如，\[“机器学习”、“数据科学”\]）
• sort：排序顺序-“星”（默认）、“叉”或“更新”
• limit：要返回的最大存储库数（1-30，默认值：10）

退货：包含以下内容的存储库列表：

• 名称、URL、描述
• 星数和语言
• 主题，上次更新时间
• 未决问题计数

示例:

{
  "language": "python",
  "topics": ["machine-learning"],
  "sort": "stars",
  "limit": 5
}

用例:

• “我想为Python项目做出贡献，但不知道是哪一个”
• “向我展示流行的JavaScript web框架以供学习”
• “寻找有贡献的活跃数据科学项目”

______________________________________________________________________

2.搜索问题

在特定存储库中搜索GitHub问题。在发现存储库后使用 discover_repository.

参数:

• repo：“所有者/仓库”格式的仓库名称（必填）
• skills：技能/关键字列表（例如，\[“python”、“测试”、“文档”\]）
• topics：主题列表（例如，\[“机器学习”、“网络开发”\]）
• language：编程语言过滤器
• difficulty：问题难度（“好的第一个问题”，“容易”，“中等”，“困难”）
• labels：要筛选的其他标签
• state：“打开”、“关闭”或“全部”
• sort：“相关性”、“创建”、“更新”或“评论”
• limit：最大结果（1-30，默认值：10）

示例:

{
  "repo": "openvinotoolkit/openvino",
  "difficulty": "good-first-issue",
  "limit": 10
}

3.获取问题详细信息

获取有关特定问题的详细信息。

参数:

• repo：“所有者/仓库”格式的仓库
• number：发行号
• include_comments：是否包含注释（默认值：false）
• max_comments：要包含的最大评论数（默认值：10）

示例:

{
  "repo": "facebook/react",
  "number": 12345,
  "include_comments": true,
  "max_comments": 5
}

4.列表_事件_元数据

获取全面的存储库元数据和贡献指南指针。

此工具提供有用的上下文 在使用存储库之前，包括：

• 存储库统计数据（星、叉、观察者）
• 默认分支和主要语言
• 许可证信息
• 克隆HTTPS和SSH的URL
• 贡献指南指针 （贡献.md、代码_OF_CONDUCT.md、开发.md等）

主要特征：贡献指导指针: 该回复包括 contribution_guides 列出要查看的常见文档文件的部分：

• 贡献.md -如何贡献和公关流程
• 代码_OF_CONDUCT.md -社区标准和期望
• Developpent.md -设置和开发信息
• 开发商.md -替代发展指南
• .github/CONTRIBUTING.md -GitHub特定指南

这有助于开发人员了解项目的标准 在进行更改之前.

参数:

• repo：“所有者/仓库”格式的仓库

示例:

{
  "repo": "microsoft/vscode"
}

响应包括:

{
  "success": true,
  "repo_name": "vscode",
  "owner": "microsoft",
  "stars": 156000,
  "language": "TypeScript",
  "contribution_guides": {
    "message": "Review these files to understand how to contribute to this project",
    "common_files": {
      "CONTRIBUTING.md": "https://github.com/microsoft/vscode/blob/main/CONTRIBUTING.md",
      "CODE_OF_CONDUCT.md": "https://github.com/microsoft/vscode/blob/main/CODE_OF_CONDUCT.md",
      "DEVELOPMENT.md": "https://github.com/microsoft/vscode/blob/main/DEVELOPMENT.md"
    }
  }
}

5.prepare_clone

克隆前验证文件夹路径。

参数:

• target_path：验证路径（绝对或相对）
• must_be_empty：文件夹是否必须为空（默认值：true）

示例:

{
  "target_path": "/home/user/projects/new-repo",
  "must_be_empty": true
}

6.clone_repo

将存储库克隆到本地目录- 需要用户确认.

⚠️ 关键的：克隆前，用户必须明确确认。不要走一条路。

参数:

• repo：“所有者/仓库”格式的仓库
• target_path：要克隆到的本地路径（用户必须指定此路径）
• confirmed：必须是 true 继续（默认值： false) - 所需的安全检查点
• clone_method：“https”或“ssh”（默认为“https”）
• shallow：是否进行浅层克隆（默认值：false）
• branch：要结账的特定分行（可选）

所需工作流:

1. 向用户呈现两个选项：

- 选项A：克隆到他们提供的特定路径 - 选项B：克隆到当前工作区

1. 获取明确的用户确认：“是否要继续？（是/否）”
2. 只有当用户确认后，才能呼叫 clone_repo 随着 confirmed=true

示例-用户确认后:

{
  "repo": "torvalds/linux",
  "target_path": "/home/user/projects/linux",
  "confirmed": true,
  "clone_method": "https",
  "shallow": true
}

未确认（将返回错误）:

{
  "repo": "torvalds/linux",
  "target_path": "/home/user/projects/linux",
  "confirmed": false
}

返回错误： CONFIRMATION_REQUIRED

7.公关助理

获取创建拉取请求的分步指导，重点是查看存储库的 贡献指南.

主要特点:

• 创建PR的分步说明
• 用于测试、提交和推送更改的Git命令
• 使用GitHub web界面或CLI的指南
• 重要：指示您查看CONTRIBUTING.md、CODE_OF_CONDUCT.md和其他投稿指南
• 常见问题的故障排除提示

为什么贡献指南很重要: 指南 强调检查存储库的贡献准则 （贡献.md、代码_OF_CONDUCT.md、开发.md）因为：

• 不同的项目对代码格式、测试和文档有不同的要求
• 以下指南可确保您的PR在第一次审核时被接受
• 某些项目需要特定的提交消息格式或分支命名约定
• 遵守行为准则对维护人员至关重要

参数:

• local_repo_path：本地存储库的路径
• base_branch：要合并到的基本分支（默认值：“main”）
• head_branch：您的分支有变化
• pr_title：拟议的PR标题
• pr_body：拟议的PR描述
• fork_flow：是否使用fork工作流（默认值：true）

示例:

{
  "local_repo_path": "/home/user/projects/my-repo",
  "base_branch": "main",
  "head_branch": "feature/my-improvement",
  "pr_title": "Add new feature X",
  "pr_body": "This PR adds feature X which solves issue #123",
  "fork_flow": true
}

示例输出包括:

## ⚠️ IMPORTANT: Review Contribution Guidelines

Before creating your PR, check the repository's contribution guidelines:

1. Look for these files in the repository:
   - **CONTRIBUTING.md** - Contribution process and standards
   - **CODE_OF_CONDUCT.md** - Community standards and behavior
   - **DEVELOPMENT.md** - Setup and development instructions
   
2. These files explain:
   - How to format code and commit messages
   - Testing requirements
   - Documentation standards
   - PR review process

8.create_pull_request（可选-需要令牌）

通过GitHub API自动创建拉取请求。

参数:

• repo：“所有者/仓库”格式的仓库
• head：分支名称或分叉的“用户名：分支”
• base：要合并到的基础分支
• title：PR标题
• body：PR描述（可选）
• draft：创建为草稿（默认值：false）
• token：GitHub PAT（可选，如果未提供，则使用GitHub_TOKEN env）

示例:

{
  "repo": "facebook/react",
  "head": "myusername:fix-bug",
  "base": "main",
  "title": "Fix rendering bug in component",
  "body": "Fixes #12345",
  "draft": false
}

9.fork_repo（可选-需要令牌）

将存储库分叉到您的帐户。

参数:

• repo：“所有者/仓库”格式的仓库
• token：GitHub PAT（可选，如果未提供，则使用GitHub_TOKEN env）

示例:

{
  "repo": "microsoft/vscode"
}

环境变量

• GITHUB_TOKEN：GitHub个人访问令牌（可选但推荐）

- 将速率限制从每小时60个请求增加到5000个请求 - 需要 create_pull_request 和 fork_repo 工具 - 获取一个：https://github.com/settings/tokens

日志记录

服务器包括结构化日志记录，以帮助调试和监控。

默认行为

默认情况下，服务器在以下位置登录 INFO 级别到stdout：

2025-01-09 14:23:45,123 - src.server - INFO - GitHub Issue Shepherd MCP Server initialized
2025-01-09 14:23:45,124 - src.server - INFO - GitHub token configured
2025-01-09 14:23:46,234 - src.github.client - INFO - Searching GitHub issues: python good-first-issue...

启用调试日志记录

要查看详细的调试信息（包括HTTP请求和参数详细信息）：

# Set environment variable
export PYTHONUNBUFFERED=1
export DEBUG=1

# Run server with debug logging
python src/server.py

或者在中修改服务器初始化 src/server.py:

from src.utils.logging_config import setup_logging
import logging

setup_logging(log_level=logging.DEBUG)

记录到文件（可选）

要将日志保存到stdout之外的文件中，请执行以下操作：

from src.utils.logging_config import setup_logging
import logging

setup_logging(
    log_level=logging.INFO,
    log_file="github_shepherd.log"
)

记录的内容:

• 服务器启动和配置
• 搜索查询和结果计数
• API请求和响应
• 速率限制状态和警告
• 所有具有完整上下文的错误
• Git操作执行和结果

速率限制

GitHub API有速率限制以防止滥用：

限制

超出限制时会发生什么

1. 工具返回标准化错误响应:

   {
     "ok": false,
     "error": {
       "code": "GITHUB_RATE_LIMIT",
       "message": "GitHub API rate limit exceeded",
       "hint": "Set GITHUB_TOKEN environment variable for higher rate limits (5000/hr vs 60/hr)",
       "details": {
         "limit_remaining": 0,
         "resets_at": 1673280000
       }
     }
   }

1. 服务器记录警告:

   WARNING - Approaching GitHub API rate limit: 6/5000 remaining
   ERROR - Rate limit exceeded. Reset at: 1673280000

1. 操作已暂停 -重置时间后重试

如何解决

立即：等待速率限制重置（未经身份验证为每小时，搜索为1分钟）

永久的：设置GitHub令牌

1. 首选https://github.com/settings/tokens
2. 生成新令牌（经典）
3. 选择范围： repo, workflow （如果使用自动化）
4. 复制并设置为环境变量：

   export GITHUB_TOKEN=ghp_your_token_here

1. 重新启动服务器

监视器：检查服务器日志中的速率限制警告，并在需要时调整搜索模式

典型工作流程

选项1：您还没有想到存储库

1. 发现热门存储库 符合您的兴趣：

{
  "language": "python",
  "topics": ["machine-learning"],
  "sort": "stars",
  "limit": 10
}

这显示了维护良好的项目（1000+颗星，100+贡献者，活跃）。

1. 选择存储库 根据结果，继续执行选项2中的步骤3

选项2：您已经知道要使用哪个存储库

1. 找到一个需要解决的问题 在该存储库中：

{
  "repo": "owner/repo",
  "skills": ["python", "testing"],
  "difficulty": "good-first-issue",
  "limit": 10
}

1. 获取问题详细信息:

{
  "repo": "owner/repo",
  "number": 123,
  "include_comments": true
}

1. 检查存储库元数据:

{
  "repo": "owner/repo"
}

1. 准备一个文件夹:

{
  "target_path": "/home/user/dev/new-project",
  "must_be_empty": true
}

1. 克隆仓库:

{
  "repo": "owner/repo",
  "target_path": "/home/user/dev/new-project",
  "clone_method": "https"
}

1. 进行更改 （在MCP之外-使用IDE/编辑器）

1. 获取公关创建指导:

{
  "local_repo_path": "/home/user/dev/new-project",
  "base_branch": "main",
  "head_branch": "fix/issue-123",
  "pr_title": "Fix issue #123",
  "pr_body": "This fixes the bug described in #123"
}

1. 可选择自动创建PR （如果你有代币）：

{
  "repo": "owner/repo",
  "head": "yourname:fix/issue-123",
  "base": "main",
  "title": "Fix issue #123",
  "body": "Fixes #123"
}

为开源做出贡献：理解存储库指南

为什么存储库指南很重要

在对任何存储库进行更改之前 关键的 了解该项目的具体贡献要求。不同的项目对以下方面有不同的标准：

• 代码样式和格式Python、JavaScript和Go有不同的约定
• 测试要求：有些需要100%的覆盖率，有些还没有测试
• 提交消息格式：有些强制使用特定的前缀，如 fix: 或 feat:
• PR审查流程：有些有多个审阅者，有些则更宽容
• 文件标准：有些需要每次更改的文档，有些则不需要
• 社区标准：行为准则的期望差异很大

此服务器如何提供帮助

此MCP服务器包括 查找和审查贡献指南的内置指南:

1. list_repo_metadata 提供直接链接到：

- 贡献.md-贡献过程 - CODE_OF_CONDUCT.md-社区标准 - DEVELOPMENT.md-开发设置 - 其他捐助资源

1. pr_assistant 强调检查指南 之前 创建一个PR，并有一个专门的部分：

   ## ⚠️ IMPORTANT: Review Contribution Guidelines

   Before creating your PR, check the repository's contribution guidelines:

   1. Look for these files in the repository:
      - CONTRIBUTING.md
      - CODE_OF_CONDUCT.md
      - DEVELOPMENT.md

   2. These files explain:
      - How to format code and commit messages
      - Testing requirements
      - Documentation standards
      - PR review process

最佳实践工作流程

1. discover_repository() or identify repo you want to work on
2. list_repo_metadata()  ← Review contribution guides here
3. search_issues()       ← Find an issue to work on
4. get_issue_details()   ← Understand the problem
5. clone_repo()          ← Only after understanding requirements
6. [Make your changes locally in your editor]
7. pr_assistant()        ← Reviews guidelines again before PR
8. create_pull_request() ← Create PR

关键的原则：在修改代码之前，请务必阅读贡献指南。这可以防止在因格式或样式问题而无法接受的PR上浪费时间。

故障排除

找不到Git

错误: Git is not installed or not found in PATH

解决方案:

1. 从以下位置安装Githttps://git-scm.com/downloads
2. 确保Git在您的系统PATH中
3. 重新启动终端/shell
4. 通过以下方式进行验证： git --version

请求频率超限

错误: GitHub API rate limit exceeded

解决方案:

1. 设置GitHub个人访问令牌
2. 导出为 GITHUB_TOKEN 环境变量
3. 重新启动MCP服务器
4. 未经身份验证：60个请求/小时
5. 已验证：5000次请求/小时

目录非空

错误: Directory is not empty

解决方案:

1. 选择其他空目录
2. 或者手动清除目录
3. 或使用 must_be_empty: false （小心使用）

权限不足

错误: Permission denied: Cannot write to directory

解决方案:

1. 检查目录权限
2. 选择一个具有写访问权限的目录
3. 在Unix/Mac上，使用： chmod +w /path/to/directory

克隆失败-找不到存储库

错误: Repository not found or inaccessible

解决方案:

1. 验证存储库名称是否正确（所有者/仓库格式）
2. 检查存储库是否是私有的，您是否有访问权限
3. 如果使用SSH，请确保您的SSH密钥设置正确
4. 对于私有存储库，使用带有令牌的HTTPS或设置SSH密钥

测试

运行测试套件：

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/

项目结构

mcp_github_issue_shepherd/
├── pyproject.toml          # Project configuration
├── README.md               # This file
├── src/
│   ├── server.py           # Main MCP server
│   ├── config.py           # Configuration and constants
│   ├── github/
│   │   ├── client.py       # GitHub API client
│   │   ├── query_builder.py  # Search query builder
│   │   └── models.py       # Data models
│   ├── git_ops/
│   │   ├── clone.py        # Git clone operations
│   │   └── fs_validate.py  # Filesystem validation
│   ├── pr/
│   │   ├── guidance.py     # PR creation guidance
│   │   └── api.py          # Automated PR/fork operations
│   └── utils/
│       ├── errors.py       # Error handling
│       ├── logging_config.py  # Logging configuration for the MCP server
│       ├── redact.py       # Token redaction
│       └── detect_project.py  # Project type detection
└── tests/
    ├── test_query_builder.py
    ├── test_mcp_tools.py
    ├── test_fs_validate.py
    ├── test_rate_limiting.py
    └── test_redact.py

安全与安保

• ✅ 令牌从不在错误消息中记录或公开
• ✅ 文件系统操作验证路径和权限
• ✅ 克隆默认仅为空目录
• ✅ 无自动代码执行或文件修改
• ✅ 所有破坏性操作都需要明确确认

许可证

MIT许可证-有关详细信息，请参阅许可证文件

贡献

欢迎投稿！拜托：

1. 克隆该仓库
2. 创建要素分支
3. 进行更改
4. 如果适用，添加测试
5. 提交拉取请求

支持

对于问题或疑问：

1. 检查上面的故障排除部分
2. 搜索现有的GitHub问题
3. 创建一个新问题，详细说明您的问题

致谢

• 用途 MCP Python SDK 用于测试。
• 用途
• 受到使开源贡献更容易的需要的启发