# Tracker — issue tracker API for agents and people

Simple issue tracker. Projects have a KEY (e.g. APP); issues get keys APP-1, APP-2, ...
Everyone is a user: people log in with a password, agents use an API token an admin created for them.
You only see projects you're a member of (admins see all). Being assigned to an issue adds you to its project.

## Auth
Every /api and /mcp request needs:  Authorization: Bearer <token>
Changes and comments are attributed to the token's user.
People: POST /api/auth/login {"username","password","device"} -> {"token","user"}

## MCP
Streamable HTTP endpoint: POST /mcp  (stateless, JSON responses)
Tools: whoami, list_users, my_inbox, list_projects, create_project, list_issues, get_issue, create_issue, update_issue, add_comment, delete_issue
  claude mcp add --transport http tracker <base-url>/mcp --header "Authorization: Bearer <token>"

## Values
status:   backlog | todo | in_progress | in_review | done | canceled
priority: none | low | medium | high | urgent
type:     task | bug | feature | idea
assignee: a username (see GET /api/users), or "" for nobody
Write @username in descriptions and comments to notify someone.

## REST (JSON in, JSON out)
GET    /api/me                            {"user", "unread"}
PATCH  /api/me                            {"name", "color", "password", "current_password"}
GET    /api/users                         everyone on the team (username, name, kind human|agent, role admin|member)
POST   /api/users                         admin: {"username","name","kind","role","password"} -> {"user","password"|"token"}
PATCH  /api/users/{username}              admin (or self): {"name","color","role","password"}
DELETE /api/users/{username}              admin
POST   /api/users/{username}/tokens       admin or self: {"label"} -> {"token"}

GET    /api/projects                      your projects (with counts per status, my_role, member_count)
POST   /api/projects                      {"name": "My App", "key": "APP", "description", "color", "icon", "members": ["claude"]}
GET    /api/projects/{KEY}
PATCH  /api/projects/{KEY}                owner: {"name", "description", "color", "icon"}
DELETE /api/projects/{KEY}                owner: deletes all its issues too
GET    /api/projects/{KEY}/members
PUT    /api/projects/{KEY}/members/{username}   owner: {"role": "owner"|"member"}
DELETE /api/projects/{KEY}/members/{username}   owner, or yourself to leave

GET    /api/issues?project=APP&status=open&assignee=me&priority=high&label=ui&type=bug&q=login
         status: comma-separated list, or "open" (not done/canceled), or "active" (todo, in_progress, in_review)
         assignee: username, "me", or "none"; q searches title/description or matches a key
POST   /api/issues                        {"project": "APP", "title": "...", "description": "markdown",
                                            "status", "priority", "type", "assignee", "labels": ["ui"], "due_date": "2026-12-31"}
GET    /api/issues/{APP-12}               includes comments and activity (history of changes)
PATCH  /api/issues/{APP-12}               any subset of the fields above; labels replaces the list
DELETE /api/issues/{APP-12}
POST   /api/issues/{APP-12}/comments      {"body": "markdown"}
DELETE /api/issues/{APP-12}/comments/{id}
GET    /api/activity?limit=50&actor=anna  latest changes in your projects (optionally by one user)
GET    /api/inbox?unread=1                your notifications (assigned, mentioned, commented, status)
POST   /api/inbox/read                    {"ids": [1,2]} | {"issue": "APP-12"} | {"all": true}
GET    /api/meta                          allowed values, users and labels
GET    /api/events                        Server-Sent Events: issue, issue_deleted, comment, project, project_deleted,
                                            members, inbox, users — each {"type","project","issue","actor"}; refetch on receipt

Errors: {"error": "invalid|not_found|forbidden|unauthorized", "message": "what to fix"}

## Working on an issue (suggested flow)
1. my_inbox, or list_issues status=active assignee=me  (or take an unassigned todo: assignee=<your username>)
2. set status=in_progress
3. comment with progress, findings, and links to commits/PRs
4. set status=in_review (a person checks it) or done