donetick-mcp: Instructions file for Claude Code

CLAUDE.md

Operating rules for an agent working in donetick-mcp, a stdio MCP server on Bun that manages chores on a self-hosted Donetick instance.

Critical rules

1. Imports. Use @/ for anything under src/. Inside a __tests__/ directory, use a relative import for a sibling under test (../index, ../read) and @/ for anything outside that directory. Never mix the two styles in a single non-test file; production code always uses @/.

2. Testing. Tests live in __tests__/ co-located with the source they cover, use bun:test, and run with bun test --isolate. Never sleep in a test. Every module that depends on time takes an injected clock (a now: () => Date or now: () => number) precisely so a test can pass a fixed instant instead of waiting on a real one. A test that cannot fail is worse than none, because it reports coverage that does not exist. After writing one, revert the behavior it covers and confirm it fails.

3. I/O boundaries, under src/. src/client.ts is the only module that touches the network. src/cache.ts and src/probe.ts are the only ones that hold state, and both hold it in an instance created once at startup, never at module scope. Every other module takes its clock and its data as arguments and holds nothing. scripts/ is outside this: it fetches and keeps state directly, because it is a CLI and not the server.

4. MCP boundary. Only src/index.ts may import @modelcontextprotocol/server. Tool definitions elsewhere are plain data: a name, a description, a zod raw shape for the input, and a handler function. Anything constructed inside the server factory in src/index.ts has per-connection lifetime, so the DonetickService and its caches are built once outside the factory and closed over, not rebuilt per connection.

5. Never guess a wire field name. Donetick's internal /api/v1 ships a swaggo spec at docs/swagger.json, with a basePath of /api/v1 and its Swagger UI mounted by default on a self-hosted instance, but the spec lies: it omits includeSubtasks, syncVersion, actionOptions and draftId; it marks isPrivate required when Donetick accepts its absence; and it states a 0..5 priority bound on PUT /chores while missing the real 0..4 bound Donetick enforces on PUT /chores/:id/priority. It carries no behavioral semantics at all. A wrong field name on a write often produces a 200 with the wrong effect rather than an error, so check src/types.ts, src/endpoints.ts, and, when in doubt, the live instance before trusting a guess. A bound enforced on input is not enforced on data already stored. Whatever the input schema refuses, the checks that read a stored shape must refuse too.