MCP server

The read-only MCP (Model Context Protocol) server exposed by tadoru mcp — tools, schemas, errors, and registration.

tadoru mcp exposes recorded activity to MCP clients — terminal agents (Claude Code, Codex, opencode, Hermes) and, crucially, shell-less clients (Claude Desktop, ChatGPT connectors) for which MCP is the only path.

Role and boundary. The server is a read-only view over the local store. It runs as an independent process from the recording daemon and cannot start or stop recording, and cannot change configuration — including the capture-time filters. The app / bundle_id arguments of query_events are query-time narrowing over already-stored data, not a privacy boundary.

Shared conventions — time expressions, event types, the event envelope — match the CLI reference and event reference.

Tools

All three tools are read-only and side-effect free.

get_timeline

Returns the LLM-ready timeline for a range. Equivalent to tadoru timeline. The tool agents call most.

Input

Output (format: "markdown")

{
  "range": { "since": "2026-08-16T08:00:00Z", "until": "2026-08-16T09:00:00Z" },
  "format": "markdown",
  "content": "## 08:12-08:31 Safari — Reviewing PR #42\n- Viewed 3 files on GitHub\n- Wrote 2 comments\n...",
  "token_estimate": 3810,
  "truncated": false
}

With format: "structured", the result matches the sessions[] structure of timeline --format json in the CLI reference.

query_events

Returns raw events matching the given conditions. Equivalent to tadoru query. For fine-grained verification or extracting specific apps/types.

Input

Output

{
  "range": { "since": "2026-08-16T08:45:00Z", "until": "2026-08-16T09:00:00Z" },
  "count": 42,
  "truncated": false,
  "events": [
    {
      "v": 1, "id": "evt_01J...", "ts": "2026-08-16T08:46:12.120Z", "mono_ns": 128374651234,
      "source": "macos.applescript", "type": "browser.navigate",
      "app": { "name": "Google Chrome", "bundle_id": "com.google.Chrome", "pid": 501 },
      "window": { "title": "PR #42", "id": 42 },
      "element": null,
      "data": { "url": "https://github.com/...", "tab_title": "PR #42", "mode": "normal" },
      "redaction": { "applied": false, "rules": [] }
    }
  ]
}

truncated: true when limit was exceeded. Event contents are already privacy-processed at capture time (secure-field exclusion, redaction) — the MCP layer never adds back anything that was excluded.

get_status

Lightweight check for agents: is recording running? A subset of tadoru status.

Input: none ({})

Output

{
  "running": true,
  "paused": false,
  "last_event_ts": "2026-08-16T08:59:58Z",
  "events_dropped": 2,
  "degraded": { "eventtap": "1 degraded collector operation observed" },
  "retention_hours": 48,
  "oldest_event_ts": "2026-08-14T09:00:00Z",
  "capture": { "sources": ["app", "window", "ui", "input", "browser"], "text_content": false },
  "permissions_ok": true
}

An agent that sees running: false can tell the user that activity is not currently being recorded, instead of answering from nothing.

Errors

The MCP server never starts recording or grants permissions. The resolution path for permission problems is the CLI: tadoru doctor (the shipped skills say so explicitly).

Registration

tadoru setup --agent <name> automates all of the below — see agent setup for per-client walkthroughs. The generic stdio-server JSON shape:

{
  "mcpServers": {
    "tadoru": {
      "command": "tadoru",
      "args": ["mcp"]
    }
  }
}

Future extensions

Not provided today; all would sit on the same read-only store view, and write access to the recording daemon will never be added:

• resources — the recent timeline and current configuration as read-only MCP resources (some clients prefer resources over tools).
• prompts — a server-provided “resume my work” prompt template.
• notifications — push on new-session detection, if demand appears.

Security boundary

• The server itself performs no external transmission (stdio only, no network surface).
• Once an agent receives tool results, forwarding them to an LLM provider is the agent’s responsibility. Given the sensitivity of activity history, the shipped skill files instruct agents to narrow the requested range before sending.
• Stored content is privacy-processed at capture time; with the default text_content: false, typed content simply does not exist in the store.