Agent Issue Tracker

Agent IssueTracker

用于跨多个AI代理会话跟踪问题的MCP（模型上下文协议）服务器。代理可以提交问题，要求下一个要处理的问题，退回他们无法完成的问题，并在完成后关闭问题。内置的web UI允许您在浏览器中监视进度。

目录

• 概述
• 先决条件
• 安装
• 运行服务器
• 测试
• 在Claude Desktop中配置
• 在VS Code Copilot聊天中配置
• 网页用户界面
• MCP工具参考
• 代理提示文件
• 安装代理提示
• 独立捆绑包
• 环境变量

______________________________________________________________________

概述

AgentIssueTracker作为单个HTTP服务器进程运行，在同一端口上有两个接口：

• 基于HTTP的MCP服务器 --AI代理连接到 /mcp 端点（StreamableHTTP传输），并使用八种工具来管理问题。
• 网页用户界面 --浏览器可访问的所有问题表，可按状态过滤。

问题在包括代码审查阶段的生命周期中移动：

created  →  in_progress  →  completed  →  in_review  →  closed
                │                │              │      →  rejected
                └────────────────┴──────────────┴──(returned)──→  created

代理采取的每个操作都记录在问题的历史日志中，因此您可以确切地看到哪个代理在何时做了什么。

______________________________________________________________________

先决条件

• Node.js 20或更高版本
• 以下一项或多项：

- 克劳德桌面（任何计划） - 带有GitHub Copilot Chat扩展的VS代码（Copilot Pro、Teams或Enterprise）

______________________________________________________________________

安装

git clone https://github.com/Rhynier/AgentIssueTracker.git AgentIssueTracker
cd AgentIssueTracker
npm install
npm run build

构建步骤将TypeScript编译为 dist/。您只需要在源文件更改时重复它。

______________________________________________________________________

运行服务器

服务器独立运行，客户端通过HTTP连接到它。在配置MCP客户端之前启动它：

# Development (no build step, recommended)
npm run dev

# Development with auto-restart on file changes
npm run dev:watch

# Production (compiled)
npm run build && npm start

启动输出出现在stderr上：

[Startup] Data file: C:\Source\Personal\AgentIssueTracker\issues.json
[Startup] Web UI:       http://localhost:3000/
[Startup] MCP endpoint: http://localhost:3000/mcp

issues.json 在首次添加问题时自动创建。

______________________________________________________________________

测试

单元测试是用 Vitest 并覆盖存储层，所有问题存储操作（包括只读 listIssues 查询）和网络服务器路由。

npm test             # Run full test suite once
npm run test:watch   # Watch mode for development

______________________________________________________________________

在Claude Desktop中配置

首先启动服务器（请参阅 运行服务器)，然后编辑 %APPDATA%\Claude\claude_desktop_config.json （如果不存在，则创建它）：

{
  "mcpServers": {
    "issue-tracker": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

重新启动克劳德桌面。这八个问题跟踪工具将出现在任何新对话的工具列表中。

如果服务器在非默认端口上运行，请设置 PORT 启动服务器时的环境变量，并相应地更新URL：

PORT=4000 npm run dev
# Client URL: http://localhost:4000/mcp

______________________________________________________________________

在VS Code Copilot聊天中配置

首先启动服务器（请参阅 运行服务器)，然后创建或编辑 .vscode/mcp.json 在项目中，您希望代理跟踪以下问题：

{
  "servers": {
    "issue-tracker": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

要求：

• VS代码1.98.0或更高版本
• GitHub Copilot聊天扩展已安装并登录
• 包括MCP支持（专业版、团队版或企业版）的副驾驶计划

配置后，将Copilot Chat切换到 代理模式 （文本字段旁边的下拉菜单）。问题跟踪工具将自动可用。你可以自然地问Copilot——例如：

“为我们刚刚发现的登录崩溃提交一个错误问题。” “目前正在处理哪些问题？” “拿起下一个问题并着手解决。”

要与您的团队共享配置，请提交 .vscode/mcp.json 源代码控制。

______________________________________________________________________

网页用户界面

打开 http://localhost:3000 当服务器运行时，在浏览器中。

该页面在表中显示所有问题，表中有ID、标题、类型、状态、日期、上次代理活动和注释列。使用顶部的筛选按钮仅显示特定状态下的问题：

http://localhost:3000?status=created
http://localhost:3000?status=in_progress
http://localhost:3000?status=completed
http://localhost:3000?status=in_review
http://localhost:3000?status=closed
http://localhost:3000?status=rejected

页面每30秒自动刷新一次。A. /health endpoint返回JSON摘要：

GET http://localhost:3000/health
→ { "status": "ok", "issueCount": 12 }

______________________________________________________________________

MCP工具参考

add_issue

创建新问题。状态设置为 created.

list_issues

列出与可选筛选器匹配的问题。这是一个只读查询，它不会声明或修改任何问题。有助于在决定下一步做什么之前检查队列大小。

返回一个JSON对象 count （退回的问题数量）和 issues （一系列摘要 id, title, classification, status, createdAt).

peek_next_issue

按分类优先级预览下一个可用问题，而不声明它。按给定的顺序检查分类，并返回最旧的 created 问题将第一分类与可用问题相匹配。如果没有匹配，则进入下一个分类。这是只读的，不会改变问题状态。

get_next_issue

申请最旧的可用问题（FIFO）。状态更改为 in_progress。以JSON格式返回完整问题，如果没有问题，则返回一条消息。当 classification 如果提供了，则只考虑该类型的问题——这使开发人员代理能够将错误优先于改进，而不是功能。

return_issue

返回您无法完成的问题。状态恢复为 created 这样另一个特工就可以把它捡起来。

complete_issue

将问题标记为已完成并准备进行代码审查。状态更改为 completed。开发人员代理在完成工作后调用此函数，而不是直接关闭问题。

get_next_review_item

申请最旧的已完成问题以供审查（FIFO）。状态更改为 in_review。以JSON格式返回完整问题，如果没有问题可供审查，则返回一条消息。

close_issue

将问题标记为已完成。这是一个终端状态-无法通过API重新打开已关闭的问题。在审阅工作流中，代码审阅者代理在审阅后调用此命令 in_review 问题。

______________________________________________________________________

安装代理提示

包含两个辅助脚本，用于将代理提示文件复制到Claude Code可以找到它们的位置。这两个脚本都列出了文件和目标，然后在复制之前要求确认。

Bash （Windows上的macOS/Linux/Git Bash）：

# Install to the global Claude Code agents directory (~/.claude/agents/)
./install-agents.sh

# Install to a specific project directory (
/.claude/agents/)
./install-agents.sh /path/to/your/project

PowerShell （Windows）：

# Install to the global Claude Code agents directory (~/.claude/agents/)
.\install-agents.ps1

# Install to a specific project directory (
\.claude\agents\)
.\install-agents.ps1 C:\path\to\your\project

当没有给出参数时，代理将全局安装，并在每个Claude Code会话中可用。给定项目路径后，它们将安装到该项目的 .claude/agents/ 目录，仅在该项目中工作时可用。

______________________________________________________________________

独立捆绑包

如果你想在不克隆存储库或安装依赖项的情况下运行服务器，你可以生成一个文件包：

npm run bundle

这使用esbuild将所有源代码和依赖项打包到 dist/agent-issue-tracker.cjs （~1MB）。将此文件复制到任何位置，并使用Node.js 20+运行它：

node agent-issue-tracker.cjs

不 npm install 或 node_modules 需要目录——只需要一个文件和 node。然后配置您的MCP客户端以连接到 http://localhost:3000/mcp （参见 在Claude Desktop中配置).

______________________________________________________________________

代理提示文件

这 artifacts/agents/ 该目录包含四个旨在与此问题跟踪器配合使用的代理的提示文件。有关详细信息，请参阅该目录。快速摘要：

这 团队领导 是协调层。使用 list_issues 在不声明任何内容的情况下检查队列大小，然后通过任务工具生成适当的工作代理（开发人员、bug修复者或代码审查者）。运行它以免提处理整个积压。

在Claude代码中明确调用它们 /agents 或者让克劳德使用特定的代理，例如：

“使用团队主管代理来处理积压的问题。” “使用代码审阅器代理来审阅我的分阶段更改。” “使用bug修复器代理来处理下一个bug。”

______________________________________________________________________

环境变量

启动服务器时设置这些（例如。 PORT=4000 npm run dev).