actual-mcp-server: Instructions file for GitHub Copilot

Copilot Instructions for Actual MCP Server

Project Overview

Actual MCP Server bridges AI assistants with Actual Budget via the Model Context Protocol (MCP), providing 81 tools for conversational financial management. Supports two transports: HTTP (LibreChat/LobeChat/multi-user) and stdio (Claude Desktop/Claude Code).

Tech Stack: TypeScript (NodeNext/ESM), Node.js 22+, @actual-app/api v26, @modelcontextprotocol/sdk, Express 5, Zod v4, Playwright

Current Status: Production-ready, 81 tools implemented

Architecture Essentials

Critical Pattern: withActualApi Wrapper

Every Actual API operation MUST use withActualApi() wrapper from src/lib/actual-adapter.ts:

// ✅ CORRECT - ensures data persistence
await withActualApi(async () => {
  return await rawAddTransactions(data);
});

// ❌ WRONG - data won't persist (tombstone issue)
await rawAddTransactions(data);

Why: Actual Budget requires api.shutdown() after every operation to commit data. The withActualApi wrapper handles init/shutdown lifecycle automatically. Based on s-stefanov/actual-mcp pattern.

Tool Structure

New tools should use createTool() from src/lib/toolFactory.ts — it wires up error handling, logging, and observability automatically:

import { z } from 'zod';
import { createTool } from '../lib/toolFactory.js';
import { CommonSchemas } from '../lib/schemas/common.js';
import adapter from '../lib/actual-adapter.js';

export default createTool({
  name: 'actual_domain_action',      // naming: actual_{domain}_{action}
  description: '...',
  schema: z.object({
    account: CommonSchemas.accountId,
    amount: CommonSchemas.amountCents, // always in cents, integer
    date: CommonSchemas.date,          // YYYY-MM-DD
  }),
  handler: async (input) => {
    return await adapter.someMethod(input);
  },
});

Many existing tools use the legacy pattern (both work, but createTool() is preferred for new tools):