actual-mcp-server: Instructions file for GitHub Copilot

Rules for MCP tool files (src/tools/*.ts)

• Tool name MUST follow actual_{domain}_{action} snake_case convention
• File name MUST match the tool name (e.g. accounts_create.ts for actual_accounts_create)
• InputSchema MUST use z.object({...}) from Zod
• Use types from CommonSchemas in src/lib/schemas/common.ts for shared fields:
  • Dates → CommonSchemas.date (validates YYYY-MM-DD)
  • Account UUIDs → CommonSchemas.accountId
  • Amounts → CommonSchemas.amountCents (integer cents, never decimal dollars)
• The call function MUST InputSchema.parse(args) before any other logic
• NEVER wrap an adapter.* call in a session of your own. adapter.* methods already open one, and the API mutex (withApiLock in actual-adapter.ts) is NOT reentrant, so nesting deadlocks. What you observe is a ~30s stall then Actual API operation timed out after 30000ms (ACTUAL_OP_TIMEOUT_MS), because #270 bounds each operation inside the lock and that timeout is what breaks the deadlock. Read that error as a probable nesting bug, not a slow server.
• Default to calling adapter.* methods. Do NOT reach for @actual-app/api just to avoid a wrapper.
• No tool statically imports @actual-app/api or performs a raw write (see AGENTS.md). A batch of pure writes that must share one cycle is an adapter method (for example adapter.setBudgetBatch, used by budget_updates_batch.ts) that runs its raw writes inside one queueWriteOperation, because calling back through adapter.* from inside a session is the nesting deadlock above. Two summary tools dynamically import the package only for the q() query builder; that is out of scope.
• A read-then-write guard belongs in the ADAPTER, not the tool (#371, #376). Four tool files used to hold one inside their own withWriteSession; all four were migrated. A guard in the tool costs retry on the reads, bypasses the observability call site, and leaves the matching adapter.* method reachable and UNGUARDED, which is how adapter.deleteRule sat callerless while silently failing to delete a schedule-owned rule. The single-cycle property does not require the raw api: queueWriteOperation holds the lock for its whole body
• When you move a guard into the adapter, fix its test's seam too. Stubbing adapter.withWriteSession as a pass-through stubs away the guard itself. Use _setSkipApiInitForTests(true) with the RAW api functions stubbed BEFORE the adapter import (it destructures them at module load), and assert the single-cycle property with the witness in tests/unit/helpers/write-cycle.mjs, which samples the drain counter from inside the raw read and write stubs. A bare _getWriteQueueBatchCountForTests() delta is not enough (#376): it proves only that one drain happened, so it stays green when the guard's read moves back out of queueWriteOperation
• Error messages must be actionable: include entity type, ID, and a suggested next tool
• After creating a tool file, you MUST:
  1. Export it from src/tools/index.ts
  2. Add the name to IMPLEMENTED_TOOLS in src/actualToolsManager.ts
  3. Run npm run build first (verify-tools reads from dist/, not src/)
  4. Run npm run verify-tools to confirm registration
• To check uncovered Actual API surface before implementing: npm run check:coverage (prints every @actual-app/api method against the current tool list; read-only, safe to run)

On conflict, follow the precedence in AGENTS.md; this file adds detail for its applyTo glob and must not contradict it.