Ticket MCP Server

Local MCP server for the repo ticket system (file-backed).

Features

• List/get/update/move/validate tickets in tickets/
• Create new tickets with strict frontmatter validation
• Agent helpers: tickets_next_id, tickets_claim, tickets_append_worklog, tickets_reconcile
• Strict schema enforcement (rejects invalid writes)
• HTTP MCP endpoint plus optional stdio proxy

Directory Structure & State Machine

The MCP server expects a tickets/ directory in the root of your project (configured via TICKET_ROOT), containing the following subfolders that directly map to the ticket's status field. The server will strictly enforce that tickets reside in the correct folder for their status:

• tickets/pending/ → status: pending (Ready to be picked up)
• tickets/in_progress/ → status: in_progress or status: blocked (Claimed and being worked)
• tickets/awaiting_human_test/ → status: awaiting_human_test (AI work complete; needs human testing)
• tickets/done/ → status: done (Human has verified and accepted)
• tickets/archive/ → status: archived (Obsolete or old tickets)

Strict Markdown Validation

To prevent AIs from deleting context or inventing their own ticket formats, the MCP server enforces that all tickets contain specific markdown headers in their body. These headers will be automatically injected when creating a ticket via tickets_create.

Required body headers:

• ## Overview
• ## Approach (medium/high-level)
• ## Tasks / Todos
• ## Requirements (AI implementation)
• ## Human Testing Steps
• ## Key Files / Areas (notes)
• ## Questions
• ## Blockers
• ## Implementation Notes

Usage

Build:

npm install
npm run build

Start HTTP server:

npm run start

Auto-rebuild on changes (dev watch):

npm run dev

Run integration tests:

npm run test

Start stdio proxy (for MCP clients expecting stdio):

npm run stdio

Auto-restart stdio proxy on changes:

npm run stdio:dev

Note: build output lands under dist/ticket-mcp/src/ because the build includes shared schema sources.

Configuration

• TICKET_ROOT (default: repo root inferred from cwd)
• TICKET_MCP_PORT (default: 3334)
• TICKET_MCP_PATH (default: /mcp)
• TICKET_STRICT (default: true)

tickets_stats response

The tickets_stats tool returns aggregate counts plus ticket numbering metadata:

{
  "status": {
    "pending": 12,
    "in_progress": 3,
    "done": 25
  },
  "area": {
    "tooling": 10,
    "combat": 8
  },
  "epic": {
    "none": 15,
    "qa": 4
  },
  "highest_ticket_number": 42,
  "next_ticket_number": 43
}

• highest_ticket_number: highest numeric suffix parsed from existing ticket IDs (or 0 if none are numeric).
• next_ticket_number: convenience value equal to highest_ticket_number + 1.

Agent helper tools

• tickets_next_id

  • Returns highest_ticket_number, next_ticket_number, and suggested_id.
  • Optional args: prefix (default T), separator (default -), padding (default 3).

• tickets_claim

  • Claims a pending ticket, moves it to in_progress, sets claim metadata, and appends a work_log entry.
  • Requires actor; accepts id or path.

• tickets_append_worklog

  • Appends a validated work_log entry and updates updated_at.
  • Requires entry; accepts id or path.

• tickets_reconcile

  • Audits ticket invariants and optionally applies safe fixes.
  • Optional apply_fixes: true will fix common metadata/date issues and folder/status mismatches when possible.

Recommended agent workflow

Use this sequence for normal implementation flow:

// 1) Allocate a canonical new id
const next = tickets_next_id({ prefix: "T", separator: "-", padding: 3 })

// 2) Create the ticket with suggested id
tickets_create({
  id: next.suggested_id,
  title: "Example ticket",
  area: "tools",
  epic: "none",
  intent: "Why this work matters",
  requirements: ["Requirement A"],
  human_testing_steps: ["Do X"],
  constraints: ["Constraint Y"],
  key_files: ["tools/ticket-mcp/src/server.ts"],
  status: "pending"
})

// 3) Claim when work starts
tickets_claim({
  id: next.suggested_id,
  actor: "worker-ai:example",
  summary: "Starting implementation"
})

// 4) Add progress notes during execution
tickets_append_worklog({
  id: next.suggested_id,
  entry: {
    actor: "worker-ai:example",
    kind: "change",
    summary: "Implemented the core logic"
  }
})

// 5) Validate and reconcile before handoff
tickets_validate({ id: next.suggested_id })
tickets_reconcile({ id: next.suggested_id }) // preview only