worklog-mcp

An MCP server that gives a coding agent somewhere to write down what it did and why.

Git already records what changed. What it doesn't record is the reasoning — why this approach over the alternative, what was tried and abandoned, what's still broken, which test run was green when the PR went up. That context lives in a chat transcript that nobody reads again.

This server gives the agent six tools to record it as it works. By default it appends JSONL to a file in your repo. Point it at an HTTP endpoint and it posts there instead.

// .mcp.json
{
  "mcpServers": {
    "worklog": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "github:aadityakushwaha/worklog-mcp"]
    }
  }
}

That's the whole setup. No account, no key, no server. Events land in .worklog/events.jsonl.

Tools

Tool	When the agent calls it
log_work	finished something meaningful — the why and any open loops
record_decision	made an architecturally consequential choice (ADR-style, with alternatives and consequences)
report_test_run	ran a suite — result and counts, not full logs
link_pr	opened or merged a pull request
update_progress	set a work item's status: not_started / in_progress / blocked / done
sync_doc	pushed a plan, spec, progress doc, runbook or research note as rendered markdown

Every event carries a sessionId shared across one agent run and a unique id per event. The agent never passes either — they're threaded automatically, so one run's events can be grouped afterwards and a retried call can be de-duplicated by the receiver.

Configuration

Variable	Default	Meaning
WORKLOG_FILE	.worklog/events.jsonl	Where to append when there's no receiver
WORKLOG_URL	—	If set, POST events here instead of writing a file
WORKLOG_API_KEY	—	Bearer token. Required when WORKLOG_URL is set

Add .worklog/ to .gitignore unless you want the log committed. Some teams do — it makes review of an agent's reasoning part of the PR.

Reading the log

It's JSONL, so the usual tools work:

# what got done, most recent first
jq -r 'select(.tool=="log_work") | "\(.at)  \(.summary)"' .worklog/events.jsonl | tail -20

# every architectural decision, with its alternatives
jq 'select(.tool=="record_decision") | {title, decision, alternatives}' .worklog/events.jsonl

# anything still blocked
jq 'select(.tool=="update_progress" and .status=="blocked")' .worklog/events.jsonl

Sending somewhere else

Set WORKLOG_URL and every event is POSTed to <WORKLOG_URL>/api/agent/events with Authorization: Bearer <WORKLOG_API_KEY>. The body is the event — tool, id, sessionId when known, and the tool's own arguments:

{ "tool": "log_work", "id": "9f2c…", "sessionId": "7a10…", "summary": "…", "intent": "…" }

Answer with:

{ "success": true, "data": { "sessionId": "7a10…", "eventId": "…" } }

The sessionId in the first response is adopted and threaded into every later call, so the receiver owns session identity rather than the client guessing at it. On { "success": false, "error": "…" } or a non-2xx, the tool call returns that error to the agent.

That's the entire contract — a single endpoint. A receiver is an afternoon's work in whatever you already run.

Making it automatic

Logging that depends on the agent remembering to log is logging that stops after a week. Wire it to a Stop hook so it fires at the end of every session:

// .claude/settings.json
{
  "hooks": {
    "Stop": [{ "matcher": "", "hooks": [{ "type": "command",
      "command": "echo 'Before finishing: call log_work with what you did and why.'" }] }]
  }
}

Development

npm install
npm run build   # tsc → dist/  (dist is committed so npx needs no build step)
npm test

Licence

MIT