@expensebot/mcp-server-auth 0.6.13 → 0.6.17

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -2,11 +2,11 @@
2
2
 
3
3
  Authenticated MCP (Model Context Protocol) server for [ExpenseBot](https://www.expensebot.ai). Lets Claude Desktop, Cursor, Claude Code, Continue, Cline, Windsurf, and any MCP-compatible AI assistant search receipts, submit photos, scan Gmail, create reports, and analyze spending using your real ExpenseBot account.
4
4
 
5
- **47 tools** across:
5
+ **50 tools** across:
6
6
  - **Search & analytics** — `search_expenses`, `get_spending_summary`, `get_deep_analytics`, `list_categories`, `list_tags`, `list_income_categories`, `search_knowledge`
7
7
  - **Income & P&L** *(v0.6.0)* — `get_income_summary`, `get_pnl`, `get_per_tag_pnl`
8
8
  - **Mileage & Subscriptions** *(v0.6.1)* — `get_mileage_summary`, `get_subscription_audit`
9
- - **Receipt capture** — `submit_receipt` (photo/PDF), `get_last_receipt_result`, `add_cash_expense`, `add_mileage_entry`, `add_income`, `parse_expense`, `get_expense_by_id`, `update_expense`, `group_expenses`, `get_spreadsheet_url`
9
+ - **Receipt and expense capture** — `submit_receipt` (photo/PDF), `get_last_receipt_result`, `add_cash_expense` (including confirmed client advances), `add_mileage_entry`, `add_income`, `add_income_from_file` (screenshot/PDF, parse-preview-confirm), `add_income_from_csv` (CSV/TSV/text, parse-preview-confirm), `parse_expense`, `get_expense_by_id`, `update_expense`, `group_expenses`, `correct_expenses`, `get_spreadsheet_url`
10
10
  - **Gmail** — `scan_gmail`, `process_gmail_receipts`, `scan_gmail_years`, `get_scan_status`
11
11
  - **Reports & invoicing** — `create_report`, `list_reports`, `get_report_details`, `share_report`, `export_report`, `list_client_invoices`
12
12
  - **Expense review** — `get_expense_splits`, `get_monthly_books_review`, `get_credits_refunds`
@@ -33,7 +33,7 @@ prepended. `update_expense` refuses zero or multiple exact matches.
33
33
 
34
34
  ### Quick start (Claude Desktop)
35
35
 
36
- 1. Sign in at [expensebot.ai](https://www.expensebot.ai) → Settings → AI Assistant Tokens → Generate
36
+ 1. Sign in and open [AI Assistant Tokens](https://www.expensebot.ai/process-info?openMcpTokens=true&source=npm) → Generate
37
37
  2. Copy the token (shown once)
38
38
  3. Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (Mac) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
39
39
 
@@ -42,7 +42,10 @@ prepended. `update_expense` refuses zero or multiple exact matches.
42
42
  "mcpServers": {
43
43
  "expensebot": {
44
44
  "command": "npx",
45
- "args": ["-y", "@expensebot/mcp-server-auth", "--token=YOUR_TOKEN_HERE"]
45
+ "args": ["-y", "@expensebot/mcp-server-auth"],
46
+ "env": {
47
+ "EXPENSEBOT_TOKEN": "YOUR_TOKEN_HERE"
48
+ }
46
49
  }
47
50
  }
48
51
  }
@@ -53,9 +56,11 @@ prepended. `update_expense` refuses zero or multiple exact matches.
53
56
  ### Quick start (Claude Code CLI)
54
57
 
55
58
  ```bash
56
- claude mcp add expensebot -- npx -y @expensebot/mcp-server-auth --token=YOUR_TOKEN_HERE
59
+ claude mcp add expensebot -- npx -y @expensebot/mcp-server-auth
57
60
  ```
58
61
 
62
+ Store `EXPENSEBOT_TOKEN` in Claude Code's environment or secret settings first. Do not put the token in the command or paste it into chat.
63
+
59
64
  ### Quick start (Cursor)
60
65
 
61
66
  Edit `~/.cursor/mcp.json`:
@@ -65,7 +70,10 @@ Edit `~/.cursor/mcp.json`:
65
70
  "mcpServers": {
66
71
  "expensebot": {
67
72
  "command": "npx",
68
- "args": ["-y", "@expensebot/mcp-server-auth", "--token=YOUR_TOKEN_HERE"]
73
+ "args": ["-y", "@expensebot/mcp-server-auth"],
74
+ "env": {
75
+ "EXPENSEBOT_TOKEN": "YOUR_TOKEN_HERE"
76
+ }
69
77
  }
70
78
  }
71
79
  }
@@ -75,7 +83,17 @@ Then in Cursor: Settings → Tools & Integrations → confirm the green dot next
75
83
 
76
84
  ### Continue, Cline, Windsurf, custom clients
77
85
 
78
- Same `npx -y @expensebot/mcp-server-auth --token=...` command in your client's MCP config.
86
+ Use `npx -y @expensebot/mcp-server-auth` in your client's MCP config and provide the token through its `EXPENSEBOT_TOKEN` environment or secret setting.
87
+
88
+ ### Remote/custom agents (including Viktor)
89
+
90
+ If the client supports remote HTTP MCP with OAuth, add:
91
+
92
+ ```text
93
+ https://mcp.expensebot.ai/mcp
94
+ ```
95
+
96
+ Complete ExpenseBot sign-in and consent in the browser. No personal token or manual OAuth client secret is needed. If the client supports only local/stdio MCP, use the npm setup above. Never email a token or paste it into an AI conversation.
79
97
 
80
98
  ## Token model
81
99
 
@@ -121,7 +139,7 @@ Exposes the ExpenseBot knowledge base, FAQ, and feature docs as MCP resources. U
121
139
 
122
140
  - Source: <https://github.com/TotesMagotes/expensebot/tree/master/mcp-server-auth>
123
141
  - Issues: email `support@expensebot.ai`
124
- - Roadmap (remote HTTPS MCP for ChatGPT + Claude.ai web): <https://www.expensebot.ai/mcp>
142
+ - Complete setup chooser and remote/desktop instructions: <https://www.expensebot.ai/mcp#choose-connection>
125
143
 
126
144
  ## Maintainer: adding or changing a tool
127
145
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@expensebot/mcp-server-auth",
3
- "version": "0.6.13",
3
+ "version": "0.6.17",
4
4
  "mcpName": "io.github.TotesMagotes/mcp-server-auth",
5
5
  "description": "Authenticated MCP server for ExpenseBot — lets Claude Desktop, Cursor, and other AI assistants search your expenses, create reports, and analyze spending using your actual ExpenseBot data.",
6
6
  "bin": {
package/src/client.js CHANGED
@@ -46,7 +46,7 @@ export class ExpenseBotClient {
46
46
  headers: {
47
47
  Authorization: `Bearer ${this.token}`,
48
48
  "Content-Type": "application/json",
49
- "User-Agent": "expensebot-mcp-auth/0.6.13",
49
+ "User-Agent": "expensebot-mcp-auth/0.6.17",
50
50
  "X-ExpenseBot-MCP-Transport": "stdio",
51
51
  ...options.headers,
52
52
  },
@@ -60,7 +60,7 @@ export class ExpenseBotClient {
60
60
  "1. Go to https://www.expensebot.ai (sign up for free 60-day trial if you don't have an account)\n" +
61
61
  "2. Click Settings → AI Assistant Tokens → Generate\n" +
62
62
  "3. Copy the token (shown only once)\n" +
63
- "4. Update your MCP config with --token=<new-token>\n" +
63
+ "4. Update EXPENSEBOT_TOKEN in your AI client's secret or environment configuration\n" +
64
64
  "5. Restart your AI client (Claude Desktop, Cursor, etc.)"
65
65
  );
66
66
  }
package/src/index.js CHANGED
@@ -6,15 +6,17 @@
6
6
  * create reports, get analytics, and more — using the user's actual
7
7
  * ExpenseBot data.
8
8
  *
9
- * Usage:
10
- * npx @expensebot/mcp-server-auth --token=<your-pat>
9
+ * Usage: provide EXPENSEBOT_TOKEN through the client's secret/environment
10
+ * configuration, then run:
11
+ * npx @expensebot/mcp-server-auth
11
12
  *
12
13
  * Claude Desktop config:
13
14
  * {
14
15
  * "mcpServers": {
15
16
  * "expensebot": {
16
17
  * "command": "npx",
17
- * "args": ["-y", "@expensebot/mcp-server-auth", "--token=<your-pat>"]
18
+ * "args": ["-y", "@expensebot/mcp-server-auth"],
19
+ * "env": { "EXPENSEBOT_TOKEN": "<stored securely by the client>" }
18
20
  * }
19
21
  * }
20
22
  * }
@@ -28,7 +30,8 @@ import {
28
30
  } from "@modelcontextprotocol/sdk/types.js";
29
31
  import { ExpenseBotClient } from "./client.js";
30
32
 
31
- // Parse --token from args
33
+ // Environment configuration is canonical. Keep the legacy argument parser so
34
+ // existing installations do not break, but do not advertise secrets in argv.
32
35
  const args = process.argv.slice(2);
33
36
  let token = process.env.EXPENSEBOT_TOKEN;
34
37
  for (const arg of args) {
@@ -43,6 +46,12 @@ const client = onboardingMode ? null : new ExpenseBotClient(token);
43
46
 
44
47
  const SERVER_INSTRUCTIONS = [
45
48
  "ExpenseBot tracks the user's business expenses and income in a Google Sheet they own.",
49
+ "For a requested multi-step workflow, be concise: show the grounded preview, ask one clear yes/no confirmation when required, then complete every approved step. Prefer group_expenses for group-and-report requests even when the expenses already have that group. Do not add unsolicited tax, audit, substantiation, or client-AP advice, and do not second-guess an approved scope unless a tool reports an ambiguity, conflict, or failure. A request to create, share, or bill from a report is NOT a request for compliance, tax, deductibility, report-detail, business-purpose, attendee, or reimbursement analysis: never call those tools as a preflight or follow-up unless the user explicitly asks for that analysis. 'Without personal expenses' is only a report filter. isReimbursable is ExpenseBot workflow state, not a judgment about whether an expense may be billed to a client.",
50
+ "For exact corrections across several expenses, use correct_expenses only after search_expenses has returned the exact expenseId values. Show its automatic preview, ask one yes/no question, then return its verified terminal result without adding advice. Use only attendee names the user explicitly supplied. For broad, ambiguous, mixed, or more than 100-row cleanup, link to Review Expenses instead.",
51
+ "Across every tool, treat returned counts, totals, currencies, statuses, and completion evidence as authoritative. Never recompute them from detail rows or reinterpret a successful result. After an approved write completes, report the outcome and relevant links without reopening the user's approved scope or adding unrequested advice. Ask another question only when the tool reports an ambiguity, conflict, failure, or required external side effect.",
52
+ "Across every answer, answer the user's requested task first and stop when it is complete. Do not infer intent, risk, tax treatment, reimbursement eligibility, business purpose, attendees, client expectations, or currency preferences from merchants, locations, dates, or amounts. Offer analysis, warnings, or follow-up work only when the user asks for it or an authoritative tool result says action is required.",
53
+ "A successful terminal write result supersedes intermediate search and preview observations. The final answer must follow the terminal result's responseGuidance and must not repeat exploratory candidates, excluded near-matches, or concerns that the terminal tool did not report. When a terminal result contains finalAnswer, return it verbatim and add nothing else. After a Bill Client handoff, do not offer report sharing or currency advice unless the user explicitly requested it.",
54
+ "Report provenance is literal: say a report was created only when the terminal result explicitly says creationStatus=created_this_call. Reports returned by list_reports are pre-existing; describe them as found, existing, or opened, never created or generated. If no new report was created, say so plainly and do not imply otherwise.",
46
55
  "After submit_receipt returns a submissionId, call get_last_receipt_result with that exact ID using the polling interval and time allowance returned by submit_receipt. A small batch allows at least 5 minutes and larger batches allow longer. A pending result is normal; never resubmit the same file because that creates a duplicate. Report the final counts, then show spreadsheetUrl and reviewExpensesUrl.",
47
56
  "After another expense submission, show the returned spreadsheetUrl and reviewExpensesUrl.",
48
57
  "For income writes, show spreadsheetUrl and reviewIncomeUrl.",
@@ -278,8 +287,18 @@ const TOOLS = [
278
287
  "excludes both the Personal tag and Personal expense category, matching " +
279
288
  "ExpenseBot's Report Wizard. Returns the report summary, exact report " +
280
289
  "link, Bill Client link, applied filters, and a prefilled Report Wizard " +
281
- "fallback for criteria that need visual review. Can optionally share " +
282
- "with recipients.",
290
+ "fallback for criteria that need visual review. Reports scoped to an " +
291
+ "existing client/project/trip group include matching expenses that are " +
292
+ "not already assigned to another ordinary report. Can optionally share " +
293
+ "with recipients. If no unreported matches remain, create no duplicate " +
294
+ "report and explain that the expenses are already in Reports. Terminal " +
295
+ "results also include accountingHandoffUrls for QuickBooks, Xero, and " +
296
+ "the existing file-export workflow. Use only the exact " +
297
+ "destination the user requested; the link opens the reviewed app flow " +
298
+ "and does not mean an export occurred. Complete " +
299
+ "the requested report directly; do not call " +
300
+ "check_compliance, get_report_details, or tax/deductibility tools before " +
301
+ "or after it unless the user explicitly asks for that separate analysis.",
283
302
  inputSchema: {
284
303
  type: "object",
285
304
  properties: {
@@ -319,7 +338,10 @@ const TOOLS = [
319
338
  name: "list_reports",
320
339
  description:
321
340
  "List the user's expense reports with pagination. Filter by status " +
322
- "(All, Draft, Submitted, Shared).",
341
+ "(All, Draft, Submitted, Shared). Each exact report includes its app, " +
342
+ "Bill Client, and accounting handoff URLs. Use the matching accounting " +
343
+ "URL only when the user explicitly asks to send or export that report; " +
344
+ "the app keeps organization, mapping, preview, and final confirmation.",
323
345
  inputSchema: {
324
346
  type: "object",
325
347
  properties: {
@@ -334,14 +356,22 @@ const TOOLS = [
334
356
  name: "get_report_details",
335
357
  description:
336
358
  "Get full details of a specific expense report including all expenses, " +
337
- "totals, and compliance status.",
359
+ "totals, and compliance status. Use only when the user explicitly asks " +
360
+ "to inspect an existing report's details. Never call this as a preflight " +
361
+ "or follow-up to creating, sharing, or billing from a report; those tools " +
362
+ "already return the required result and links.",
338
363
  inputSchema: {
339
364
  type: "object",
340
365
  properties: {
341
366
  clientEmail: CLIENT_EMAIL_SCHEMA,
342
367
  reportId: { type: "string", description: "The report/spreadsheet ID" },
368
+ userRequest: {
369
+ type: "string",
370
+ description:
371
+ "The user's exact request asking to inspect this report. Do not paraphrase or invent diagnostic intent.",
372
+ },
343
373
  },
344
- required: ["reportId"],
374
+ required: ["reportId", "userRequest"],
345
375
  },
346
376
  },
347
377
  {
@@ -364,14 +394,22 @@ const TOOLS = [
364
394
  {
365
395
  name: "check_compliance",
366
396
  description:
367
- "Check an expense report for compliance issues (missing business " +
368
- "purpose, policy violations, etc.).",
397
+ "Use only when the user explicitly asks to check an existing report for " +
398
+ "compliance issues such as missing business purpose or policy violations. " +
399
+ "Creating a report, excluding Personal expenses, sharing a report, or " +
400
+ "billing a client is not a compliance request; never call this tool " +
401
+ "automatically as a preflight or follow-up for those workflows.",
369
402
  inputSchema: {
370
403
  type: "object",
371
404
  properties: {
372
405
  reportId: { type: "string", description: "Report ID to check" },
406
+ userRequest: {
407
+ type: "string",
408
+ description:
409
+ "The user's exact request explicitly asking for compliance, policy, audit, substantiation, or business-purpose analysis. Do not paraphrase or invent intent.",
410
+ },
373
411
  },
374
- required: ["reportId"],
412
+ required: ["reportId", "userRequest"],
375
413
  },
376
414
  },
377
415
  {
@@ -448,6 +486,7 @@ const TOOLS = [
448
486
  },
449
487
  {
450
488
  name: "submit_receipt",
489
+ _meta: { "openai/fileParams": ["photo"] },
451
490
  description:
452
491
  "Submit a photo or PDF of a receipt for processing. Covers requests " +
453
492
  "phrased as 'log this', 'log this receipt', 'save this receipt', " +
@@ -628,15 +667,28 @@ const TOOLS = [
628
667
  {
629
668
  name: "add_cash_expense",
630
669
  description:
631
- "Add an expense without a receipt (cash purchase, tip, etc.). " +
632
- "Writes directly to the user's expense spreadsheet. Call list_categories " +
633
- "first and choose one of the user's configured Expense Accounts. A unique " +
634
- "account-label alias may be canonicalized, but unknown or ambiguous categories are rejected.",
670
+ "Add an expense without a receipt, or record money a client provided in advance for expenses. " +
671
+ "Writes directly to the user's expense spreadsheet after confirmation. For an ordinary expense, " +
672
+ "call list_categories first and provide a configured Expense Account. For a client advance, set " +
673
+ "isClientAdvance=true and clientName; ExpenseBot reuses or creates the canonical client group, " +
674
+ "applies Cash advance received, and stores the amount as a negative expense. Use this only for " +
675
+ "money supplied by a client before related spending, never for vendor refunds, reimbursements, " +
676
+ "earned fees, retainers, or generic deposits. " +
677
+ "Use the Manual expense link from get_spreadsheet_url instead when the user " +
678
+ "needs a reviewed form for multiple entries, credits/refunds, tax or tip " +
679
+ "breakdowns, per diem, or incomplete details.",
635
680
  inputSchema: {
636
681
  type: "object",
637
682
  properties: {
638
- merchant: { type: "string", description: "Merchant/vendor name" },
639
- total: { type: "number", description: "Total amount" },
683
+ merchant: {
684
+ type: "string",
685
+ description:
686
+ "Merchant/vendor name for an ordinary expense. Not needed for a client advance; ExpenseBot derives it from clientName.",
687
+ },
688
+ total: {
689
+ type: "number",
690
+ description: "Positive amount paid or received. ExpenseBot stores a client advance as negative.",
691
+ },
640
692
  date: {
641
693
  type: "string",
642
694
  description: "Expense date (YYYY-MM-DD)",
@@ -653,8 +705,18 @@ const TOOLS = [
653
705
  currency: { type: "string", description: "Currency code (default: USD)" },
654
706
  city: { type: "string", description: "City/location" },
655
707
  notes: { type: "string", description: "Notes or description" },
708
+ isClientAdvance: {
709
+ type: "boolean",
710
+ description:
711
+ "True only when a client supplied money in advance for expenses. Requires clientName and does not require category.",
712
+ },
713
+ clientName: {
714
+ type: "string",
715
+ description:
716
+ "Client name for a client advance, in ordinary language. ExpenseBot resolves the canonical Client – Name group.",
717
+ },
656
718
  },
657
- required: ["merchant", "total", "date", "category"],
719
+ required: ["total", "date"],
658
720
  },
659
721
  },
660
722
  {
@@ -758,7 +820,10 @@ const TOOLS = [
758
820
  "consultants, contractors, and anyone who drives for work. Requires " +
759
821
  "the user to have configured their mileage rate (cents/km or cents/mi) " +
760
822
  "and unit (mi/km) in ExpenseBot Settings. The trip writes a row to " +
761
- "their expense spreadsheet with the calculated dollar value.",
823
+ "their expense spreadsheet with the calculated dollar value. Use the " +
824
+ "Mileage and travel link from get_spreadsheet_url instead when the user " +
825
+ "needs Google Maps route calculation, mileage settings, repeated trips, " +
826
+ "calendar/rideshare import, per diem, or visual review.",
762
827
  inputSchema: {
763
828
  type: "object",
764
829
  properties: {
@@ -838,6 +903,191 @@ const TOOLS = [
838
903
  required: ["amount", "source", "paymentMethod"],
839
904
  },
840
905
  },
906
+ {
907
+ name: "add_income_from_file",
908
+ _meta: { "openai/fileParams": ["photo"] },
909
+ description:
910
+ "Import income from an attached screenshot, image (JPEG, PNG, WebP, HEIC/HEIF), or PDF " +
911
+ "(payment screenshots, wallet apps, payout or bank statements; max 10 MB). This is a " +
912
+ "two-step tool. STEP 1: call it with the file and WITHOUT confirm — ExpenseBot parses the " +
913
+ "file with the same importer as the app's Add Income screen, checks every row against the " +
914
+ "user's Income tab for duplicates, and returns a preview with a previewId, exact row count, " +
915
+ "totals by currency, per-row details, duplicate flags, and any rejected rows. NOTHING is " +
916
+ "saved in step 1; treat the attachment as consent to parse, not consent to write. Show the " +
917
+ "user the parsed rows and duplicates, then STEP 2: call again with confirm: true and the " +
918
+ "previewId to write exactly those rows. Only include user-approved changes in step 2 " +
919
+ "(selectedIndexes, keepBothIndexes, rowEdits, tag, bulkNote). Flagged duplicates are skipped " +
920
+ "unless the user explicitly asks to keep them (keepBothIndexes). The preview expires after " +
921
+ "15 minutes; an expired or unknown previewId never writes. After a successful confirm, show " +
922
+ "the returned spreadsheetUrl and reviewIncomeUrl. For a visually complex review (mixed " +
923
+ "income/expense rows, many edits), send the user to the Add Income app link returned by " +
924
+ "get_spreadsheet_url instead.",
925
+ inputSchema: {
926
+ type: "object",
927
+ properties: {
928
+ photo: {
929
+ type: "string",
930
+ description:
931
+ "Base64-encoded image/PDF bytes (step 1). On ChatGPT you may pass the attached file " +
932
+ "reference object directly; the server fetches the bytes.",
933
+ },
934
+ mimeType: {
935
+ type: "string",
936
+ enum: [
937
+ "image/jpeg",
938
+ "image/png",
939
+ "image/webp",
940
+ "image/heic",
941
+ "image/heif",
942
+ "application/pdf",
943
+ ],
944
+ description: "MIME type of the file (default: image/jpeg)",
945
+ },
946
+ paymentMethod: {
947
+ type: "string",
948
+ description:
949
+ "Fallback payment rail for rows where the parser found none (Cash, Check, " +
950
+ "Bank transfer, Wallet app, Credit/Debit card, Payment processor, or Other).",
951
+ },
952
+ tag: {
953
+ type: "string",
954
+ description:
955
+ "Optional client/project tag. In step 1 it pre-fills the staged rows; in step 2 it " +
956
+ "applies to the confirmed selection.",
957
+ },
958
+ confirm: {
959
+ type: "boolean",
960
+ description:
961
+ "Step 2 only: true writes the staged rows. Omit it (with previewId absent) to parse " +
962
+ "and preview without writing.",
963
+ },
964
+ previewId: {
965
+ type: "string",
966
+ description: "Step 2 only: the previewId returned by the step-1 call.",
967
+ },
968
+ selectedIndexes: {
969
+ type: "array",
970
+ items: { type: "integer" },
971
+ description:
972
+ "Step 2 only: preview row indexes to write. Omit to write all staged rows.",
973
+ },
974
+ keepBothIndexes: {
975
+ type: "array",
976
+ items: { type: "integer" },
977
+ description:
978
+ "Step 2 only: preview indexes of duplicate-flagged rows the user explicitly wants to " +
979
+ "keep anyway (the app's 'Keep Both').",
980
+ },
981
+ rowEdits: {
982
+ type: "array",
983
+ description:
984
+ "Step 2 only: user-approved corrections, at most 50 rows. Fields: date (ISO " +
985
+ "YYYY-MM-DD), source, amount, currency, category, paymentMethod, description, notes, " +
986
+ "reference, fees, taxCollected, tag.",
987
+ items: {
988
+ type: "object",
989
+ properties: {
990
+ index: { type: "integer", description: "Preview row index" },
991
+ fields: { type: "object", additionalProperties: true },
992
+ },
993
+ required: ["index", "fields"],
994
+ },
995
+ },
996
+ bulkNote: {
997
+ type: "string",
998
+ description:
999
+ "Step 2 only: one note (max 120 chars) prepended to every confirmed row's Notes, " +
1000
+ "same as the app's 'Add note to all entries'.",
1001
+ },
1002
+ },
1003
+ required: [],
1004
+ },
1005
+ },
1006
+ {
1007
+ name: "add_income_from_csv",
1008
+ _meta: { "openai/fileParams": ["csvContent"] },
1009
+ description:
1010
+ "Import income from a CSV/TSV/text export (Stripe, PayPal, Square, Cash App, Venmo, " +
1011
+ "OnlyFans, Patreon, Clips4Sale, Ko-fi, Gumroad, Etsy, Uber/Lyft/DoorDash driver exports, " +
1012
+ "bank statements, and similar; max 500 KB). Same two-step contract as " +
1013
+ "add_income_from_file: STEP 1 call with csvContent and WITHOUT confirm parses the file " +
1014
+ "with the same platform-agnostic importer as the app's Add Income screen (platform " +
1015
+ "detection, fee handling, refunds, source aliases, ISO dates) and returns a duplicate-checked " +
1016
+ "preview with a previewId. NOTHING is saved in step 1. Show the user the parsed rows and " +
1017
+ "duplicates, then STEP 2 call again with confirm: true and the previewId to write exactly " +
1018
+ "those rows, optionally with user-approved selectedIndexes, keepBothIndexes, rowEdits, tag, " +
1019
+ "or bulkNote. Flagged duplicates are skipped unless the user explicitly keeps them. The " +
1020
+ "preview expires after 15 minutes and an expired or unknown previewId never writes. After a " +
1021
+ "successful confirm, show the returned spreadsheetUrl and reviewIncomeUrl.",
1022
+ inputSchema: {
1023
+ type: "object",
1024
+ properties: {
1025
+ csvContent: {
1026
+ type: "string",
1027
+ description:
1028
+ "Raw CSV/TSV/text content (step 1). On ChatGPT you may pass the attached file " +
1029
+ "reference object directly; the server fetches and decodes the bytes.",
1030
+ },
1031
+ paymentMethod: {
1032
+ type: "string",
1033
+ description:
1034
+ "Fallback payment rail for rows where the parser found none (Cash, Check, " +
1035
+ "Bank transfer, Wallet app, Credit/Debit card, Payment processor, or Other).",
1036
+ },
1037
+ tag: {
1038
+ type: "string",
1039
+ description:
1040
+ "Optional client/project tag. In step 1 it pre-fills the staged rows; in step 2 it " +
1041
+ "applies to the confirmed selection.",
1042
+ },
1043
+ confirm: {
1044
+ type: "boolean",
1045
+ description:
1046
+ "Step 2 only: true writes the staged rows. Omit it (with previewId absent) to parse " +
1047
+ "and preview without writing.",
1048
+ },
1049
+ previewId: {
1050
+ type: "string",
1051
+ description: "Step 2 only: the previewId returned by the step-1 call.",
1052
+ },
1053
+ selectedIndexes: {
1054
+ type: "array",
1055
+ items: { type: "integer" },
1056
+ description:
1057
+ "Step 2 only: preview row indexes to write. Omit to write all staged rows.",
1058
+ },
1059
+ keepBothIndexes: {
1060
+ type: "array",
1061
+ items: { type: "integer" },
1062
+ description:
1063
+ "Step 2 only: preview indexes of duplicate-flagged rows the user explicitly wants to " +
1064
+ "keep anyway (the app's 'Keep Both').",
1065
+ },
1066
+ rowEdits: {
1067
+ type: "array",
1068
+ description:
1069
+ "Step 2 only: user-approved corrections, at most 50 rows. Fields: date (ISO " +
1070
+ "YYYY-MM-DD), source, amount, currency, category, paymentMethod, description, notes, " +
1071
+ "reference, fees, taxCollected, tag.",
1072
+ items: {
1073
+ type: "object",
1074
+ properties: {
1075
+ index: { type: "integer", description: "Preview row index" },
1076
+ fields: { type: "object", additionalProperties: true },
1077
+ },
1078
+ required: ["index", "fields"],
1079
+ },
1080
+ },
1081
+ bulkNote: {
1082
+ type: "string",
1083
+ description:
1084
+ "Step 2 only: one note (max 120 chars) prepended to every confirmed row's Notes, " +
1085
+ "same as the app's 'Add note to all entries'.",
1086
+ },
1087
+ },
1088
+ required: [],
1089
+ },
1090
+ },
841
1091
  {
842
1092
  name: "list_categories",
843
1093
  description:
@@ -1162,6 +1412,22 @@ const TOOLS = [
1162
1412
  "or General Settings link. Category, G/L, and account-code requests use " +
1163
1413
  "Category management; client, project, and trip groups use Group " +
1164
1414
  "management; questions about what counts as Personal use Personal rules. " +
1415
+ "When the user asks to choose receipt images from Google Photos, use the " +
1416
+ "returned Google Photos link; it opens the existing authenticated picker " +
1417
+ "and handles any required Google consent in ExpenseBot. When they ask " +
1418
+ "where ExpenseBot stores receipt files, return the Drive folder link only " +
1419
+ "when it is available; never invent or request a folder ID. " +
1420
+ "For a complete, unambiguous cash expense or mileage trip, use the direct " +
1421
+ "write tool. Use the returned Manual expense link for multiple entries, " +
1422
+ "credits/refunds, detailed tax/tip entry, per diem, incomplete details, or " +
1423
+ "visual review. Use the Mileage and travel link for route calculation, " +
1424
+ "mileage settings, repeated trips, calendar/rideshare imports, per diem, " +
1425
+ "or visual review. These links open the existing reviewed app forms. " +
1426
+ "When the user wants to import income from a screenshot, PDF, or CSV but " +
1427
+ "no attachment is available in chat (or the review is visually complex), " +
1428
+ "use the returned Import income links — they open the existing Add Income " +
1429
+ "importer, which parses the file and shows every row for review before " +
1430
+ "anything is saved. " +
1165
1431
  "Team setup requests use the returned role-aware Team setup handoff: " +
1166
1432
  "eligible solo business owners open Add teammates, while existing team " +
1167
1433
  "owners and co-admins open License Manager. If the handoff says owner " +
@@ -1470,9 +1736,13 @@ const TOOLS = [
1470
1736
  "Examples: 'group my Mexico meals for client Rob', 'put these Vegas expenses under the Vegas project', " +
1471
1737
  "or 'group these for client Rob and create a report'. The user does not need to know about tags: " +
1472
1738
  "ExpenseBot resolves the requested name against existing groups and proposes creating one only when needed. " +
1473
- "Use exact expenseId values returned by search_expenses. First call with confirm omitted/false for a grounded " +
1474
- "preview; after explicit user approval, repeat the same operationId and selection with confirm:true. " +
1475
- "The confirmed operation can create a report and returns exact report and Bill Client links. " +
1739
+ "Use exact expenseId values returned by search_expenses. A grounded preview is automatic for every bulk request; " +
1740
+ "the user does not need to ask for one. First call with confirm omitted/false, show the returned exact rows, count, " +
1741
+ "totals, proposed group, exclusions, and conflicts, then ask for approval. Only after explicit user approval, " +
1742
+ "repeat the same operationId and selection with confirm:true. A premature confirm:true is converted to preview. " +
1743
+ "When the request includes a report, set createReport:true on that confirmed group_expenses call and use its report result; do not run a separate broader create_report query. " +
1744
+ "For 'without personal expenses', set excludePersonal:true; ExpenseBot removes Personal-tagged and Personal-category rows before preview so their Personal marker is never overwritten. " +
1745
+ "The confirmed operation returns exact report and Bill Client links. Expenses already assigned to another ordinary report are excluded; if none remain, no duplicate report is created and the result links to Reports instead. Keep the user-facing response concise and do not add unsolicited tax or substantiation advice. Do not call check_compliance, get_report_details, or tax/deductibility tools before or after this workflow unless the user explicitly asks for that separate analysis. " +
1476
1746
  "Sharing remains a separate share_report action with recipient confirmation.",
1477
1747
  inputSchema: {
1478
1748
  type: "object",
@@ -1521,6 +1791,20 @@ const TOOLS = [
1521
1791
  approveNewGroup: { type: "boolean", description: "True only when the preview says a new group is required." },
1522
1792
  createReport: { type: "boolean", description: "Create a report from the exact eligible grouped expenses." },
1523
1793
  reportTitle: { type: "string" },
1794
+ excludePersonal: {
1795
+ type: "boolean",
1796
+ description: "Exclude Personal-tagged and Personal-category expenses from both grouping and the exact report.",
1797
+ },
1798
+ excludedTags: {
1799
+ type: "array",
1800
+ items: { type: "string" },
1801
+ description: "Existing groups to exclude before preview and grouping.",
1802
+ },
1803
+ excludedCategories: {
1804
+ type: "array",
1805
+ items: { type: "string" },
1806
+ description: "Expense categories to exclude before preview and grouping.",
1807
+ },
1524
1808
  status: { type: "boolean", description: "Read operation status using operationId." },
1525
1809
  undo: { type: "boolean", description: "Undo a completed grouping within its undo window." },
1526
1810
  },
@@ -1565,6 +1849,105 @@ const TOOLS = [
1565
1849
  required: ["expenseId", "fields"],
1566
1850
  },
1567
1851
  },
1852
+ {
1853
+ name: "correct_expenses",
1854
+ description:
1855
+ "Safely correct the category, business purpose, or explicit attendees on an exact bounded set of recorded expenses. " +
1856
+ "Examples: 'categorize these as Travel', 'add Client kickoff dinner as the business purpose for these meals', or " +
1857
+ "'add Fred, Rob, and Lamar to last night's business meal'. First use search_expenses to identify the exact rows, then pass their full expenseId values. " +
1858
+ "A grounded preview is automatic: first call with confirm omitted/false, show the exact count and proposed before-to-after changes, and ask once for approval. " +
1859
+ "Only after explicit approval repeat the same operationId, selection, and change with confirm:true. A premature confirm:true is converted to preview. " +
1860
+ "Attendee names must come explicitly from the user; never infer them. attendeeMode add preserves existing attendees, while replace substitutes only the attendee segment. " +
1861
+ "Business purpose and attendees preserve the structured Notes field, including card, description, inbox, and other typed segments. Formula Notes and changes that exceed the Notes limit are skipped safely. " +
1862
+ "The confirmed result reports applied/conflicted/failed counts and supports Undo. This tool does not omit duplicates, change amounts or dates, infer business context, or run broad Calendar matching. " +
1863
+ "For unsupported or more than 100-row cleanup, send the user to https://www.expensebot.ai/review-expenses?source=mcp.",
1864
+ inputSchema: {
1865
+ type: "object",
1866
+ additionalProperties: false,
1867
+ properties: {
1868
+ change: {
1869
+ type: "object",
1870
+ additionalProperties: false,
1871
+ description:
1872
+ "Exactly one correction. The selected type determines which matching value field is required.",
1873
+ properties: {
1874
+ type: {
1875
+ type: "string",
1876
+ enum: ["category", "businessPurpose", "attendees"],
1877
+ },
1878
+ category: { type: "string" },
1879
+ businessPurpose: { type: "string" },
1880
+ attendees: {
1881
+ type: "array",
1882
+ minItems: 1,
1883
+ maxItems: 25,
1884
+ items: { type: "string" },
1885
+ },
1886
+ attendeeMode: {
1887
+ type: "string",
1888
+ enum: ["add", "replace"],
1889
+ description:
1890
+ "Use add unless the user explicitly asks to replace existing attendees.",
1891
+ },
1892
+ },
1893
+ required: ["type"],
1894
+ },
1895
+ selection: {
1896
+ type: "object",
1897
+ additionalProperties: false,
1898
+ properties: {
1899
+ items: {
1900
+ type: "array",
1901
+ minItems: 1,
1902
+ maxItems: 100,
1903
+ items: {
1904
+ type: "object",
1905
+ additionalProperties: false,
1906
+ properties: {
1907
+ receiptId: {
1908
+ type: "string",
1909
+ description:
1910
+ "Exact full expenseId/Column-Q receipt identity from search_expenses.",
1911
+ },
1912
+ expected: {
1913
+ type: "object",
1914
+ additionalProperties: false,
1915
+ description:
1916
+ "Optional optimistic-concurrency values copied from the search result.",
1917
+ properties: {
1918
+ category: { type: "string" },
1919
+ notes: { type: "string" },
1920
+ },
1921
+ },
1922
+ },
1923
+ required: ["receiptId"],
1924
+ },
1925
+ },
1926
+ },
1927
+ required: ["items"],
1928
+ },
1929
+ operationId: {
1930
+ type: "string",
1931
+ pattern: "^expense-bulk:[a-zA-Z0-9_-]{8,100}$",
1932
+ description:
1933
+ "Stable idempotency key generated once for preview and reused unchanged.",
1934
+ },
1935
+ confirm: {
1936
+ type: "boolean",
1937
+ description: "Omit/false for preview; true only after explicit approval.",
1938
+ },
1939
+ status: {
1940
+ type: "boolean",
1941
+ description: "Read operation status using operationId.",
1942
+ },
1943
+ undo: {
1944
+ type: "boolean",
1945
+ description: "Undo a completed correction within its Undo window.",
1946
+ },
1947
+ },
1948
+ required: ["operationId"],
1949
+ },
1950
+ },
1568
1951
  ];
1569
1952
 
1570
1953
  // Tools available without authentication (onboarding mode)
@@ -1657,6 +2040,7 @@ async function handleTool(name, args) {
1657
2040
  return formatResult(
1658
2041
  await client.execute("help_compliance", {
1659
2042
  reportId: args.reportId,
2043
+ userRequest: args.userRequest,
1660
2044
  })
1661
2045
  );
1662
2046
 
@@ -1745,6 +2129,14 @@ async function handleTool(name, args) {
1745
2129
  case "add_income":
1746
2130
  return formatResult(await client.execute("add_income", args));
1747
2131
 
2132
+ // Two-phase income import (v-next) — pass-through; the backend owns the
2133
+ // parse -> durable preview -> confirm -> chunked canonical write contract.
2134
+ case "add_income_from_file":
2135
+ return formatResult(await client.execute("add_income_from_file", args));
2136
+
2137
+ case "add_income_from_csv":
2138
+ return formatResult(await client.execute("add_income_from_csv", args));
2139
+
1748
2140
  case "list_categories":
1749
2141
  return formatResult(await client.execute("list_categories", {}));
1750
2142
 
@@ -2004,6 +2396,21 @@ async function handleTool(name, args) {
2004
2396
  approveNewGroup: args.approveNewGroup,
2005
2397
  createReport: args.createReport,
2006
2398
  reportTitle: args.reportTitle,
2399
+ excludePersonal: args.excludePersonal,
2400
+ excludedTags: args.excludedTags,
2401
+ excludedCategories: args.excludedCategories,
2402
+ status: args.status,
2403
+ undo: args.undo,
2404
+ })
2405
+ );
2406
+
2407
+ case "correct_expenses":
2408
+ return formatResult(
2409
+ await client.execute("correct_expenses", {
2410
+ change: args.change,
2411
+ selection: args.selection,
2412
+ operationId: args.operationId,
2413
+ confirm: args.confirm,
2007
2414
  status: args.status,
2008
2415
  undo: args.undo,
2009
2416
  })
@@ -2047,6 +2454,16 @@ function formatResult(result) {
2047
2454
  return { content: [{ type: "text", text: errText }], isError: true };
2048
2455
  }
2049
2456
 
2457
+ // Terminal write results already contain the exact user-facing closeout.
2458
+ // Returning only that text keeps stdio aligned with remote and prevents a
2459
+ // model from reopening settled scope using raw report projections.
2460
+ if (typeof result?.finalAnswer === "string" && result.finalAnswer.trim()) {
2461
+ return {
2462
+ content: [{ type: "text", text: result.finalAnswer.trim() }],
2463
+ isError: false,
2464
+ };
2465
+ }
2466
+
2050
2467
  // Extract the meaningful content
2051
2468
  let text;
2052
2469
  if (result?.message && typeof result.message === "string") {
@@ -2106,7 +2523,7 @@ function formatResult(result) {
2106
2523
 
2107
2524
  async function main() {
2108
2525
  const server = new Server(
2109
- { name: "expensebot-auth", version: "0.6.13" },
2526
+ { name: "expensebot-auth", version: "0.6.17" },
2110
2527
  { capabilities: { tools: {} }, instructions: SERVER_INSTRUCTIONS }
2111
2528
  );
2112
2529
 
package/src/test.js CHANGED
@@ -15,6 +15,7 @@
15
15
  */
16
16
 
17
17
  import { spawn } from "node:child_process";
18
+ import { readFileSync } from "node:fs";
18
19
  import { fileURLToPath } from "node:url";
19
20
  import path from "node:path";
20
21
  import { readStructuredHttpError } from "./client.js";
@@ -22,7 +23,7 @@ import { readStructuredHttpError } from "./client.js";
22
23
  const __dirname = path.dirname(fileURLToPath(import.meta.url));
23
24
  const SERVER_PATH = path.join(__dirname, "index.js");
24
25
 
25
- const EXPECTED_TOOL_COUNT = 47; // + conversational client/project grouping
26
+ const EXPECTED_TOOL_COUNT = 50;
26
27
  const REQUIRED_TOOLS = [
27
28
  // v0.5.x
28
29
  "search_expenses",
@@ -52,6 +53,7 @@ const REQUIRED_TOOLS = [
52
53
  "get_scan_status",
53
54
  "update_expense",
54
55
  "group_expenses",
56
+ "correct_expenses",
55
57
  // Phase 4B — read-only surfaces for shipped product data
56
58
  "list_client_invoices",
57
59
  "get_expense_splits",
@@ -165,6 +167,12 @@ function check(label, ok, details = "") {
165
167
 
166
168
  (async () => {
167
169
  console.log("=== mcp-server-auth smoke test ===\n");
170
+ const serverSource = readFileSync(SERVER_PATH, "utf8");
171
+ check(
172
+ "stdio formatter emits terminal finalAnswer without raw-data append",
173
+ /if \(typeof result\?\.finalAnswer === "string"/.test(serverSource) &&
174
+ /text: result\.finalAnswer\.trim\(\)/.test(serverSource)
175
+ );
168
176
  const structuredFailure = await readStructuredHttpError(
169
177
  new Response(
170
178
  JSON.stringify({
@@ -194,6 +202,28 @@ function check(label, ok, details = "") {
194
202
  /search_knowledge/.test(instructions) &&
195
203
  /fullAnswer:true/.test(instructions)
196
204
  );
205
+ check(
206
+ "initialize instructions keep approved workflows concise",
207
+ /one clear yes\/no confirmation/i.test(instructions) &&
208
+ /complete every approved step/i.test(instructions) &&
209
+ /unsolicited tax/i.test(instructions) &&
210
+ /NOT a request for compliance/i.test(instructions)
211
+ );
212
+ check(
213
+ "initialize instructions preserve authoritative tool outcomes",
214
+ /never recompute/i.test(instructions) &&
215
+ /without reopening/i.test(instructions) &&
216
+ /unrequested advice/i.test(instructions) &&
217
+ /terminal write result supersedes intermediate search/i.test(instructions) &&
218
+ /excluded near-matches/i.test(instructions) &&
219
+ /return it verbatim and add nothing else/i.test(instructions)
220
+ );
221
+ check(
222
+ "initialize instructions preserve report provenance",
223
+ /creationStatus=created_this_call/.test(instructions) &&
224
+ /list_reports are pre-existing/i.test(instructions) &&
225
+ /never created or generated/i.test(instructions)
226
+ );
197
227
 
198
228
  // 1. tools/list shape
199
229
  const listResp = byId.get(2);
@@ -204,6 +234,20 @@ function check(label, ok, details = "") {
204
234
  `(got ${typeof tools})`
205
235
  );
206
236
  if (Array.isArray(tools)) {
237
+ const complianceTool = tools.find((tool) => tool.name === "check_compliance");
238
+ const reportDetailsTool = tools.find((tool) => tool.name === "get_report_details");
239
+ check(
240
+ "compliance and report-detail tools are explicit opt-in",
241
+ /only when the user explicitly asks/i.test(complianceTool?.description || "") &&
242
+ /billing a client is not a compliance request/i.test(
243
+ complianceTool?.description || ""
244
+ ) &&
245
+ complianceTool?.inputSchema?.required?.includes("userRequest") &&
246
+ /only when the user explicitly asks/i.test(
247
+ reportDetailsTool?.description || ""
248
+ ) &&
249
+ reportDetailsTool?.inputSchema?.required?.includes("userRequest")
250
+ );
207
251
  check(
208
252
  `tools/list count = ${EXPECTED_TOOL_COUNT}`,
209
253
  tools.length === EXPECTED_TOOL_COUNT,
@@ -223,6 +267,19 @@ function check(label, ok, details = "") {
223
267
  noDesc.length === 0,
224
268
  noDesc.length ? `missing on: ${noDesc.map((t) => t.name).join(", ")}` : ""
225
269
  );
270
+ const fileParamContracts = {
271
+ submit_receipt: "photo",
272
+ add_income_from_file: "photo",
273
+ add_income_from_csv: "csvContent",
274
+ };
275
+ check(
276
+ "binary/text attachment tools advertise OpenAI file parameters",
277
+ Object.entries(fileParamContracts).every(([name, field]) =>
278
+ tools
279
+ .find((tool) => tool.name === name)
280
+ ?._meta?.["openai/fileParams"]?.includes(field)
281
+ )
282
+ );
226
283
  const updateExpense = tools.find((tool) => tool.name === "update_expense");
227
284
  check(
228
285
  "update_expense requires exact Column-Q expenseId and exposes no rowNumber",
@@ -238,6 +295,17 @@ function check(label, ok, details = "") {
238
295
  updateExpense?.inputSchema?.properties?.expenseId?.description || ""
239
296
  )
240
297
  );
298
+ const addCashExpense = tools.find((tool) => tool.name === "add_cash_expense");
299
+ check(
300
+ "add_cash_expense exposes canonical client-advance intake",
301
+ addCashExpense?.inputSchema?.properties?.isClientAdvance?.type ===
302
+ "boolean" &&
303
+ addCashExpense?.inputSchema?.properties?.clientName?.type === "string" &&
304
+ !addCashExpense?.inputSchema?.required?.includes("merchant") &&
305
+ !addCashExpense?.inputSchema?.required?.includes("category") &&
306
+ /negative expense/i.test(addCashExpense?.description || "") &&
307
+ /never for vendor refunds/i.test(addCashExpense?.description || "")
308
+ );
241
309
  const searchExpenses = tools.find((tool) => tool.name === "search_expenses");
242
310
  check(
243
311
  "search_expenses exposes opaque cursor pagination",
@@ -263,6 +331,34 @@ function check(label, ok, details = "") {
263
331
  createReport?.description || ""
264
332
  )
265
333
  );
334
+ const groupExpenses = tools.find((tool) => tool.name === "group_expenses");
335
+ check(
336
+ "group_expenses makes preview automatic before every bulk write",
337
+ groupExpenses?.inputSchema?.properties?.confirm?.type === "boolean" &&
338
+ groupExpenses?.inputSchema?.properties?.excludePersonal?.type ===
339
+ "boolean" &&
340
+ groupExpenses?.inputSchema?.properties?.excludedTags?.items?.type ===
341
+ "string" &&
342
+ /preview is automatic/i.test(groupExpenses?.description || "") &&
343
+ /premature confirm:true is converted to preview/i.test(
344
+ groupExpenses?.description || ""
345
+ )
346
+ );
347
+ const correctExpenses = tools.find(
348
+ (tool) => tool.name === "correct_expenses"
349
+ );
350
+ check(
351
+ "correct_expenses is exact, bounded, typed, and reversible",
352
+ correctExpenses?.inputSchema?.properties?.selection?.properties?.items
353
+ ?.maxItems === 100 &&
354
+ correctExpenses?.inputSchema?.properties?.change?.properties?.attendees
355
+ ?.maxItems === 25 &&
356
+ correctExpenses?.inputSchema?.properties?.change?.properties?.attendeeMode
357
+ ?.enum?.includes("replace") &&
358
+ /preview is automatic/i.test(correctExpenses?.description || "") &&
359
+ /supports Undo/i.test(correctExpenses?.description || "") &&
360
+ /does not omit duplicates/i.test(correctExpenses?.description || "")
361
+ );
266
362
  const searchKnowledge = tools.find((tool) => tool.name === "search_knowledge");
267
363
  check(
268
364
  "search_knowledge exposes bounded full-answer retrieval",
@@ -1,10 +0,0 @@
1
- {
2
- "_meta": {
3
- "generatedAt": "2026-05-07T05:13:24.014Z",
4
- "sourceKb": "../server/config/kb/entries/income-and-pnl-analytics.md",
5
- "note": "Auto-generated from KB. Do NOT edit by hand — re-run `npm run gen-descriptions` after the KB changes."
6
- },
7
- "get_income_summary": "Get income totals and breakdowns from the Income tab — Schedule C / T2125 basis. Excludes Schedule B (interest, dividends), tax refunds, and security deposits (mirrors year-end report routing). Examples: \"How much income YTD?\", \"Income by source\", \"by month\", \"by payment method\".",
8
- "get_pnl": "Compute Profit & Loss across the Income tab and expenses. Examples: \"Am I profitable this year?\", \"Net income last quarter\", \"What's my margin?\", \"P&L for Q1\".",
9
- "get_per_tag_pnl": "Per-tag P&L — revenue, cost, profit, and margin grouped by tag. Requires both income AND expense rows to be tagged consistently. Examples: ."
10
- }