@overdoser/timeline-mcp

MCP server for CRK Timeline: lets AI agents report implementation stages (or any events) onto a live manifest timeline. Single self-contained file — no install step beyond npx.

Setup

Add to your project's .mcp.json (Claude Code, or any MCP client):

{
  "mcpServers": {
    "timeline": {
      "command": "npx",
      "args": ["-y", "@overdoser/timeline-mcp"],
      "env": {
        "TIMELINE_URL": "https://timeline.overdoser.org",
        "TIMELINE_API_KEY": "tlt_…"
      }
    }
  }
}

Create the tlt_… ingest key under Applications in the timeline UI. TIMELINE_URL may also point at a local relay (http://localhost:7740, image cracoidic/timeline-relay) — same contract, and the key becomes optional when the relay holds one.

Tools

• timeline_send — record one finished step (op, status, properties…).
• timeline_begin — start a stage; it renders as a growing dashed bar live.
• timeline_complete — close that stage (same key): one bar, real duration.

Which manifest do events land on?

Per call: the manifest argument wins → else the TIMELINE_MANIFEST env → else <project-folder>-<YYYY-MM-DD> derived from the working directory the MCP client launched the server in. One shared config therefore separates projects (and days) automatically; the computed default is shown to the agent in the tool schema.

Optional env: TIMELINE_SERVICE — the event lane/color (default agent).