feat(mcp-server): balance report tool (MCP Prompt 15)

[gilgardosh]

Summary

Implements Prompt 15 – Tool 3: selected report read operation (see
docs/mcp/spec.md §8.2). Adds one high-value
read-only report.

Stacked PR: targets claude/mcp-prompt-14-lookup-tools (Prompt 14, #4015).
Review/merge Prompts 09→14 first; this diff shows only the Prompt 15 changes.

Changes

• src/tools/reports.ts — accounter_balance_report (transactionsForBalanceReport):
  • Strict input with tight limits: a single businessId, fromDate/toDate (bounded to 366 days, format-checked), and a reportType enum (BALANCE, the only phase-1 value).
  • Role-gated (business_owner / accountant, matching the server's @requiresAnyRole).
  • Output rows capped at 500 with a truncated flag to avoid large payloads; normalized rows + period + count.
• src/tools/execute.ts — the scope-narrowing convention now also accepts a singular businessId (not just businessIds[]), so the report's business is validated as a subset of the caller's memberships (AUTHORIZATION_ERROR when out of scope) and passed as the report's ownerId.
• src/tools/registry-instance.ts — the report tool registered.
• Tests — valid report (owner scoping + normalization), invalid range (inverted, too-wide, bad format), oversized-result truncation, and role/scope denial. 167 tests total.

Validation

• yarn workspace @accounter/mcp-server test → 167 passed
• yarn workspace @accounter/mcp-server lint / typecheck / build → pass

Notes / open decisions

• Report choice. I picked the balance report because it has a clean bounded date-range + single-owner shape and is role-gated — good coverage of the policy machinery. The reportType enum has one value now so adding more reports later is non-breaking.
• Row cap. Capped at 500 rows in-tool with a truncated flag; the shared truncation framework (Prompt 16) will generalize this and add continuation hints.
• Query fields verified against packages/server (transactionsForBalanceReport, BalanceTransactions, FinancialAmount); upstream is mocked in tests, so worth a live smoke check before release.

🤖 Generated with Claude Code

---

Generated by Claude Code

[gemini-code-assist]

Code Review

This pull request introduces the accounter_balance_report tool, which generates read-only balance reports for a business over a bounded date range. It also updates the scope-narrowing helper to support a singular businessId input and registers the new tool. The review feedback highlights two important improvements: adding an explicit check to ensure ownerId is defined to prevent unauthorized queries, and using nullish coalescing on the upstream GraphQL response to avoid potential runtime crashes if the transaction list is nullish.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

To enforce strict tenant isolation and prevent potential unauthorized queries or runtime errors, we should explicitly assert that ownerId is defined and is a valid string before passing it to the upstream GraphQL query.

Suggested change

	const ownerId = context.readScope.businessIds[0];
	const data = await context.client.query<{ transactionsForBalanceReport: RawBalanceRow[] }>(
	const ownerId = context.readScope.businessIds[0];
	if (!ownerId) {
	throw new Error('No authorized business ID found in scope');
	}
	const data = await context.client.query<{ transactionsForBalanceReport: RawBalanceRow[] }>(