AgentIssueTracker

AgentIssueTracker

An MCP (Model Context Protocol) server for tracking issues across multiple AI agent sessions. Agents can file issues, claim the next one to work on, return issues they cannot complete, and close issues when done. A built-in web UI lets you monitor progress in a browser.

Contents

• Overview
• Prerequisites
• Installation
• Running the server
• Testing
• Configuring in Claude Desktop
• Configuring in VS Code Copilot Chat
• Web UI
• MCP tools reference
• Agent prompt files
• Installing agent prompts
• Standalone bundle
• Environment variables

---

Overview

AgentIssueTracker runs as a single HTTP server process with two interfaces on the same port:

• MCP server over HTTP — AI agents connect to the /mcp endpoint (StreamableHTTP transport) and use eight tools to manage issues.
• Web UI — A browser-accessible table of all issues, filterable by status.

Issues move through a lifecycle that includes a code-review stage:

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

Every action taken by an agent is recorded in the issue's history log, so you can see exactly which agent did what and when.

---

Prerequisites

• Node.js 20 or later
• One or more of:
• Claude Desktop (any plan)
• VS Code with the GitHub Copilot Chat extension (Copilot Pro, Teams, or Enterprise)

---

Installation

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

The build step compiles TypeScript to dist/. You only need to repeat it when source files change.

---

Running the server

The server runs independently and clients connect to it over HTTP. Start it before configuring your MCP client:

# 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

Startup output appears on 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 is created automatically the first time an issue is added.

---

Testing

Unit tests are written with Vitest and cover the storage layer, all issue store operations (including the read-only listIssues query), and the web server routes.

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

| Test file | What's covered | |---|---| | src/storage.test.ts | loadIssues / saveIssues — missing file, JSON round-trip, atomic .tmp→rename write | | src/issueStore.test.ts | addIssue, listIssues (status/classification filters), peekNextIssue (classification priority, fall-through, read-only), getNextIssue (FIFO + classification filter), completeIssue, getNextReviewItem, returnIssue, closeIssue — status transitions, history, comments, error cases | | src/webServer.test.ts | GET /, GET /?status=, GET /health — HTML content, status filter, invalid filter fallback, XSS escaping |

---

Configuring in Claude Desktop

Start the server first (see Running the server), then edit %APPDATA%\Claude\claude_desktop_config.json (create it if it does not exist):

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

Restart Claude Desktop. The eight issue-tracker tools will appear in the tools list in any new conversation.

If the server runs on a non-default port, set the PORT environment variable when starting the server and update the URL accordingly:

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

---

Configuring in VS Code Copilot Chat

Start the server first (see Running the server), then create or edit .vscode/mcp.json in the project you want agents to track issues for:

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

Requirements:

• VS Code 1.98.0 or later
• GitHub Copilot Chat extension installed and signed in
• A Copilot plan that includes MCP support (Pro, Teams, or Enterprise)

Once configured, switch Copilot Chat to Agent mode (the drop-down next to the text field). The issue-tracker tools will be available automatically. You can ask Copilot naturally — for example:

"File a bug issue for the login crash we just found." "What issues are currently in progress?" "Pick up the next issue and work on it."

To share the configuration with your team, commit .vscode/mcp.json to source control.

---

Web UI

Open http://localhost:3000 in a browser while the server is running.

The page shows all issues in a table with columns for ID, title, type, status, dates, last agent activity, and comments. Use the filter buttons at the top to show only issues in a particular status:

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

The page auto-refreshes every 30 seconds. A /health endpoint returns a JSON summary:

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

---

MCP tools reference

add_issue

Create a new issue. Status is set to created.

| Parameter | Type | Description | |---|---|---| | title | string | Short summary | | description | string | Full description | | classification | bug \| improvement \| feature | Issue category | | agent | string | Your agent's name (recorded in history) |

list_issues

List issues matching optional filters. This is a read-only query — it does not claim or modify any issues. Useful for checking queue sizes before deciding what to do next.

| Parameter | Type | Description | |---|---|---| | status | created \| in_progress \| completed \| in_review \| closed \| rejected (optional) | Only include issues with this status | | classification | bug \| improvement \| feature (optional) | Only include issues of this type | | skip | integer >= 0 (optional) | Number of matching issues to skip (for pagination). Defaults to 0 | | take | integer >= 1 (optional) | Maximum number of issues to return. Omit to return all remaining |

Returns a JSON object with count (number of returned issues) and issues (array of summaries with id, title, classification, status, createdAt).

peek_next_issue

Preview the next available issue by classification priority without claiming it. Checks classifications in the order given and returns the oldest created issue matching the first classification with available issues. If none match, falls through to the next classification. This is read-only — it does not change issue status.

| Parameter | Type | Description | |---|---|---| | classifications | array of bug \| improvement \| feature | Ordered list of classifications to check (at least one required) |

get_next_issue

Claim the oldest available issue (FIFO). Status changes to in_progress. Returns the full issue as JSON, or a message if no issues are available. When classification is provided, only issues of that type are considered — this lets developer agents prioritize bugs over improvements over features.

| Parameter | Type | Description | |---|---|---| | agent | string | Your agent's name (recorded in history) | | classification | bug \| improvement \| feature (optional) | Only consider issues of this type |

return_issue

Return an issue you cannot complete. Status reverts to created so another agent can pick it up.

| Parameter | Type | Description | |---|---|---| | issue_id | UUID string | The issue to return | | comment | string | Why you are returning it | | agent | string | Your agent's name (recorded in history) |

complete_issue

Mark an issue as completed and ready for code review. Status changes to completed. The developer agent calls this after finishing work, instead of closing the issue directly.

| Parameter | Type | Description | |---|---|---| | issue_id | UUID string | The issue to complete | | comment | string | Summary of the work done | | agent | string | Your agent's name (recorded in history) |

get_next_review_item

Claim the oldest completed issue for review (FIFO). Status changes to in_review. Returns the full issue as JSON, or a message if no issues are ready for review.

| Parameter | Type | Description | |---|---|---| | agent | string | Your agent's name (recorded in history) |

close_issue

Mark an issue as done. This is a terminal state — closed issues cannot be reopened via the API. In the review workflow, the code-reviewer agent calls this after reviewing an in_review issue.

| Parameter | Type | Description | |---|---|---| | issue_id | UUID string | The issue to close | | resolution | closed \| rejected | Final status | | comment | string | What was done or why it was rejected | | agent | string | Your agent's name (recorded in history) |

---

Installing agent prompts

Two helper scripts are included to copy the agent prompt files to where Claude Code can find them. Both scripts list the files and destination, then ask for confirmation before copying.

Bash (macOS / Linux / Git Bash on Windows):

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

# Install to a specific project directory (<path>/.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 (<path>\.claude\agents\)
.\install-agents.ps1 C:\path\to\your\project

When no argument is given, the agents are installed globally and will be available in every Claude Code session. When a project path is given, they are installed into that project's .claude/agents/ directory and will only be available when working in that project.

---

Standalone bundle

If you want to run the server without cloning the repository or installing dependencies, you can produce a single-file bundle:

npm run bundle

This uses esbuild to package all source code and dependencies into dist/agent-issue-tracker.cjs (~1 MB). Copy this file anywhere and run it with Node.js 20+:

node agent-issue-tracker.cjs

No npm install or node_modules directory is needed — just the one file and node. Then configure your MCP client to connect to http://localhost:3000/mcp (see Configuring in Claude Desktop).

---

Agent prompt files

The artifacts/agents/ directory contains prompt files for four agents designed to work with this issue tracker. See that directory for details. Quick summary:

| Agent | Purpose | |---|---| | team-lead | Monitors all queues and dispatches subagents in priority order — reviews first, then bugs, improvements, features | | developer | Picks up issues (bugs first, then improvements, then features), implements them, and marks them completed for review | | code-reviewer | Picks up completed issues for review, then closes or rejects them | | bug-fixer | Picks up the next bug issue, investigates and fixes it, closes or returns it |

The team-lead is the coordination layer. It uses list_issues to check queue sizes without claiming anything, then spawns the appropriate worker agent (developer, bug-fixer, or code-reviewer) via the Task tool. Run it to process an entire backlog hands-free.

Invoke them explicitly in Claude Code with /agents or by asking Claude to use a specific agent, for example:

"Use the team-lead agent to process the issue backlog." "Use the code-reviewer agent to review my staged changes." "Use the bug-fixer agent to work on the next bug."

---

Environment variables

| Variable | Default | Description | |---|---|---| | PORT | 3000 | Port for the web UI and MCP endpoint | | ISSUES_FILE | <cwd>/issues.json | Path to the data file |

Set these when starting the server (e.g. PORT=4000 npm run dev).