report_balance

Instructions

Implementation Reference

• apps/mcp/src/tools/report.ts:9-46 (handler)

  Handler: Defines the 'report_balance' MCP tool. Aggregates all balance entries by period, computing assets, liabilities, and net_worth, sorted by period and limited by the 'limit' parameter (default 36).

  server.tool(
    'report_balance',
    'Aggregate balance sheet entries by period. Returns monthly net worth trend sorted by period.',
    {
      limit: z
        .number()
        .int()
        .min(1)
        .max(120)
        .default(36)
        .describe('Max number of periods to return (default: 36)'),
    },
    async ({ limit }) => {
      const db = getDb();
      const rows = db.select().from(balanceEntries).all();
  
      const byPeriod = rows.reduce((map, { period, type, amount }) => {
        const prev = map.get(period) ?? { assets: 0, liabilities: 0 };
        map.set(period, {
          assets: prev.assets + (type === 'asset' ? amount : 0),
          liabilities: prev.liabilities + (type === 'liability' ? amount : 0),
        });
        return map;
      }, new Map<string, { assets: number; liabilities: number }>());
  
      const result = [...byPeriod.entries()]
        .sort(([a], [b]) => a.localeCompare(b))
        .slice(-limit)
        .map(([period, { assets, liabilities }]) => ({
          period,
          assets,
          liabilities,
          net_worth: assets - liabilities,
        }));
  
      return ok(result);
    },
  );

• apps/mcp/src/tools/report.ts:12-20 (schema)

  Schema: Zod input schema for report_balance — accepts optional 'limit' (integer 1-120, default 36).

  {
    limit: z
      .number()
      .int()
      .min(1)
      .max(120)
      .default(36)
      .describe('Max number of periods to return (default: 36)'),
  },

• apps/mcp/src/tools/report.ts:8-20 (registration)

  Registration: The 'report_balance' tool is registered via server.tool() within the registerReportTools() function, which is called from apps/mcp/src/index.ts:20.

  export function registerReportTools(server: McpServer): void {
    server.tool(
      'report_balance',
      'Aggregate balance sheet entries by period. Returns monthly net worth trend sorted by period.',
      {
        limit: z
          .number()
          .int()
          .min(1)
          .max(120)
          .default(36)
          .describe('Max number of periods to return (default: 36)'),
      },

• apps/mcp/src/helpers.ts:67-69 (helper)

  Helper: The 'ok' function wraps data into the MCP response format (content array with JSON stringified text).

  export const ok = (data: unknown) => ({
    content: [{ type: 'text' as const, text: JSON.stringify(data, null, 2) }],
  });

• apps/mcp/src/db.ts:50-58 (helper)

  Support: getDb() returns the database client used by the tool handler to query balanceEntries.

  export const getDb = (): DbClient => {
    if (!_db) _db = createDbClient(dbPath());
    return _db;
  };
  
  export const getRepository = (): DataRepository => {
    if (!_repo) _repo = createDataRepository(getDb());
    return _repo;
  };