MCP GitHub 问题优先级服务器

一个模型上下文协议 (MCP) 服务器，使 AI 助手能够通过确定性优先级评分和并发安全选择来管理 GitHub 问题。

快速入门

# 1. Install from npm (recommended)
npm install -g mcp-git-issue-priority

# 2. Authenticate (if not already using GitHub CLI)
gh auth login

# 3. Add to Claude Code (~/.claude.json)

{
  "mcpServers": {
    "github-issue-priority": {
      "command": "mcp-git-issue-priority"
    }
  }
}

# 4. Restart Claude Code and verify
# The MCP tools should appear when you run /mcp

功能特性

基于优先级的选择：确定性评分算法确保跨会话的问题优先级保持一致
并发安全锁：基于文件的原子锁防止多个 AI 会话选择同一个问题
引导式工作流：8 阶段工作流（选择 → 研究 → 分支 → 实现 → 测试 → 提交 → PR → 审查），并带有转换验证
自动标记：创建并管理优先级 (P0-P3)、类型 (bug, feature, chore, docs) 和状态标签
陈旧锁检测：自动检测并清理来自已终止进程的锁
审计日志：所有操作均采用 JSON Lines 格式记录，并保留 30 天

安装

前置要求

Node.js 20+ - 下载
GitHub CLI (推荐) - 安装并运行 gh auth login
- 或者：拥有 repo 权限的 GitHub 个人访问令牌

从 npm 安装 (推荐)

npm install -g mcp-git-issue-priority

安装特定版本

npm install -g mcp-git-issue-priority@1.0.0

从源码安装

git clone https://github.com/steiner385/mcp-git-issue-priority.git
cd mcp-git-issue-priority
npm install && npm link

故障排除

问题	解决方案
`command not found: mcp-git-issue-priority`	确保 npm 全局 bin 目录在你的 PATH 中：`npm bin -g`
`GitHub authentication required`	运行 `gh auth login` 或设置 `GITHUB_TOKEN`
安装期间构建错误	确保已安装 Node.js 20+：`node --version`

配置

GitHub 身份验证

服务器支持两种身份验证方法：

推荐：GitHub CLI (自动)

如果你已安装并验证了 GitHub CLI，服务器会自动获取你的令牌：

# One-time setup
gh auth login

这是推荐的方法 - 无需手动管理令牌。

替代方案：环境变量

设置 GITHUB_TOKEN 为具有 repo 权限的个人访问令牌：

export GITHUB_TOKEN="ghp_your_personal_access_token"

或者在你的 MCP 设置中进行配置（见下文）。

Claude Code 配置

添加到 ~/.claude.json (全局) 或 .claude/settings.json (项目)：

{
  "mcpServers": {
    "github-issue-priority": {
      "command": "mcp-git-issue-priority"
    }
  }
}

使用个人访问令牌而不是 GitHub CLI？ 将令牌添加到配置中：

{
  "mcpServers": {
    "github-issue-priority": {
      "command": "mcp-git-issue-priority",
      "env": {
        "GITHUB_TOKEN": "ghp_your_personal_access_token"
      }
    }
  }
}

验证安装

重启 Claude Code 后：

运行 /mcp 查看可用的 MCP 服务器
github-issue-priority 服务器应列出 13 个工具
在任何仓库中尝试 list_backlog 以确认其正常工作

可用工具

`create_issue`

创建一个带有强制优先级和类型标签的新 GitHub 问题。

Arguments:
  - title (required): Issue title
  - body (optional): Issue description
  - priority (required): P0 (critical) | P1 (high) | P2 (medium) | P3 (low)
  - type (required): bug | feature | chore | docs
  - repository (required): "owner/repo" format

`select_next_issue`

从积压工作中选择并锁定优先级最高的问题。使用确定性评分以确保选择的一致性。

Arguments:
  - repository (required): "owner/repo" format
  - type (optional): Filter by issue type
  - maxPriority (optional): Only consider issues at or above this priority

`list_backlog`

按优先级顺序列出所有未解决的问题，无需获取锁（只读）。

Arguments:
  - repository (required): "owner/repo" format
  - type (optional): Filter by issue type
  - limit (optional): Maximum issues to return (default: 20)

`advance_workflow`

将锁定问题的流程推进到下一阶段。

Arguments:
  - issueNumber (required): Issue number to advance
  - targetPhase (required): research | branch | implementation | testing | commit | pr | review
  - repository (required): "owner/repo" format
  - testsPassed (optional): Required when advancing to 'commit' phase
  - prTitle (optional): Required for 'pr' phase
  - prBody (optional): Required for 'pr' phase
  - skipJustification (optional): Required if skipping phases

`get_workflow_status`

获取锁定问题的当前工作流状态。

Arguments:
  - issueNumber (optional): Specific issue number
  - repository (optional): "owner/repo" format

`release_lock`

释放问题的锁（在完成、放弃或合并时）。

Arguments:
  - issueNumber (required): Issue number
  - reason (required): completed | abandoned | merged
  - repository (required): "owner/repo" format

`force_claim`

强制认领被其他会话锁定的问题（需要确认）。

Arguments:
  - issueNumber (required): Issue number to claim
  - confirmation (required): Must be exactly "I understand this may cause conflicts"
  - repository (required): "owner/repo" format

`sync_backlog_labels`

检测并选择性修复缺少必要优先级/类型/状态标签的问题。

Arguments:
  - repository (required): "owner/repo" format
  - mode (optional): "report" (default) to list issues, "update" to apply labels
  - defaultPriority (optional): P0 | P1 | P2 | P3 (defaults to P2)
  - defaultType (optional): bug | feature | chore | docs (defaults to feature)

在 报告模式 下，返回所有缺少标签的问题列表，并提供缺失详情。

在 更新模式 下，将默认标签应用于问题：

缺少优先级 → priority:P2 (或指定的默认值)
缺少类型 → type:feature (或指定的默认值)
缺少状态 → status:backlog

`get_pr_status`

检查拉取请求的 CI 状态、审批状态和合并状态。

Arguments:
  - repository (required): "owner/repo" format
  - prNumber (required): Pull request number to check

`bulk_update_issues`

一次性添加/移除标签并关闭/重新打开多个问题。

Arguments:
  - repository (required): "owner/repo" format
  - issues (required): Array of issue numbers (1-50)
  - addLabels (optional): Labels to add
  - removeLabels (optional): Labels to remove
  - state (optional): "open" | "closed"

`implement_batch`

开始按优先级顺序实现一批 N 个问题。返回第一个要实现的问题。

Arguments:
  - repository (required): "owner/repo" format
  - count (required): Number of issues to implement (1-10)
  - includeTypes (optional): Only include these issue types
  - excludeTypes (optional): Exclude these issue types
  - maxPriority (optional): Only P0, P1, etc.

`batch_continue`

继续批量实现。轮询 PR 合并状态，然后返回下一个问题或完成状态。

Arguments:
  - batchId (required): Batch ID from implement_batch
  - prNumber (optional): PR number for current issue

`get_workflow_analytics`

获取基于时间的工作流分析：周期时间、阶段细分、老化报告。

Arguments:
  - repository (required): "owner/repo" format
  - period (optional): "7d" | "30d" | "90d" | "all" (default: 30d)

优先级评分算法

问题使用确定性公式进行评分：

score = (basePoints + ageBonus) * blockingMultiplier * blockedPenalty

基础分：P0=1000, P1=100, P2=10, P3=1
年龄奖励：自创建以来每天 +1 分（最多 365 分）
阻塞乘数：带有 "blocking" 标签的问题乘以 1.5 倍
被阻塞惩罚：被打开的父问题阻塞的问题（通过 GitHub 子问题）乘以 0.1 倍
决胜局：创建日期较早者胜出 (FIFO)

依赖检测

具有打开的父问题（使用 GitHub 的子问题功能）的问题会自动降低优先级，并受到 0.1 倍的惩罚。这确保了被阻塞的工作会沉入积压工作的底部，直到其依赖项得到解决。一旦父问题关闭，子问题的优先级将恢复正常。

工作流阶段

selection：问题被选中并锁定
research：理解问题
branch：创建功能分支
implementation：代码更改进行中
testing：运行测试和验证
commit：提交更改
pr：创建拉取请求
review：等待审查/合并

数据存储

所有数据本地存储在 ~/.mcp-git-issue-priority/ 中：

~/.mcp-git-issue-priority/
├── locks/          # Active lock files (.lockdata)
├── workflow/       # Workflow state files (.json)
└── logs/           # Audit logs (JSON Lines format)

开发

构建

npm run build

测试

npm test

Lint

npm run lint

类型检查

npm run typecheck

发布 (维护者)

一次性设置

在 https://www.npmjs.com/ 创建一个 npm 账户
前往 https://www.npmjs.com/settings/tokens
创建一个具有 "Publish" 权限的 "Automation" 令牌
添加到 GitHub：Settings → Secrets → Actions → 新建名为 NPM_TOKEN 的 secret

创建发布

# Patch release (bug fixes): 1.0.0 → 1.0.1
npm version patch -m "Release v%s"
git push && git push --tags

# Minor release (new features): 1.0.0 → 1.1.0
npm version minor -m "Release v%s"
git push && git push --tags

# Major release (breaking changes): 1.0.0 → 2.0.0
npm version major -m "Release v%s"
git push && git push --tags

推送标签会触发发布工作流，该工作流会：

运行 lint、构建和测试
创建一个带有 tarball 附件的 GitHub 发布
发布到 npm 注册表

下载跟踪

GitHub：发布页面显示每个 .tgz 资产的下载次数
npm：https://www.npmjs.com/package/mcp-git-issue-priority 显示每周下载量

许可证

MIT 许可证 - 详情请参阅 LICENSE。

贡献

欢迎贡献！请参阅 CONTRIBUTING.md 获取指南。

反馈与支持

我们很乐意听取你的意见！你的反馈有助于为每个人改进此工具。

问题或想法？ 发起一个 Discussion
发现 Bug？ 提交一个 issue
功能请求？ 提交一个 issue，标题中包含 [Feature]
快速反馈？ 运行 mcp-git-issue-priority --feedback 打开反馈页面

在创建新问题之前，请先检查现有问题。

MCP GitHub 问题优先级服务器

快速入门

功能特性

安装

前置要求

从 npm 安装 (推荐)

安装特定版本

从源码安装

故障排除

配置

GitHub 身份验证

推荐：GitHub CLI (自动)

替代方案：环境变量

Claude Code 配置

验证安装

可用工具

create_issue

select_next_issue

list_backlog

advance_workflow

get_workflow_status

release_lock

force_claim

sync_backlog_labels

get_pr_status

bulk_update_issues

implement_batch

batch_continue

get_workflow_analytics