@agentsworklog/mcp — Activity Monitor MCP server

A stdio MCP server that exposes the Activity Monitor to coding agents as tools. It is a thin wrapper over the REST API (ADR 0002): the API is the source of truth; this server holds no state and no business logic.

The tool set (12 tools) and its contract live in docs/mcp.md.

Configuration

The server is configured entirely by environment variables, read per call:

| Variable | Required | Default | Purpose | | --------------- | -------- | ----------------------- | --------------------------------------------------- | | AAM_API_URL | no | http://localhost:3001 | Base URL of the Activity Monitor API. | | AAM_API_TOKEN | yes | — | Bearer token; every call acts as that token's user. |

If AAM_API_TOKEN is unset the server still starts and lists its tools, but any tool call fails with a clear error — mint a token in the app (or, for local development, run the API in dev mode and use the seeded dev token).

Build & run

pnpm --filter @agentsworklog/mcp build     # compile to dist/
pnpm --filter @agentsworklog/mcp start     # run dist/index.js over stdio

During development you can run it straight from source with pnpm --filter @agentsworklog/mcp dev.

Smoke test

smoke launches the built server over stdio and asserts the tool contract (exactly 12 tools, agent-safety rule on every description). This needs no API — it exercises the real server the plugin launches, which the mocked unit tests can't reach:

pnpm --filter @agentsworklog/mcp build
pnpm --filter @agentsworklog/mcp smoke

Add a live read round-trip by pointing it at a running API and a repository the token can access:

AAM_API_TOKEN=<token> AAM_SMOKE_REPO=<owner>/<repo> \
  pnpm --filter @agentsworklog/mcp smoke

Consumed by the Claude Code plugin

The plugins/claude-code plugin registers this server (see its .mcp.json) and adds /activity:* commands and a SessionStart hook on top. See that README for the end-to-end install and verification walkthrough.