AgentIssueTracker: Instructions file for Claude Code

AgentIssueTracker — Agent Context

This is an MCP server that lets AI agents track and coordinate work on shared issues. It exposes eight MCP tools over HTTP (StreamableHTTP transport) and a read-only web UI, both served from the same Node.js process on a single port.

Commands

npm run dev          # Run directly with tsx (no build step, recommended for development)
npm run dev:watch    # Same, with auto-restart on file changes
npm run build        # Compile TypeScript to dist/
npm start            # Run compiled output (requires build first)
npm run bundle       # Bundle everything into a single dist/agent-issue-tracker.cjs
npm run start:bundle # Run the single-file bundle
npm test             # Run unit tests (vitest, single pass)
npm run test:watch   # Run tests in watch mode

File Map

src/types.ts            Shared interfaces — Issue, HistoryEntry, Comment, IssueStore
src/storage.ts          JSON file persistence — loadIssues() and saveIssues()
src/issueStore.ts       Business logic — in-memory store + all eight operations (incl. read-only listIssues, peekNextIssue)
src/mcpServer.ts        MCP tool registrations — delegates to issueStore
src/webServer.ts        Express web UI — HTML table with ?status= filter
src/index.ts            Entry point — mounts MCP HTTP transport at /mcp, starts combined HTTP server
src/storage.test.ts     Tests for loadIssues() and saveIssues()
src/issueStore.test.ts  Tests for all issue store operations (incl. listIssues)
src/webServer.test.ts   Tests for HTTP routes and HTML rendering
vitest.config.ts        Vitest configuration

esbuild.config.mjs esbuild bundler configuration for single-file packaging

Runtime artefacts (not in source control):

issues.json Live data store, auto-created on first write dist/ Compiled JavaScript, produced by npm run build dist/agent-issue-tracker.cjs Single-file bundle, produced by npm run bundle

## Issue Status Lifecycle

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

Closed states (`closed`, `rejected`) are terminal — no tool transitions out of them.

## MCP Tools

| Tool | Key inputs | What it does |
|---|---|---|
| `add_issue` | title, description, classification, agent | Creates issue with status `created` |
| `list_issues` | status?, classification?, skip?, take? | Lists issues matching optional filters with pagination (read-only, no state change) |
| `peek_next_issue` | classifications (ordered array) | Returns oldest `created` issue matching first classification with results; falls through to next classification if none found (read-only, no state change) |
| `get_next_issue` | agent, classification? | Takes oldest `created` issue (FIFO, optionally filtered by classification), sets it `in_progress`, returns full JSON |
| `return_issue` | issue_id, comment, agent | Puts issue back to `created`; appends comment |
| `complete_issue` | issue_id, comment, agent | Sets issue to `completed` (ready for review); appends comment |
| `get_next_review_item` | agent | Takes oldest `completed` issue (FIFO), sets it `in_review`, returns full JSON |
| `close_issue` | issue_id, resolution, comment, agent | Sets `closed` or `rejected`; appends comment |

All mutating tools append to the issue's `history[]` array (timestamp + agent + action description). Read-only tools (`list_issues`, `peek_next_issue`) do not.

## Environment Variables

| Variable | Default | Purpose |
|---|---|---|
| `PORT` | `3000` | HTTP port for both the web UI and MCP endpoint |
| `ISSUES_FILE` | `<cwd>/issues.json` | Path to the JSON data file |

## Critical Conventions

**Prefer `console.error` for diagnostic output.** The codebase consistently uses `console.error` for all logging. (With HTTP transport stdout is no longer reserved for MCP protocol bytes, but keeping `console.error` is still good practice to avoid surprises.)

**All mutations go through `issueStore.ts`.** The web server is read-only; it calls only `getAllIssues()` and `getIssuesByStatus()`. Never add write paths to `webServer.ts`.

**Atomic saves.** `saveIssues()` in `storage.ts` writes to `issues.json.tmp` then renames it. Do not replace this with a direct `writeFile` to `issues.json` — the rename is what prevents corruption on crash.

**Module resolution requires `.js` extensions.** The project uses `"module": "NodeNext"` in tsconfig. All internal imports must end in `.js` even though the source files are `.ts`. The MCP SDK also ships as native ESM and requires this setting.

**`issueStore.ts` is a singleton.** The store is loaded once at module initialisation (`let store = loadIssues()`). Do not call `loadIssues()` again elsewhere — it reads from disk and would overwrite in-memory state.

**Test isolation for the singleton.** Because the store is module-level state, tests use `vi.doMock('./storage.js', ...)` + `vi.resetModules()` in `beforeEach` to get a fresh module (and therefore a fresh empty store) for each test. Do not add a `resetStore()` export to production code — the test pattern already handles this cleanly.

## MCP Client Configuration

The server runs independently and clients connect to it over HTTP. Start the server first:

```bash