# tempo-mcp

MCP server that lets Claude log, list, and delete Tempo worklogs against Jira issues.

## Setup

1. `npm install && npm run build`
2. Copy `.env.example` to `.env` and fill in:
   - `TEMPO_API_TOKEN` — generated in Jira under **Tempo → Settings → API Integration**, scoped to *Manage Worklogs*.
   - `JIRA_BASE_URL` — e.g. `https://your-domain.atlassian.net`
   - `JIRA_EMAIL` / `JIRA_API_TOKEN` — used to resolve issue keys (e.g. `PROJ-1234`) to the numeric issue IDs Tempo requires. Generate the token at https://id.atlassian.com/manage-profile/security/api-tokens.

## Register with Claude Code

```
claude mcp add tempo-mcp -- node /path/to/tempo-mcp/dist/index.js
```

Or via `.mcp.json`, with the env vars above set in the entry's `env` block.

The server validates both Tempo and Jira credentials on startup and logs a clear pass/fail message to stderr (visible in Claude Code's MCP logs) before it accepts tool calls, rather than failing confusingly on first use.

## Tools

**Worklogs**
- `get_worklogs` — list worklogs, optionally filtered by `issueKey`, `authorAccountId`, and date range (`from`/`to`).
- `post_worklog` — log time against an issue (`issueKey`, `timeSpentHours` or `timeSpentSeconds`, `startDate`, `authorAccountId`, optional `startTime`/`description`). Defaults to a dry-run preview; pass `confirm: true` to actually write it.
- `update_worklog` — change an existing worklog's time/date/description by `tempoWorklogId`. Same dry-run/`confirm: true` behavior.
- `delete_worklog` — delete a worklog by `tempoWorklogId`. Same dry-run/`confirm: true` behavior (previews the real worklog before deleting it).

**Lookups** (so Claude doesn't need issue IDs or account IDs handed to it up front)
- `whoami` — the Jira account the configured credentials belong to.
- `search_projects` — list/filter visible Jira projects.
- `search_recent_issues` — find issues by project, assignee, and/or free text, most recently updated first.

`post_worklog` requires an `authorAccountId`. Get your own via `whoami`; for others, use their Jira admin console profile URL, which shows their `accountId`. (An earlier `find_users` tool was removed — it depended on the "Browse users and groups" global permission, which returned an empty result with HTTP 200 rather than an error when missing, confirmed via direct API testing against this org's Jira instance.)

Issue keys are resolved to Tempo's required numeric issue ID automatically (and cached in-process) via the Jira REST API. Auth failures return a plain-English hint (e.g. "check JIRA_EMAIL/JIRA_API_TOKEN/JIRA_BASE_URL") instead of a raw, sometimes localized, HTTP error body.

## Safety and abuse controls

- **`authorAccountId` is allowlisted, not free-form.** `post_worklog` will only attribute a worklog to the credentialed account (from `JIRA_EMAIL`/`whoami`) unless `AUTHORIZED_AUTHOR_ACCOUNT_IDS` in `.env` explicitly lists other account IDs. This exists specifically so that content Claude reads from a Jira issue or Tempo worklog description can't talk it into logging fabricated time against an arbitrary third party — the allowlist is controlled by you, in `.env`, not by anything the model reads.
- **Every write is dry-run by default.** `post_worklog`, `update_worklog`, and `delete_worklog` all preview what they would do and require an explicit `confirm: true` to actually execute.
- **`MAX_WRITES_PER_SESSION`** (default 20) caps how many writes a single running server process will perform before refusing further ones, as a blast-radius limit against a runaway or manipulated conversation. Restart the server to reset the count.
- **Local audit log.** Every `post_worklog`/`update_worklog`/`delete_worklog` call (success or failure) is appended as a JSON line to `logs/audit.jsonl` (gitignored) — a local record of what was written, independent of Tempo's own history.
- Keep `.env` file permissions restricted, especially on a shared machine — it holds both the Tempo API token and Jira Basic-auth credentials in plaintext.