whooing_balance

Instructions

Implementation Reference

• src/server.ts:834-854 (handler)

  The handler function for 'whooing_balance' tool. It normalizes date args, fetches a balance sheet (bs.json) from the Whooing API, formats the result via formatBalance(), and returns text content.

  async (args) => {
    const defaults = getDateDefaults();
    const startDate = normalizeDate(args.start_date ?? defaults.startDate);
    const endDate = normalizeDate(args.end_date ?? defaults.endDate);
    const sectionId = args.section_id ?? client.defaultSectionId;
  
    await client.loadAccounts(sectionId);
    const results = await client.apiGet("bs.json", {
      section_id: sectionId,
      start_date: startDate,
      end_date: endDate,
    });
  
    const text = formatBalance(
      results as Parameters<typeof formatBalance>[0],
      client.getAccountCache(),
      startDate,
      endDate
    );
    return { content: [{ type: "text", text }] };
  }

• src/server.ts:63-78 (schema)

  The input schema (dateRangeSchema) used by the whooing_balance tool. Defines optional start_date, end_date, and section_id fields.

  const dateRangeSchema = {
    start_date: z
      .string()
      .regex(/^\d{4}-?\d{2}-?\d{2}$/)
      .optional()
      .describe("Start date (YYYYMMDD). Defaults to 1st of current month."),
    end_date: z
      .string()
      .regex(/^\d{4}-?\d{2}-?\d{2}$/)
      .optional()
      .describe("End date (YYYYMMDD). Defaults to today."),
    section_id: z
      .string()
      .optional()
      .describe("Section ID. Defaults to WHOOING_SECTION_ID env var."),
  };

• src/server.ts:826-855 (registration)

  Registration of the 'whooing_balance' tool via server.registerTool() with description, inputSchema, and annotations.

  server.registerTool(
    "whooing_balance",
    {
      description:
        "Get balance sheet (assets, liabilities, capital) as of a date range",
      inputSchema: dateRangeSchema,
      annotations: { readOnlyHint: true },
    },
    async (args) => {
      const defaults = getDateDefaults();
      const startDate = normalizeDate(args.start_date ?? defaults.startDate);
      const endDate = normalizeDate(args.end_date ?? defaults.endDate);
      const sectionId = args.section_id ?? client.defaultSectionId;
  
      await client.loadAccounts(sectionId);
      const results = await client.apiGet("bs.json", {
        section_id: sectionId,
        start_date: startDate,
        end_date: endDate,
      });
  
      const text = formatBalance(
        results as Parameters<typeof formatBalance>[0],
        client.getAccountCache(),
        startDate,
        endDate
      );
      return { content: [{ type: "text", text }] };
    }
  );

• src/formatters.ts:557-561 (helper)

  BSResults interface defining the shape of the balance sheet response (assets, liabilities, capital as CategoryGroup).

  interface BSResults {
    assets?: CategoryGroup;
    liabilities?: CategoryGroup;
    capital?: CategoryGroup;
  }

• src/formatters.ts:563-595 (helper)

  The formatBalance() helper function that formats balance sheet data into a human-readable string with asset/liability/capital sections.

  export function formatBalance(
    results: BSResults,
    accounts: Map<string, AccountInfo>,
    startDate: string,
    endDate: string
  ): string {
    const lines: string[] = [];
    lines.push(`## 자산/부채 현황 (${startDate} ~ ${endDate})`);
    lines.push("");
  
    const sections: [string, CategoryGroup | undefined][] = [
      ["자산", results.assets],
      ["부채", results.liabilities],
      ["자본", results.capital],
    ];
  
    for (const [title, group] of sections) {
      const filtered = normalizeAccountEntries(group?.accounts)
        .filter((item) => Number(item.money) !== 0)
        .sort((a, b) => Math.abs(Number(b.money)) - Math.abs(Number(a.money)));
  
      if (filtered.length > 0) {
        lines.push(`### ${title}: ${formatAmount(group?.total ?? 0)}`);
        for (const item of filtered) {
          const name = accounts.get(item.account_id)?.name ?? item.account_id;
          lines.push(`- ${name}: ${formatAmount(item.money)}`);
        }
        lines.push("");
      }
    }
  
    return lines.join("\n");
  }