things-cloud-mcp: Instructions file for Codex

AGENTS.md

Build and test

Use the Go toolchain on PATH (on the current macOS workstation it is /opt/homebrew/bin/go).

go test ./...
go test -race ./...
go vet ./...
go build ./...

Run the same four checks in things-cloud-sdk/ after SDK changes. The server defaults to port 8080.

Environment variables:

• PORT: HTTP port.
• DATA_DIR: SQLite and credential-key directory (default data/).
• JWT_SECRET: base64 JWT signing key; generated when absent.
• CREDENTIALS_SECRET: durable high-entropy secret used to derive the AES key for Things passwords at rest. When absent, the server creates DATA_DIR/credentials.key with mode 0600.
• THINGS_DEBUG: SDK debug logging.

Architecture and safety invariants

The single-package Go MCP server is in main.go, oauth.go, and landing.go. Requests authenticate with Basic credentials or OAuth bearer tokens. UserManager creates a per-account ThingsMCP; the cache binds an account to a digest of the authenticated credentials, never just an email address.

Key SDK types from github.com/arthursoares/things-cloud-sdk:

• Task.CreationDate is time.Time; ScheduledDate, DeadlineDate, and CompletionDate are pointers.
• TaskType: 0 task, 1 project, 2 heading. TaskStatus: 0 pending, 2 canceled, 3 completed.
• TaskSchedule: 0 inbox, 1 anytime, 2 someday. Task.StartBucket: 0 default, 1 tonight (wire field sb).

Every operation for one account holds that account's opMu for the complete sync, validation, handler, and write lifecycle. Do not narrow this lock: history cursors and the in-memory task graph must advance atomically.

Synchronization is fail-closed:

• Resolve and use the history key returned by Verify; never select the numerically largest history.
• Initial load builds a candidate history and state, then swaps both only after every page and event validates.
• Incremental sync uses a cloned cursor and applies a fully validated delta atomically.
• Never automatically fall back to a full rebuild after an incremental error.
• Reject unknown schema versions, business-entity kinds, actions, malformed payloads, cursor regression, and no-progress pagination. Versioned Settings<digits> records are the explicit exception: they are account metadata and must be ignored so settings-only version bumps cannot block the task graph.