MCP GitHub Issue Priority Server

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行日志记录，保留30天

安装

先决条件

• Node.js 20+ - 下载
• GitHub命令行界面 （推荐）- 安装 然后跑 gh auth login

- 或者：GitHub个人访问令牌 repo 范围

从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

故障排除

配置

GitHub身份验证

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

推荐：GitHub CLI（自动）

如果你有 安装并验证后，服务器会自动检索您的令牌：

# One-time setup
gh auth login

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

备选方案：环境变量

集 GITHUB_TOKEN 带着一个 个人访问令牌 这已经 repo 范围：

export GITHUB_TOKEN="ghp_your_personal_access_token"

或者在MCP设置中配置它（见下文）。

Claude代码配置

添加 ~/.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后：

1. 跑 /mcp 查看可用的MCP服务器
2. 这 github-issue-priority 服务器应列出13个工具
3. 尝试 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分）
• 阻塞乘数：1.5倍用于“阻塞”标签问题
• 封锁处罚：对于被开放父问题阻止的问题，为0.1倍（通过GitHub子问题）
• 决胜局：较早的创建日期获胜（FIFO）

依赖性检测

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

工作流阶段

1. 选择：已选择并锁定问题
2. 研究：理解问题
3. 分支：已创建要素分支
4. 实施：代码更改正在进行中
5. 测试：运行测试和验证
6. 承诺：已提交更改
7. 公关：已创建拉取请求
8. 审查：等待审核/合并

数据存储

所有数据都存储在本地 ~/.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

棉绒

npm run lint

类型检查

npm run typecheck

发布（维护人员）

一次性设置

1. 在以下位置创建npm帐户https://www.npmjs.com/
2. 首选https://www.npmjs.com/settings/tokens
3. 创建具有“发布”权限的“自动化”令牌
4. 添加到GitHub：设置→ 秘密→ 行动→ 新秘密命名 NPM_TOKEN

创建发布

# 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、build和测试
• 创建附带tarball的GitHub版本
• 发布到npm注册表

下载跟踪

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

许可证

MIT许可证-请参阅 许可证 了解详情。

贡献

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

反馈与支持

我们很乐意收到您的来信！您的反馈有助于为每个人改进此工具。

• 问题或想法？ 开始a 讨论
• 发现bug了吗？ 打开一个问题
• 功能请求？ 打开一个问题 随着 [Feature] 在标题中
• 快速反馈？ 跑 mcp-git-issue-priority --feedback 打开反馈页面

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