内容
# gh-issue-to-pr-mcp
[](https://github.com/huzaifaali14/gh-issue-to-pr-mcp/actions/workflows/ci.yml)
[](LICENSE)
用于 **Claude Code** 的本地 MCP 服务器，处理将问题转化为 PR 的机械且容易出错的部分：创建分支、运行构建/类型检查/ lint 命令、检查合并冲突、在推送前、提交、推送和开启 PR。
**编写实际的代码修复不是此服务器的任务** — 这仍然是正常的 Claude Code 代理工作（Claude 通过 `get_issue` 读取问题，使用其通常的工具编辑文件，然后使用其余工具进行提交）。如果您有自己的 PR 标题/描述约定（Claude Code 技能、`CONTRIBUTING.md`、PR 模板），请指向它们 — `create_pull_request` 只需提交给定的 `title`/`body`，它不会自行编写。
## 它不做的事情
- 它不编写代码。`get_issue` 向 Claude 提供问题文本；Claude 自身编辑文件。
- 它不强制推送、重写历史记录或自动解决冲突 — `check_conflicts` 仅使用 `git merge-tree` **检测**冲突（只读）。
- 它从不运行在有未提交更改的工作树上 — `create_branch_for_issue` 拒绝切换分支。
## 要求
- Node.js >= 18
- 已安装并认证 [`gh`](https://cli.github.com) 命令行工具（`gh auth login`）— 用于读取问题和开启 PR
- 具有 `origin` 远程仓库的 Git 仓库
## 安装
```bash
git clone https://github.com/huzaifaali14/gh-issue-to-pr-mcp.git
cd gh-issue-to-pr-mcp
npm install
npm run build
```
## 在 Claude Code 中注册
```bash
claude mcp add gh-issue-to-pr -- node /absolute/path/to/gh-issue-to-pr-mcp/dist/index.js
```
或者直接将其添加到您的 Claude Code MCP 配置中（例如，仓库中的 `.mcp.json` 或您的全局配置）：
```json
{
"mcpServers": {
"gh-issue-to-pr": {
"command": "node",
"args": ["/absolute/path/to/gh-issue-to-pr-mcp/dist/index.js"]
}
}
}
```
默认情况下，服务器在启动的目录（Claude Code 的 cwd，即您的仓库）上运行。要将其固定到特定的 checkout，无论 cwd 如何，请设置：
```json
{
"mcpServers": {
"gh-issue-to-pr": {
"command": "node",
"args": ["/absolute/path/to/gh-issue-to-pr-mcp/dist/index.js"],
"env": { "GH_ISSUE_TO_PR_MCP_REPO_ROOT": "/absolute/path/to/your/repo" }
}
}
}
```
## 配置您的构建/类型检查/lint 命令
开箱即用，服务器自动检测您的构建/类型检查/lint/测试命令 — 无需配置。如果自动检测不适合您的设置，请在您的仓库根目录下放置一个 `.issue-to-pr.json`，并显式指定命令：
```json
{
"baseBranch": "main",
"commands": {
"build": "npm run build",
"typecheck": "npm run typecheck",
"lint": "npm run lint",
"test": "npm test"
}
}
```
您只需要包含要覆盖的检查 — 任何省略的检查仍会默认自动检测。有关起点，请参见此文件夹中的 `.issue-to-pr.example.json`。
**每项检查的解析顺序**，从最高优先级到最低优先级：
1. 在 `run_checks` 工具调用中传递的显式 `commands` 覆盖
2. 仓库根目录下的 `.issue-to-pr.json`（上面的文件）
3. 自动检测 — 检查整个仓库（包括 monorepo/workspace 设置）中的 `package.json` 脚本，并选择一个跨所有软件包运行检查的命令，而不是手动循环。
在不实际运行任何操作的情况下运行 `detect_checks` 以查看已找到/配置的内容。
## 工具
| 工具 | 用途 |
|---|---|
| `get_issue` | 按编号、`#N` 或 URL 获取问题标题/正文/标签 |
| `create_branch_for_issue` | 获取基准、验证干净树、创建/切换 `issue-N-slug` 分支 |
| `detect_checks` | 报告将要使用的构建/类型检查/lint/测试命令及其原因 |
| `run_checks` | 运行一个或多个检查，返回每个检查的退出代码 + 输出（默认情况下不停止第一个失败） |
| `check_conflicts` | 使用 `git merge-tree` 只读检查与基准的合并冲突 |
| `commit_and_push` | `git add -A && git commit && git push -u origin <branch>` |
| `create_pull_request` | `gh pr create`，可选地追加 `Closes #N` |
## 典型流程（Claude Code 将自然地使用这些工具）
1. `get_issue` — 读取问题
2. `create_branch_for_issue` — 分支
3. Claude 编辑文件以实现修复（正常的代理编码，不在此调用工具）
4. `run_checks` with `["build","typecheck","lint","test"]` — 迭代直到通过
5. `check_conflicts` 针对基准 — 需要时变基和解决冲突，然后重新检查
6. `commit_and_push`
7. `create_pull_request` 附带标题/正文，`closesIssue` 已设置
## 关于 `check_conflicts` 的说明
使用 `git merge-tree <merge-base> HEAD origin/<base>`，它计算合并结果而不影响工作树、索引或启动实际合并 — 可以随意调用。需要 Git 2.38+ 以获取结构化冲突报告；较旧的 Git 仍然有效，但从输出中提取冲突文件可能不太精确。
## 安全说明
- 构建/类型检查/lint/测试命令（来自 `.issue-to-pr.json`、工具调用覆盖或自动检测）通过真正的 shell 运行，因为它们被期望是您自己配置的完整 shell 命令字符串。不要将此服务器指向您不信任的仓库的 `.issue-to-pr.json`。
- 所有其他涉及自由文本或外部来源的内容 — 提交消息、问题标题/正文、PR 标题/正文、分支名称 — 直接作为 argv 传递给 `git`/`gh`，而没有 shell 插值，因此不能用于注入 shell 命令。
## 贡献
问题和 PR 欢迎 — 请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。
## License
[MIT](LICENSE)
