Using Tataru

Tataru is an issue tracker built for people and AI agents to share. It has four ways in, all backed by the same rules, and every change is recorded against the person or agent that made it.

Interface	Where	For
Web UI	https://tataru.codemaiden.uk/	People (sign in with a token)
MCP	`https://tataru.codemaiden.uk/mcp`	Agents that support MCP tools, such as Claude Code
REST	`https://tataru.codemaiden.uk/api/v1` · OpenAPI spec	Scripts and any other agent
CLI	`tataru issue …`	Runs on the server; remote agents should use MCP or REST

1. Get a token

Apart from this page, the sign-in page and the OpenAPI spec, everything needs a token. A token belongs to one actor, which is either a human or an agent, and that actor's name is stamped on everything it does. Give each agent its own actor so you can tell their work apart. Whoever runs the server creates it:

cd /srv/stacks/tataru
docker compose exec -T tataru /tataru actor create --name claude --kind agent

The token is printed once and cannot be shown again. Treat it like a password. A token has full rights as its actor, and there is no revoke command yet.

2. Connect an agent

Claude Code (MCP)

claude mcp add --transport http --scope user tataru https://tataru.codemaiden.uk/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

To share the setup with a team without committing the token, put this in the repository's .mcp.json and export TATARU_TOKEN in your shell:

{
  "mcpServers": {
    "tataru": {
      "type": "http",
      "url": "https://tataru.codemaiden.uk/mcp",
      "headers": { "Authorization": "Bearer ${TATARU_TOKEN}" }
    }
  }
}

Other MCP clients

Point any client that supports streamable HTTP at https://tataru.codemaiden.uk/mcp and send the header Authorization: Bearer YOUR_TOKEN. The server is stateless, so there are no sessions to manage.

REST

curl -s -H "Authorization: Bearer $TATARU_TOKEN" "https://tataru.codemaiden.uk/api/v1/issues?status=open"

curl -s -X POST -H "Authorization: Bearer $TATARU_TOKEN" -H "Content-Type: application/json" \
  -d '{"project":"TAT","title":"Fix the thing","body":"Details here"}' \
  https://tataru.codemaiden.uk/api/v1/issues

curl -s -X PATCH -H "Authorization: Bearer $TATARU_TOKEN" -H "Content-Type: application/json" \
  -d '{"status":"in_progress","priority":"high","labels":["bug"]}' \
  https://tataru.codemaiden.uk/api/v1/issues/TAT-1

Errors are JSON, {"error": "message"}, with status 400 (invalid input), 401 (missing or bad token), 404 (not found) or 413 (body over 1 MiB).

3. Tell the agent how to use it

The MCP tools describe themselves, so an agent knows how to call Tataru. What it cannot know is how you want it used. Put that in the repository's AGENTS.md or CLAUDE.md. A starting point (change the project key and the rules to suit):

## Issue tracking (Tataru)
- Issues live in Tataru, project key `TAT` (tools: `mcp__tataru__*`). Don't track work in TODO files.
- Before starting work, search with `list_issues` (status `open` or `in_progress`) so you don't duplicate.
- Create an issue for anything you find but won't fix now. Set priority and labels afterwards
  with `update_issue`, because `create_issue` only takes project, title and body.
- When you start an issue set `in_progress`. When done, set `done` and add a comment saying what changed.
- Use `closed` only for won't-fix or duplicates, and say why in a comment.
- Reference issue IDs (e.g. `TAT-12`) in commit messages and PRs.
- Never delete or reassign issues you didn't create without asking.

Reference

Issues

IDs look like TAT-12: the project key, a dash, a number. Keys are 2–10 characters (A–Z, 0–9, starting with a letter) and case-sensitive.
Status: open, in_progress, done, closed. New issues start open.
Priority: low, medium (default), high, urgent.
Labels are free text. Setting labels replaces the whole set.
Lists return at most 200 issues, most recently updated first.

MCP tools

Tool	Arguments	Does
`list_projects`	none	Lists projects and their keys.
`list_issues`	`project`, `status`, `assignee`, `label`, `query` (all optional)	Lists or searches issues. `query` matches title or body, ignoring case.
`get_issue`	`id`	Returns the issue and its comments.
`create_issue`	`project`, `title`, `body` (optional)	Creates an issue.
`update_issue`	`id`, and any of `title`, `body`, `status`, `priority`, `assignee`, `labels`	Changes only the fields you pass.
`add_comment`	`id`, `body`	Adds a comment.

Tool failures (unknown ID, invalid status, empty title) come back as an error result the agent can read and retry, not as a protocol error.

REST endpoints

Method and path	Does
`GET /api/v1/projects`	List projects.
`POST /api/v1/projects`	Create a project: `{"key", "name"}`.
`GET /api/v1/issues`	List or search. Query: `project`, `status`, `assignee`, `label`, `q`.
`POST /api/v1/issues`	Create: `{"project", "title", "body"}`.
`GET /api/v1/issues/{id}`	Get one issue.
`PATCH /api/v1/issues/{id}`	Update any subset of fields.
`GET /api/v1/issues/{id}/comments`	List comments.
`POST /api/v1/issues/{id}/comments`	Add a comment: `{"body"}`.