# TrucoPilot Tickets — MCP API Documentation

> **Base URL:** `https://trucopilot.com/api/mcp/v1`
> **Auth:** Bearer token in `Authorization` header (project-scoped, hashed at rest, revocable). Generate in **Settings > MCP Connection** in the TrucoPilot web UI.
> **Protocol:** MCP (Model Context Protocol) Streamable HTTP at `/mcp`. Every tool is also a REST endpoint (see table below).

## Quick Start

```bash
claude mcp add --transport http trucopilot-tickets \
  https://trucopilot.com/api/mcp/v1/mcp \
  --header "Authorization: Bearer YOUR_TOKEN_HERE"
```

Or add the same server manually under `mcpServers` in `~/.claude.json` (`"type": "http"`, the URL above, and the `Authorization` header). Then tell your AI: "Create a ticket for implementing login", "Move ticket 5 to In Process", "What's the project status?".

## Rules for LLMs / AI Agents

**You MUST follow these rules when connected to a TrucoPilot project:**

1. **First call:** always `get_project_status` — full board state (all boards, columns, tickets), documents, stats. **Use actual column names from the response; never guess them** (`list_columns` also works).
2. **Every feature is an Epic with sub-tickets.** Search for a related Epic first (`list_tickets` / `search`). If found, add a sub-ticket with `create_sub_ticket`; if not, `create_ticket` with `ticket_type: "epic"`, then sub-tickets under it. Never create standalone tickets for feature work.
3. **Epics auto-advance — only move sub-tickets.** All sub-tickets in the done column (`is_done_column: true`) → Epic auto-moves to done. Any sub-ticket in a middle column → Epic auto-moves to in-progress. All in first column → Epic stays put.
4. **Create tickets directly in the right column** via `column_name` (e.g. straight into the active column if you're starting now) — saves a `move_ticket` call.
5. **Comment after every action.** `add_comment` is REQUIRED after any update, move, or completed work — include summary, files changed, functions/classes modified. This is the audit trail.
6. **Complete sub-tickets** by moving them to the done column with a final summary comment. Last open sub-ticket done → Epic auto-completes.
7. **Bug reports: reopen, don't duplicate.** Search for the completed sub-ticket that implemented the feature; `move_ticket` it back to the active column, comment the bug, fix, complete again. Only create a new bug ticket if nothing related exists.

**Typical new-feature flow:** `get_project_status` → `create_ticket` (epic, in active column) → `create_sub_ticket`(s) → work + `add_comment` → `move_ticket` each sub-ticket to done (Epic auto-completes).

## Bootstrapping a Project from Git History

When connecting to an existing codebase for the first time, recreate the work already done so the board has history:

1. `get_project_status` to discover columns.
2. Analyze `git log --oneline --since="6 months ago"`; group commits into logical features (auth, API, UI…). One sub-ticket per meaningful piece, not per commit; skip infra/config noise.
3. For each major feature: `create_ticket` with `ticket_type: "epic"`, a description of what it does and key files, `created_at` = earliest related commit date (ISO 8601, e.g. `"2025-03-15T10:00:00"`), and `column_name` = done column if complete.
4. `create_sub_ticket` for each piece of work under its Epic (same fields; `parent_ticket_id` = the Epic).
5. `add_comment` on completed tickets summarizing what was built, files involved, current state.

Tip: `git log --format="%H %ai %s" --diff-filter=A -- "*.py"` shows when files were first added.

## MCP Tools (19 total)

Ticket IDs accept the full key, number, or UUID (`"PROJ-5"`, `"5"`). Bold params are required; all others optional.

| Tool | Params | REST | Purpose |
|------|--------|------|---------|
| `get_project_status` | — | `GET /status` | **CALL FIRST, every session/task.** Compact snapshot: project info, stats, all boards/columns (each with `name`, `is_done_column`, `ticket_count`, ticket index), 5 most-recent tickets (metadata only), documents (metadata only, except README content clipped to 3000 chars when Auto-Summary is on), labels. |
| `get_all_tickets` | — | `GET /all-tickets` | Compact index of ALL tickets (key, title, type, column, parent) with truncated AI summaries + documents clipped to 3000 chars. No descriptions/comments — use `get_ticket` for full content. |
| `list_columns` | — | `GET /columns` | All columns with `name`, `is_done_column`, `board_name`, ticket count. Check before creating/moving. |
| `create_ticket` | **title**, description, column_name, priority, ticket_type, created_at | `POST /tickets` | New ticket. `ticket_type`: `task` (default), `bug`, `story`, `epic`. |
| `create_sub_ticket` | **parent_ticket_id**, **title**, description, priority, column_name, created_at | `POST /tickets/{id}/sub-ticket` | Sub-ticket under a parent; parent auto-promotes to Epic. Priority defaults to parent's. |
| `convert_to_sub_ticket` | **ticket_id**, **epic_id** | `POST /tickets/{id}/convert-to-sub-ticket` | Re-parent a standalone ticket under an epic (epic auto-promoted). |
| `get_ticket` | **ticket_id** | `GET /tickets/{id}` | Full details incl. comments, activity, AI summary. |
| `list_tickets` | column_name, status, priority, search, limit | `GET /tickets` | Filter tickets. `status`: `open`/`completed`; `search` matches title+description. |
| `update_ticket` | **ticket_id**, title, description, priority, ticket_type, created_at | `PUT /tickets/{id}` | Update properties. **MUST `add_comment` after.** |
| `move_ticket` | **ticket_id**, **column_name** | `POST /tickets/{id}/move` | Move between columns (done = column with `is_done_column: true`). **MUST `add_comment` after.** |
| `add_comment` | **ticket_id**, **content** | `POST /tickets/{id}/comment` | Markdown comment. Required audit trail: summary, files changed, functions/classes, notes. |
| `delete_ticket` | **ticket_id** | `DELETE /tickets/{id}` | Delete permanently. |
| `search` | **query**, scope | `GET /search?q=` | Search tickets + documents. `scope`: `all` (default), `tickets`, `documents`. |
| `list_documents` | doc_type | `GET /documents` | List wiki/docs pages. `doc_type`: `readme`, `claude_md`, `wiki`, `changelog`, `custom`. |
| `get_document` | **doc_id** | `GET /documents/{slug}` | Get a document by slug or ID (e.g. `"readme"`). |
| `create_document` | **title**, content, slug, doc_type | `POST /documents` | New wiki page. |
| `update_document` | **doc_id**, title, content | `PUT /documents/{slug}` | Update a document. |
| `list_labels` | — | `GET /labels` | All project labels. |
| `list_members` | — | `GET /members` | Org members for assignment. |

Common fields: `priority` ∈ `lowest`/`low`/`medium` (default)/`high`/`highest`; `column_name` is case-insensitive and defaults to the first column; `created_at` is an ISO 8601 datetime for backdating historical imports (defaults to now). Descriptions and comments are markdown.

**MCP call example** (same shape for every tool):

```json
{ "name": "create_ticket", "arguments": { "title": "Implement OAuth login", "ticket_type": "epic", "column_name": "In Process", "created_at": "2025-06-15T10:30:00" } }
```

Also available: `GET /health` (health check), `DELETE /documents/{slug}`.