@expensebot/mcp-server-auth 0.6.0 → 0.6.2

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,14 +2,28 @@
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
- **31 tools** across:
5
+ **44 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
- - **Receipt capture** — `submit_receipt` (photo/PDF), `add_cash_expense`, `add_mileage_entry`, `add_income`, `parse_expense`, `get_expense_by_id`
9
- - **Gmail** — `scan_gmail`, `process_gmail_receipts`
10
- - **Reports** — `create_report`, `list_reports`, `get_report_details`, `share_report`, `export_report`
8
+ - **Mileage & Subscriptions** *(v0.6.1)* — `get_mileage_summary`, `get_subscription_audit`
9
+ - **Receipt capture** — `submit_receipt` (photo/PDF), `add_cash_expense`, `add_mileage_entry`, `add_income`, `parse_expense`, `get_expense_by_id`, `update_expense`
10
+ - **Gmail** — `scan_gmail`, `process_gmail_receipts`, `scan_gmail_years`, `get_scan_status`
11
+ - **Reports & invoicing** — `create_report`, `list_reports`, `get_report_details`, `share_report`, `export_report`, `list_client_invoices`
12
+ - **Expense review** — `get_expense_splits`, `get_monthly_books_review`, `get_credits_refunds`
11
13
  - **Compliance & tax** — `check_compliance`, `fix_compliance`, `check_tax_deductibility`
12
- - **Activity & onboarding** — `get_recent_activity`, `get_signup_link`, `get_pricing`, `check_feature`, `start_trial_link`
14
+ - **Activity, tracing & onboarding** — `get_recent_activity`, `trace_document`, `get_signup_link`, `get_pricing`, `check_feature`, `start_trial_link`
15
+ - **Business what-if** — `whatif_afford`, `whatif_client`, `whatif_tax_setaside`
16
+
17
+ ### Expense identity contract
18
+
19
+ `search_expenses` returns an `expenseId` for each update-eligible result. That
20
+ value is the exact full Receipt ID stored in Column Q, including any
21
+ `::driveFileId` suffix. Pass it unchanged to `update_expense`. Never substitute
22
+ a displayed date, a bare receipt-ID prefix, or a sheet row number: dates are
23
+ not identities, bare IDs can collide, and row numbers move when rows are
24
+ prepended. `update_expense` refuses zero or multiple exact matches.
25
+
26
+ **Period comparison** — All analytics tools (spending, income, P&L, per-tag P&L, mileage) accept YoY / MoM / QoQ / same-month-prev-year phrasing in the `query` field. Margin is rendered loss-aware (multiplier when expenses exceed revenue) so AI clients see "expenses 5.4× revenue" instead of "-436.9% margin".
13
27
 
14
28
  ## Setup
15
29
 
@@ -109,6 +123,33 @@ Exposes the ExpenseBot knowledge base, FAQ, and feature docs as MCP resources. U
109
123
  - Issues: email `support@expensebot.ai`
110
124
  - Roadmap (remote HTTPS MCP for ChatGPT + Claude.ai web): <https://www.expensebot.ai/mcp>
111
125
 
126
+ ## Maintainer: adding or changing a tool
127
+
128
+ The stdio `TOOLS[]` catalog in `src/index.js` is the schema source of truth, but
129
+ it is only one part of the release. A new MCP tool must also be registered in
130
+ the main app's shared action policy, and a deliberate decision must be made
131
+ about whether the same tool belongs in ExpenseBot's in-app chat.
132
+
133
+ Required workflow:
134
+
135
+ 1. Add the `TOOLS[]` definition and matching `handleTool()` case here.
136
+ 2. Run `npm run sync-check` and `npm test`; update the inventory and versioned
137
+ package metadata when publishing.
138
+ 3. Run `npm run sync-tools` from `mcp-server-remote/` and commit the generated
139
+ catalog.
140
+ 4. Register the backend action in `server/config/actionPolicy.js` and the tool
141
+ in `server/config/toolPolicy.js`, with explicit `mcp` and/or `chat`
142
+ `surfaces`.
143
+ 5. Verify remote `TOOL_TO_ACTION`, metadata/exclusions, main-route parity, and
144
+ policy coverage tests.
145
+ 6. For a chat-visible write, do not enable it until it has the durable
146
+ confirmation adapter and result probe required by the canonical contract.
147
+
148
+ The complete bidirectional checklist and deployment matrix are in
149
+ `docs/architecture/mcp-and-chat-tool-surface.md`. In particular, changing the
150
+ main backend does not require republishing this npm package unless this
151
+ package's schema, local dispatch, or transport also changed.
152
+
112
153
  ## License
113
154
 
114
155
  MIT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@expensebot/mcp-server-auth",
3
- "version": "0.6.0",
3
+ "version": "0.6.2",
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": {
@@ -65,12 +65,14 @@ const serverVersionMatch = indexSrc.match(
65
65
  const serverVersion = serverVersionMatch?.[1];
66
66
 
67
67
  // Extract advertised tool count from get_signup_link message
68
- const advertisedCountMatch = indexSrc.match(
69
- /unlock all (\d+) tools/i
70
- );
71
- const advertisedCount = advertisedCountMatch?.[1]
72
- ? parseInt(advertisedCountMatch[1], 10)
73
- : null;
68
+ const advertisedCountMatch = indexSrc.match(/unlock all (\d+) tools/i);
69
+ const usesDynamicAdvertisedCount =
70
+ /unlock all \$\{TOOLS\.length\} tools/i.test(indexSrc);
71
+ const advertisedCount = usesDynamicAdvertisedCount
72
+ ? tools.length
73
+ : advertisedCountMatch?.[1]
74
+ ? parseInt(advertisedCountMatch[1], 10)
75
+ : null;
74
76
 
75
77
  // ── 2. Cross-check: every tool has a case branch ────────────────────
76
78
  const missingCases = tools.filter((t) => !cases.has(t));
@@ -160,7 +162,10 @@ console.log(`package.json version: ${pkg.version}`);
160
162
  console.log(`server.json version: ${serverJson.version}`);
161
163
  console.log(`Server version: ${serverVersion ?? "n/a"}`);
162
164
  console.log(`User-Agent version: ${uaVersion ?? "n/a"}`);
163
- console.log(`Advertised tool count: ${advertisedCount ?? "n/a"}`);
165
+ console.log(
166
+ `Advertised tool count: ${advertisedCount ?? "n/a"}` +
167
+ (usesDynamicAdvertisedCount ? " (dynamic)" : "")
168
+ );
164
169
  console.log("");
165
170
 
166
171
  if (warnings.length) {
package/src/client.js CHANGED
@@ -20,7 +20,7 @@ export class ExpenseBotClient {
20
20
  headers: {
21
21
  Authorization: `Bearer ${this.token}`,
22
22
  "Content-Type": "application/json",
23
- "User-Agent": "expensebot-mcp-auth/0.6.0",
23
+ "User-Agent": "expensebot-mcp-auth/0.6.2",
24
24
  ...options.headers,
25
25
  },
26
26
  body: options.body ? JSON.stringify(options.body) : undefined,
package/src/index.js CHANGED
@@ -49,6 +49,105 @@ if (onboardingMode) {
49
49
  );
50
50
  }
51
51
 
52
+ // ── Shared schemas ─────────────────────────────────────────────────────
53
+ //
54
+ // dateRange is a discriminated union — historically every analytics tool
55
+ // inlined the same flat object with all fields optional. OpenAI's app-review
56
+ // scanner flagged that as "Unclear Arguments: dateRange has multiple required
57
+ // fields with type as free-form string; unclear valid values/required fields
58
+ // per type." (2026-05-28 review feedback). Switching to oneOf with const
59
+ // discriminators on `type` makes the per-variant required set explicit:
60
+ // - { type: "month", month, year }
61
+ // - { type: "quarter", quarter, year }
62
+ // - { type: "year", year }
63
+ // - { type: "specific", start, end } // ISO YYYY-MM-DD
64
+ // - { type: "relative", value } // "last month", "YTD", …
65
+ // Keep this in sync with the runtime in analyticsController.js — the union
66
+ // only describes legal SHAPES; the controller still tolerates legacy
67
+ // flat-object callers for backward compat with old client builds.
68
+
69
+ const DATE_RANGE_SCHEMA = {
70
+ description:
71
+ "Time period filter. Use exactly one variant — pick the shape that matches the user's phrasing.",
72
+ oneOf: [
73
+ {
74
+ type: "object",
75
+ title: "Specific month",
76
+ properties: {
77
+ type: { type: "string", const: "month" },
78
+ month: {
79
+ type: "string",
80
+ description: "Month name or 1-12 (e.g., 'March' or '3')",
81
+ },
82
+ year: { type: "integer", description: "4-digit year (e.g., 2026)" },
83
+ },
84
+ required: ["type", "month", "year"],
85
+ additionalProperties: false,
86
+ },
87
+ {
88
+ type: "object",
89
+ title: "Quarter of a year",
90
+ properties: {
91
+ type: { type: "string", const: "quarter" },
92
+ quarter: { type: "integer", minimum: 1, maximum: 4 },
93
+ year: { type: "integer" },
94
+ },
95
+ required: ["type", "quarter", "year"],
96
+ additionalProperties: false,
97
+ },
98
+ {
99
+ type: "object",
100
+ title: "Full year",
101
+ properties: {
102
+ type: { type: "string", const: "year" },
103
+ year: { type: "integer" },
104
+ },
105
+ required: ["type", "year"],
106
+ additionalProperties: false,
107
+ },
108
+ {
109
+ type: "object",
110
+ title: "Specific date range",
111
+ properties: {
112
+ type: { type: "string", const: "specific" },
113
+ start: {
114
+ type: "string",
115
+ format: "date",
116
+ description: "ISO date YYYY-MM-DD (inclusive)",
117
+ },
118
+ end: {
119
+ type: "string",
120
+ format: "date",
121
+ description: "ISO date YYYY-MM-DD (inclusive)",
122
+ },
123
+ },
124
+ required: ["type", "start", "end"],
125
+ additionalProperties: false,
126
+ },
127
+ {
128
+ type: "object",
129
+ title: "Relative natural-language range",
130
+ properties: {
131
+ type: { type: "string", const: "relative" },
132
+ value: {
133
+ type: "string",
134
+ description:
135
+ "Relative range phrase, e.g., 'last month', 'YTD', 'this quarter', 'last 7 days'",
136
+ },
137
+ },
138
+ required: ["type", "value"],
139
+ additionalProperties: false,
140
+ },
141
+ ],
142
+ };
143
+
144
+ const CLIENT_EMAIL_SCHEMA = {
145
+ type: "string",
146
+ format: "email",
147
+ description:
148
+ "Client account email. Accountants may use this only for an accepted ExpenseBot client.",
149
+ };
150
+
52
151
  // ── Tool Definitions ───────────────────────────────────────────────────
53
152
 
54
153
  const TOOLS = [
@@ -57,10 +156,12 @@ const TOOLS = [
57
156
  description:
58
157
  "Search and filter the user's expenses. Returns matching expense rows " +
59
158
  "from their spreadsheet. Filter by category, merchant, date range, " +
60
- "amount, or tags.",
159
+ "amount, or tags. Each result includes expenseId, the exact durable " +
160
+ "Receipt ID required by update_expense.",
61
161
  inputSchema: {
62
162
  type: "object",
63
163
  properties: {
164
+ clientEmail: CLIENT_EMAIL_SCHEMA,
64
165
  categories: {
65
166
  type: "array",
66
167
  items: { type: "string" },
@@ -71,19 +172,7 @@ const TOOLS = [
71
172
  items: { type: "string" },
72
173
  description: "Filter by merchant names (e.g., ['Uber', 'Starbucks'])",
73
174
  },
74
- dateRange: {
75
- type: "object",
76
- description: "Time period filter",
77
- properties: {
78
- type: { type: "string", enum: ["month", "quarter", "year", "specific", "relative"] },
79
- month: { type: "string" },
80
- year: { type: "integer" },
81
- quarter: { type: "integer", minimum: 1, maximum: 4 },
82
- value: { type: "string", description: "Relative date like 'last month', 'this week'" },
83
- start: { type: "string", format: "date" },
84
- end: { type: "string", format: "date" },
85
- },
86
- },
175
+ dateRange: DATE_RANGE_SCHEMA,
87
176
  minAmount: { type: "number", description: "Minimum expense amount" },
88
177
  maxAmount: { type: "number", description: "Maximum expense amount" },
89
178
  tags: { type: "array", items: { type: "string" }, description: "Filter by tags" },
@@ -94,31 +183,29 @@ const TOOLS = [
94
183
  {
95
184
  name: "get_spending_summary",
96
185
  description:
97
- "Get totals, breakdowns, and analytics across BOTH expenses and " +
98
- "income for fast questions. Examples: 'how much did I spend last " +
99
- "month', 'income YTD', 'rental income by property', 'P&L for Q1', " +
100
- "'profit by client'. Covers expenses, income (Schedule C / T2125), " +
101
- "Schedule B (interest/dividends), tax refunds, P&L, and per-tag P&L. " +
102
- "Returns: { message, data: { total, breakdown, sampleMeta? } }.",
186
+ "Unified analytics endpoint — handles expenses, income, P&L, " +
187
+ "per-tag P&L (per-client / per-property / per-event), Schedule B " +
188
+ "drill-in (interest, dividends, tax refunds, security deposits), " +
189
+ "mileage, and subscription audits in ONE tool. Examples: 'how much " +
190
+ "did I spend last month', 'income YTD', 'rental income by " +
191
+ "property', 'P&L for Q1', 'profit by client', 'mileage this year', " +
192
+ "'recurring subscriptions', 'price increases', 'duplicate " +
193
+ "subscriptions', 'trial conversions'. Supports period comparison " +
194
+ "phrasing — 'this year vs last' (YoY), 'vs last month' (MoM), 'Q1 " +
195
+ "vs Q2' (QoQ), same-month-prev-year. Margin renders as multiplier " +
196
+ "('expenses 5.4× revenue') when in loss territory. Returns: " +
197
+ "{ message, data: { total, breakdown?, comparison?, sampleMeta? } }.",
103
198
  inputSchema: {
104
199
  type: "object",
105
200
  properties: {
201
+ clientEmail: CLIENT_EMAIL_SCHEMA,
106
202
  query: {
107
203
  type: "string",
108
204
  description:
109
205
  "Natural language question (e.g., 'how much did I spend in March', 'rental income by property')",
110
206
  },
111
207
  categories: { type: "array", items: { type: "string" } },
112
- dateRange: {
113
- type: "object",
114
- properties: {
115
- type: { type: "string" },
116
- month: { type: "string" },
117
- year: { type: "integer" },
118
- quarter: { type: "integer" },
119
- value: { type: "string" },
120
- },
121
- },
208
+ dateRange: DATE_RANGE_SCHEMA,
122
209
  groupBy: { type: "string", enum: ["category", "merchant", "month", "tag", "source", "paymentMethod"] },
123
210
  metric: { type: "string", enum: ["total", "count", "average"] },
124
211
  },
@@ -140,15 +227,7 @@ const TOOLS = [
140
227
  type: "string",
141
228
  description: "The analytics question to answer",
142
229
  },
143
- dateRange: {
144
- type: "object",
145
- properties: {
146
- type: { type: "string" },
147
- month: { type: "string" },
148
- year: { type: "integer" },
149
- quarter: { type: "integer" },
150
- },
151
- },
230
+ dateRange: DATE_RANGE_SCHEMA,
152
231
  },
153
232
  required: ["query"],
154
233
  },
@@ -161,18 +240,7 @@ const TOOLS = [
161
240
  inputSchema: {
162
241
  type: "object",
163
242
  properties: {
164
- dateRange: {
165
- type: "object",
166
- description: "Time period for the report (required)",
167
- properties: {
168
- type: { type: "string", enum: ["month", "quarter", "year", "specific"] },
169
- month: { type: "string" },
170
- year: { type: "integer" },
171
- quarter: { type: "integer" },
172
- start: { type: "string", format: "date" },
173
- end: { type: "string", format: "date" },
174
- },
175
- },
243
+ dateRange: DATE_RANGE_SCHEMA,
176
244
  title: { type: "string", description: "Custom report title" },
177
245
  categories: { type: "array", items: { type: "string" } },
178
246
  tags: { type: "array", items: { type: "string" } },
@@ -193,6 +261,7 @@ const TOOLS = [
193
261
  inputSchema: {
194
262
  type: "object",
195
263
  properties: {
264
+ clientEmail: CLIENT_EMAIL_SCHEMA,
196
265
  page: { type: "integer", default: 1 },
197
266
  limit: { type: "integer", default: 20 },
198
267
  filter: { type: "string", enum: ["All", "Draft", "Submitted", "Shared"], default: "All" },
@@ -207,6 +276,7 @@ const TOOLS = [
207
276
  inputSchema: {
208
277
  type: "object",
209
278
  properties: {
279
+ clientEmail: CLIENT_EMAIL_SCHEMA,
210
280
  reportId: { type: "string", description: "The report/spreadsheet ID" },
211
281
  },
212
282
  required: ["reportId"],
@@ -337,7 +407,9 @@ const TOOLS = [
337
407
  name: "add_cash_expense",
338
408
  description:
339
409
  "Add an expense without a receipt (cash purchase, tip, etc.). " +
340
- "Writes directly to the user's expense spreadsheet.",
410
+ "Writes directly to the user's expense spreadsheet. Call list_categories " +
411
+ "first and choose one of the user's configured Expense Accounts. A unique " +
412
+ "account-label alias may be canonicalized, but unknown or ambiguous categories are rejected.",
341
413
  inputSchema: {
342
414
  type: "object",
343
415
  properties: {
@@ -348,7 +420,11 @@ const TOOLS = [
348
420
  description: "Expense date (YYYY-MM-DD)",
349
421
  format: "date",
350
422
  },
351
- category: { type: "string", description: "Expense category" },
423
+ category: {
424
+ type: "string",
425
+ description:
426
+ "A configured Expense Account returned by list_categories. Do not invent a category.",
427
+ },
352
428
  subtotal: { type: "number", description: "Subtotal before tax" },
353
429
  tax: { type: "number", description: "Tax amount" },
354
430
  tip: { type: "number", description: "Tip amount" },
@@ -405,9 +481,11 @@ const TOOLS = [
405
481
  name: "scan_gmail",
406
482
  description:
407
483
  "Trigger a background Gmail scan to discover and process receipt " +
408
- "emails. Runs asynchronously — returns immediately, user gets an " +
409
- 'email summary when done. Like clicking "Find Receipts in Gmail" ' +
410
- "in the UI. Default: scans last 60 days.",
484
+ "emails from the last ~60 days (default). Runs asynchronously — " +
485
+ "returns immediately, user gets an email summary when done. Like " +
486
+ 'clicking "Find Receipts in Gmail" in the UI. For whole PAST YEARS ' +
487
+ "(e.g. 2023, or 2020-2022) use scan_gmail_years instead; to check a " +
488
+ "scan's progress use get_scan_status.",
411
489
  inputSchema: {
412
490
  type: "object",
413
491
  properties: {
@@ -506,7 +584,9 @@ const TOOLS = [
506
584
  description:
507
585
  "Log an income entry manually (cash, check, Stripe payout, etc.). " +
508
586
  "Writes to the Income tab of the user's expense spreadsheet. Useful " +
509
- "for income that isn't auto-detected from Gmail or Plaid.",
587
+ "for income that isn't auto-detected from Gmail or Plaid. Call " +
588
+ "list_income_categories first and use one of its fixed tax categories; " +
589
+ "an omitted category defaults to Service income and an unknown category is rejected.",
510
590
  inputSchema: {
511
591
  type: "object",
512
592
  properties: {
@@ -517,7 +597,7 @@ const TOOLS = [
517
597
  },
518
598
  paymentMethod: {
519
599
  type: "string",
520
- description: "How you got paid (e.g., 'Cash', 'Check', 'Stripe', 'Bank Transfer', 'Venmo')",
600
+ description: "How you got paid. Canonical rails are Cash, Check, Bank transfer, Wallet app, Credit/Debit card, Payment processor, or Other; common labels such as Stripe and Venmo are normalized.",
521
601
  },
522
602
  date: {
523
603
  type: "string",
@@ -526,7 +606,7 @@ const TOOLS = [
526
606
  },
527
607
  currency: { type: "string", description: "Currency code (default: home currency)" },
528
608
  description: { type: "string", description: "What the income was for" },
529
- category: { type: "string", description: "Income category (optional)" },
609
+ category: { type: "string", description: "A category returned by list_income_categories (optional; defaults to Service income)" },
530
610
  reference: { type: "string", description: "Invoice or transaction reference" },
531
611
  fees: { type: "number", description: "Processor/transfer fees deducted" },
532
612
  taxCollected: { type: "number", description: "Sales tax/GST/HST collected" },
@@ -564,13 +644,18 @@ const TOOLS = [
564
644
  name: "get_income_summary",
565
645
  description:
566
646
  "Get income totals, breakdowns, and analytics from the Income tab. " +
567
- "Covers Schedule C / T2125 income, Schedule B (interest, dividends), " +
568
- "tax refunds, rental income, and per-source/per-payment-method/per-" +
569
- "category/per-month breakdowns. Excludes security deposits (tenant " +
570
- "funds, not taxable). Examples: 'income YTD', 'income by source', " +
647
+ "Covers Schedule C / T2125 income, Schedule B drill-in (interest, " +
648
+ "dividends, tax refunds, security deposits), rental income, and " +
649
+ "per-source / per-payment-method / per-category / per-month / " +
650
+ "per-tag breakdowns. Schedule-C-style category exclusions match " +
651
+ "year-end T6 routing (security deposits, refunds excluded from " +
652
+ "taxable totals). Examples: 'income YTD', 'income by source', " +
571
653
  "'rental income by property', 'interest income this year', " +
572
- "'dividends YTD', 'tax refunds 2024'. Returns: { message, data: " +
573
- "{ total, breakdown?, sampleMeta? } }.",
654
+ "'dividends YTD', 'tax refunds 2024', 'income this year vs last' " +
655
+ "(YoY). Supports period comparison phrasing — YoY ('vs last year'), " +
656
+ "MoM ('vs last month'), QoQ ('Q1 vs Q2'), same-month-prev-year. " +
657
+ "Returns: { message, data: { total, breakdown?, comparison?, " +
658
+ "sampleMeta? } }.",
574
659
  inputSchema: {
575
660
  type: "object",
576
661
  properties: {
@@ -584,16 +669,7 @@ const TOOLS = [
584
669
  enum: ["source", "category", "month", "paymentMethod", "tag"],
585
670
  description: "How to group the breakdown",
586
671
  },
587
- dateRange: {
588
- type: "object",
589
- properties: {
590
- type: { type: "string" },
591
- month: { type: "string" },
592
- year: { type: "integer" },
593
- quarter: { type: "integer" },
594
- value: { type: "string", description: "Relative date like 'YTD', 'last quarter'" },
595
- },
596
- },
672
+ dateRange: DATE_RANGE_SCHEMA,
597
673
  incomeTagPrefix: {
598
674
  type: "string",
599
675
  description:
@@ -607,26 +683,22 @@ const TOOLS = [
607
683
  description:
608
684
  "Compute Profit & Loss (P&L / net income / margin) by combining the " +
609
685
  "Income tab with expense tabs. Examples: 'am I profitable this " +
610
- "year', 'P&L for Q1', 'net income last quarter', 'what's my margin'. " +
611
- "Returns: { message, data: { revenue, expenses, netIncome, margin, " +
612
- "sampleMeta? } }.",
686
+ "year', 'P&L for Q1', 'net income last quarter', 'what's my " +
687
+ "margin', 'P&L this year vs last' (YoY). Supports period comparison " +
688
+ "— YoY, MoM, QoQ, same-month-prev-year. Margin renders as " +
689
+ "multiplier in loss territory ('expenses 5.4× revenue') so the " +
690
+ "user gets a readable signal instead of '-436.9% margin'. Returns: " +
691
+ "{ message, data: { revenue, expenses, netIncome, margin, " +
692
+ "comparison?, sampleMeta? } }.",
613
693
  inputSchema: {
614
694
  type: "object",
615
695
  properties: {
696
+ clientEmail: CLIENT_EMAIL_SCHEMA,
616
697
  query: {
617
698
  type: "string",
618
699
  description: "Natural language P&L question (e.g., 'P&L for Q1 2025', 'am I profitable')",
619
700
  },
620
- dateRange: {
621
- type: "object",
622
- properties: {
623
- type: { type: "string" },
624
- month: { type: "string" },
625
- year: { type: "integer" },
626
- quarter: { type: "integer" },
627
- value: { type: "string" },
628
- },
629
- },
701
+ dateRange: DATE_RANGE_SCHEMA,
630
702
  },
631
703
  },
632
704
  },
@@ -634,11 +706,15 @@ const TOOLS = [
634
706
  name: "get_per_tag_pnl",
635
707
  description:
636
708
  "Per-tag P&L — revenue, cost, profit, and margin grouped by tag " +
637
- "(per-client, per-property, per-event). Requires both income AND " +
638
- "expense rows to be tagged with matching labels (e.g., 'Smith " +
639
- "Wedding', 'Prop – Brooklyn'). Examples: 'per-tag P&L this year', " +
640
- "'profit by client', 'profit by property', 'profit on the Smith " +
641
- "wedding'. Defaults to year-to-date if no date range given.",
709
+ "(per-client, per-property, per-event, per-realtor-deal). Requires " +
710
+ "both income AND expense rows to be tagged with matching labels. " +
711
+ "Common tag-prefix shortcuts: 'Prop –' (rentals), 'Client –' " +
712
+ "(client billings), 'Wedding –' (events), 'Realtor –' (real estate " +
713
+ "deals). Examples: 'per-tag P&L this year', 'profit by client', " +
714
+ "'profit by property', 'profit on the Smith wedding', 'per-client " +
715
+ "P&L this year vs last' (YoY). Supports YoY / MoM / QoQ comparison " +
716
+ "phrasing. Margin renders as multiplier in loss territory. " +
717
+ "Defaults to year-to-date if no date range given.",
642
718
  inputSchema: {
643
719
  type: "object",
644
720
  properties: {
@@ -651,28 +727,16 @@ const TOOLS = [
651
727
  description:
652
728
  "Optional prefix to limit which tags are bucketed (e.g., 'Prop –' for properties only, 'Client –' for clients only). When omitted, all tags are included.",
653
729
  },
654
- dateRange: {
655
- type: "object",
656
- properties: {
657
- type: { type: "string" },
658
- month: { type: "string" },
659
- year: { type: "integer" },
660
- quarter: { type: "integer" },
661
- value: { type: "string" },
662
- },
663
- },
730
+ dateRange: DATE_RANGE_SCHEMA,
664
731
  },
665
732
  },
666
733
  },
667
734
  {
668
735
  name: "list_income_categories",
669
736
  description:
670
- "List the user's configured income categories (mirrors " +
671
- "list_categories for the Income tab). Use this BEFORE calling " +
672
- "add_income with a category so you pass the user's actual income " +
673
- "category names, not guesses. Returns the canonical INCOME_CATEGORIES " +
674
- "enum (Service Revenue, Product Sales, Rental Income, Interest " +
675
- "Income, Dividend Income, Tax Refund, Other Income, etc.).",
737
+ "List ExpenseBot's fixed income tax categories. Unlike Expense Accounts, " +
738
+ "these are not user-configured. Use this BEFORE calling add_income so " +
739
+ "you pass an exact canonical category instead of guessing.",
676
740
  inputSchema: { type: "object", properties: {} },
677
741
  },
678
742
  {
@@ -706,13 +770,123 @@ const TOOLS = [
706
770
  },
707
771
  },
708
772
  },
773
+ {
774
+ name: "trace_document",
775
+ description:
776
+ "Trace what happened to a specific receipt, invoice, forwarded email, Gmail receipt, or PDF in ExpenseBot processing. " +
777
+ "Use when the user asks where a document went, why it did not show up, whether it was skipped, routed to income, deduped, or removed as a duplicate. " +
778
+ "Returns a read-only timeline from the user's lineage audit trail.",
779
+ inputSchema: {
780
+ type: "object",
781
+ properties: {
782
+ query: {
783
+ type: "string",
784
+ description:
785
+ "Merchant, sender, subject, invoice number, or phrase to search for, e.g. 'Blue Rocket', 'Driversnote', 'Uber receipt'.",
786
+ },
787
+ receiptId: {
788
+ type: "string",
789
+ description: "ExpenseBot receipt/invoice ID if known, e.g. IR-123, RO-abc, RR-456.",
790
+ },
791
+ messageId: {
792
+ type: "string",
793
+ description: "Gmail message ID if known.",
794
+ },
795
+ threadId: {
796
+ type: "string",
797
+ description: "Gmail thread ID if known.",
798
+ },
799
+ outcome: {
800
+ type: "string",
801
+ enum: ["all", "created", "skipped", "suggested", "income_routed", "deduped", "removed_as_duplicate"],
802
+ description: "Optional processing outcome filter.",
803
+ default: "all",
804
+ },
805
+ days: {
806
+ type: "integer",
807
+ minimum: 1,
808
+ maximum: 180,
809
+ default: 30,
810
+ description: "How many days back to search.",
811
+ },
812
+ limit: {
813
+ type: "integer",
814
+ minimum: 1,
815
+ maximum: 250,
816
+ default: 80,
817
+ description: "Maximum lineage events to return.",
818
+ },
819
+ },
820
+ },
821
+ },
822
+ // ── Mileage & Subscriptions (v0.6.1) ─────────────────────────────────
823
+ // Both proxy to the same query_analytics action that powers the chat
824
+ // widget — runtime is auto-routed via classifyMileageIntent /
825
+ // classifySubscriptionIntent. Registered as dedicated tools so AI
826
+ // clients pick them up in completions for "mileage" / "subscriptions"
827
+ // questions instead of the generic get_spending_summary.
828
+ {
829
+ name: "get_mileage_summary",
830
+ description:
831
+ "Mileage analytics — totals, breakdowns by month / client / " +
832
+ "purpose / category, plus deduction framing (cents-per-mile or " +
833
+ "cents-per-km × distance, country-aware IRS / CRA rates). " +
834
+ "Examples: 'mileage this year', 'miles driven for Acme', 'mileage " +
835
+ "by month', 'mileage deduction estimate', 'business miles last " +
836
+ "quarter'. Supports YoY / MoM / QoQ comparison phrasing. Returns: " +
837
+ "{ message, data: { totalDistance, deductionEstimate?, breakdown?, " +
838
+ "comparison?, sampleMeta? } }.",
839
+ inputSchema: {
840
+ type: "object",
841
+ properties: {
842
+ query: {
843
+ type: "string",
844
+ description:
845
+ "Natural language mileage question (e.g., 'mileage this year', 'miles driven for Acme client')",
846
+ },
847
+ groupBy: {
848
+ type: "string",
849
+ enum: ["month", "tag", "purpose", "category"],
850
+ description: "How to group the breakdown",
851
+ },
852
+ dateRange: DATE_RANGE_SCHEMA,
853
+ },
854
+ },
855
+ },
856
+ {
857
+ name: "get_subscription_audit",
858
+ description:
859
+ "Subscription audit — wraps the Subscription Auditor engine to " +
860
+ "find recurring charges, duplicates, price increases, and " +
861
+ "trial-conversion suspects in the user's expenses. Examples: " +
862
+ "'recurring subscriptions', 'duplicate subscriptions', 'price " +
863
+ "increases', 'trial conversions', 'subscriptions over $20/month'. " +
864
+ "Returns: { message, data: { recurring, duplicates, priceIncreases, " +
865
+ "trialConversions, totalMonthlyCost, sampleMeta? } }.",
866
+ inputSchema: {
867
+ type: "object",
868
+ properties: {
869
+ query: {
870
+ type: "string",
871
+ description:
872
+ "Natural language subscription question (e.g., 'find duplicate subscriptions', 'price increases this year')",
873
+ },
874
+ focus: {
875
+ type: "string",
876
+ enum: ["recurring", "duplicates", "price_increases", "trial_conversions", "all"],
877
+ description: "Narrow the audit to a single category (default: all)",
878
+ },
879
+ dateRange: DATE_RANGE_SCHEMA,
880
+ },
881
+ },
882
+ },
709
883
 
710
884
  // ── Read-only mutation helpers + onboarding (v0.7.0) ─────────────────
711
885
  {
712
886
  name: "get_expense_by_id",
713
887
  description:
714
888
  "Fetch a single expense row by its sheet row number or by its " +
715
- "ExpenseBot expenseId (the value in column J). Returns the row's " +
889
+ "ExpenseBot expenseId (the exact Receipt ID in Column Q). Returns the row's " +
716
890
  "headers + values + a labeled {header → value} map so you can refer " +
717
891
  "to a specific expense the user mentioned. Read-only.",
718
892
  inputSchema: {
@@ -725,7 +899,7 @@ const TOOLS = [
725
899
  },
726
900
  expenseId: {
727
901
  type: "string",
728
- description: "ExpenseBot expense ID (column J)",
902
+ description: "Exact full ExpenseBot Receipt ID from Column Q",
729
903
  },
730
904
  },
731
905
  },
@@ -794,6 +968,266 @@ const TOOLS = [
794
968
  },
795
969
  },
796
970
  },
971
+
972
+ // ── Pulse CFO Slice 4 — What-If ───────────────────────────────────────
973
+ // Deterministic scenario math (Safe Draw recompute + client income
974
+ // impact + tax set-aside). No model call: numbers always come from the
975
+ // pure functions, never from the AI. All three carry
976
+ // "estimates — confirm with your tax professional" in their response.
977
+ {
978
+ name: "whatif_afford",
979
+ description:
980
+ "Can I afford $X/month? Recomputes the user's Safe Monthly Draw " +
981
+ "(how much they can safely pay themselves) with an added recurring " +
982
+ "monthly cost, and returns a yes/tight/no verdict plus the before/" +
983
+ "after numbers. Use for questions like 'can I afford a $500/mo " +
984
+ "hire' or 'what if I add a $200/mo software subscription'. Requires " +
985
+ "at least 3 months of income history — otherwise returns " +
986
+ "insufficient_data rather than a guess.",
987
+ inputSchema: {
988
+ type: "object",
989
+ properties: {
990
+ deltaMonthly: {
991
+ type: "number",
992
+ minimum: 0,
993
+ description: "The new recurring monthly cost being considered, in the user's home currency",
994
+ },
995
+ },
996
+ required: ["deltaMonthly"],
997
+ },
998
+ },
999
+ {
1000
+ name: "whatif_client",
1001
+ description:
1002
+ "What if a client pays late or leaves? mode='late30' shifts that " +
1003
+ "client's OPEN invoice amounts out of the near-term expectation " +
1004
+ "(they still owe it, it's just not landing this month). " +
1005
+ "mode='gone' removes that client's trailing monthly income " +
1006
+ "contribution and recomputes Safe Draw against the reduced " +
1007
+ "baseline. Use for questions like 'what if Acme Corp pays 30 days " +
1008
+ "late' or 'what happens if I lose my biggest client'. Client " +
1009
+ "identity is matched against the Income tab's tag/source/" +
1010
+ "description fields — best effort, not a guaranteed match.",
1011
+ inputSchema: {
1012
+ type: "object",
1013
+ properties: {
1014
+ clientName: {
1015
+ type: "string",
1016
+ description: "The client's name as it appears on invoices or income rows",
1017
+ },
1018
+ mode: {
1019
+ type: "string",
1020
+ enum: ["late30", "gone"],
1021
+ description: "'late30' = shift open invoices 30 days late; 'gone' = client stops paying entirely",
1022
+ },
1023
+ },
1024
+ required: ["clientName", "mode"],
1025
+ },
1026
+ },
1027
+ {
1028
+ name: "whatif_tax_setaside",
1029
+ description:
1030
+ "What should I set aside for taxes? Surfaces the same monthly tax " +
1031
+ "set-aside estimate already computed for Safe Monthly Draw — wiring, " +
1032
+ "not new math. Flat-rate estimate (default 30%) against trailing " +
1033
+ "income minus recurring + variable spend. Use for 'how much should " +
1034
+ "I set aside for taxes this month'.",
1035
+ inputSchema: { type: "object", properties: {} },
1036
+ },
1037
+ {
1038
+ name: "scan_gmail_years",
1039
+ description:
1040
+ "Scan one or more COMPLETED PRIOR years of the user's Gmail for " +
1041
+ "receipts (e.g. years:[2023] or years:[2020,2021,2022]). Long-running " +
1042
+ "background job: the first eligible year starts immediately and the " +
1043
+ "rest queue, running one at a time (each full year typically takes a " +
1044
+ "couple of hours; the user can close the app). ALWAYS call first " +
1045
+ "WITHOUT confirmStart to preview which years are eligible, then ask " +
1046
+ "the user to confirm, then call again with confirmStart:true. For " +
1047
+ "receipts from the last ~60 days use scan_gmail instead. To check how " +
1048
+ "a scan is going, use get_scan_status. The current in-progress year " +
1049
+ "cannot be year-scanned.",
1050
+ inputSchema: {
1051
+ type: "object",
1052
+ properties: {
1053
+ years: {
1054
+ type: "array",
1055
+ items: { type: "number" },
1056
+ description: "Completed prior years to scan, e.g. [2020, 2021]. Max 10.",
1057
+ },
1058
+ accountEmail: {
1059
+ type: "string",
1060
+ description:
1061
+ "Optional: which connected Gmail inbox to scan (multi-inbox users). Defaults to the primary.",
1062
+ },
1063
+ confirmStart: {
1064
+ type: "boolean",
1065
+ description:
1066
+ "Omit or false = preview only (no scan starts). Must be exactly true to start scanning.",
1067
+ },
1068
+ },
1069
+ required: ["years"],
1070
+ },
1071
+ },
1072
+ {
1073
+ name: "get_scan_status",
1074
+ description:
1075
+ "Check the status of the user's Gmail receipt scans: whether a scan " +
1076
+ "is running right now, which years are queued for scanning, and " +
1077
+ "recent scan history (per inbox, with date range and counts). Call " +
1078
+ "this when the user asks how their scan is going or whether a year " +
1079
+ "has finished. Read-only.",
1080
+ inputSchema: { type: "object", properties: {} },
1081
+ },
1082
+ {
1083
+ name: "list_client_invoices",
1084
+ description:
1085
+ "List the user's issued client invoices (accounts receivable) — open " +
1086
+ "or paid, with totals and due dates. Use when the user asks what " +
1087
+ "clients owe them, which invoices are outstanding or overdue, or " +
1088
+ "before running whatif_client on a client. Read-only.",
1089
+ inputSchema: {
1090
+ type: "object",
1091
+ properties: {
1092
+ clientEmail: CLIENT_EMAIL_SCHEMA,
1093
+ status: {
1094
+ type: "string",
1095
+ enum: ["open", "paid", "all"],
1096
+ description: "Filter by invoice status (default open).",
1097
+ },
1098
+ clientName: {
1099
+ type: "string",
1100
+ description: "Optional: exact client name (case-insensitive).",
1101
+ },
1102
+ limit: {
1103
+ type: "number",
1104
+ description: "Max invoices to return (default 25, max 100).",
1105
+ },
1106
+ },
1107
+ },
1108
+ },
1109
+ {
1110
+ name: "get_expense_splits",
1111
+ description:
1112
+ "Show how an expense is split or allocated across categories, clients, " +
1113
+ "properties, or business and personal portions. Returns one parent " +
1114
+ "payment with nested allocation lines; it never treats split lines as " +
1115
+ "separate expenses. Read-only — edit splits in ExpenseBot's Review workspace.",
1116
+ inputSchema: {
1117
+ type: "object",
1118
+ properties: {
1119
+ clientEmail: CLIENT_EMAIL_SCHEMA,
1120
+ receiptId: {
1121
+ type: "string",
1122
+ description: "Optional Receipt ID for one expense.",
1123
+ },
1124
+ dateRange: {
1125
+ type: "object",
1126
+ properties: {
1127
+ startDate: {
1128
+ type: "string",
1129
+ description: "Inclusive start date in YYYY-MM-DD format.",
1130
+ },
1131
+ endDate: {
1132
+ type: "string",
1133
+ description: "Inclusive end date in YYYY-MM-DD format.",
1134
+ },
1135
+ },
1136
+ },
1137
+ onlySplit: {
1138
+ type: "boolean",
1139
+ description:
1140
+ "Return only expenses with active splits (default true). Set false to inspect an unsplit Receipt ID.",
1141
+ },
1142
+ limit: {
1143
+ type: "number",
1144
+ description: "Max parent expenses to return (default 25, max 100).",
1145
+ },
1146
+ },
1147
+ },
1148
+ },
1149
+ {
1150
+ name: "get_monthly_books_review",
1151
+ description:
1152
+ "Get the user's Monthly Books Review: recorded income, spending, net, " +
1153
+ "top categories and merchants, plus deterministic cash-pulse alerts for " +
1154
+ "one calendar month. Defaults to the last completed month. Advisory " +
1155
+ "fields are estimates and retain ExpenseBot's tax-professional disclaimer.",
1156
+ inputSchema: {
1157
+ type: "object",
1158
+ properties: {
1159
+ clientEmail: CLIENT_EMAIL_SCHEMA,
1160
+ period: {
1161
+ type: "string",
1162
+ pattern: "^\\d{4}-\\d{2}$",
1163
+ description:
1164
+ "Calendar month in YYYY-MM format. Defaults to the last completed month.",
1165
+ },
1166
+ },
1167
+ },
1168
+ },
1169
+ {
1170
+ name: "get_credits_refunds",
1171
+ description:
1172
+ "List recently reviewed card refunds, rewards, and statement credits that " +
1173
+ "are already recorded as negative expenses or matched to an existing offset. " +
1174
+ "Read-only: it never scans cards, changes review decisions, or adds rows.",
1175
+ inputSchema: {
1176
+ type: "object",
1177
+ properties: {
1178
+ clientEmail: CLIENT_EMAIL_SCHEMA,
1179
+ dateRange: {
1180
+ type: "object",
1181
+ properties: {
1182
+ startDate: {
1183
+ type: "string",
1184
+ description: "Inclusive start date in YYYY-MM-DD format.",
1185
+ },
1186
+ endDate: {
1187
+ type: "string",
1188
+ description: "Inclusive end date in YYYY-MM-DD format.",
1189
+ },
1190
+ },
1191
+ },
1192
+ limit: {
1193
+ type: "number",
1194
+ description: "Maximum results to return (default 25, max 100).",
1195
+ },
1196
+ },
1197
+ },
1198
+ },
1199
+ {
1200
+ name: "update_expense",
1201
+ description:
1202
+ "Update a single existing expense row's category, tag, merchant, or " +
1203
+ "business purpose (e.g. 'recategorize expense X to Meals' or 'tag it " +
1204
+ "Client – Acme'). Identify it only by the exact expenseId returned by " +
1205
+ "search_expenses (the full Receipt ID from Column Q). Never use a date, " +
1206
+ "displayed number, or sheet row number as expenseId. " +
1207
+ "ALWAYS call first WITHOUT confirm to preview the current→proposed " +
1208
+ "change, then ask the user to confirm, then call again with " +
1209
+ "confirm:true. Only category/tag/merchant/businessPurpose are " +
1210
+ "editable — amounts, dates, and notes are not editable via the " +
1211
+ "assistant. Does not create or delete rows.",
1212
+ inputSchema: {
1213
+ type: "object",
1214
+ properties: {
1215
+ expenseId: { type: "string", description: "Exact full Receipt ID from Column Q, returned as expenseId by search_expenses." },
1216
+ fields: {
1217
+ type: "object",
1218
+ description: "The fields to change. Only these keys are honored.",
1219
+ properties: {
1220
+ category: { type: "string" },
1221
+ tag: { type: "string" },
1222
+ merchant: { type: "string" },
1223
+ businessPurpose: { type: "string" },
1224
+ },
1225
+ },
1226
+ confirm: { type: "boolean", description: "Omit or false = preview only (no write). Must be exactly true to apply the change." },
1227
+ },
1228
+ required: ["expenseId", "fields"],
1229
+ },
1230
+ },
797
1231
  ];
798
1232
 
799
1233
  // Tools available without authentication (onboarding mode)
@@ -839,7 +1273,7 @@ async function handleTool(name, args) {
839
1273
  text:
840
1274
  "**ExpenseBot — 60-day free trial, no credit card required**\n\n" +
841
1275
  `Sign up: https://www.expensebot.ai?utm_source=${args?.utmSource || "mcp"}&utm_medium=ai-assistant\n\n` +
842
- "After signing up, generate an AI Assistant Token from Settings to unlock all 31 tools " +
1276
+ `After signing up, generate an AI Assistant Token from Settings to unlock all ${TOOLS.length} tools ` +
843
1277
  "(submit receipts, scan Gmail, search expenses, run income / P&L / per-tag P&L analytics, create reports).\n\n" +
844
1278
  "Free for accountants forever. $10/month for everyone else.",
845
1279
  },
@@ -851,13 +1285,15 @@ async function handleTool(name, args) {
851
1285
  await client.execute("query_expenses", args)
852
1286
  );
853
1287
 
854
- case "get_spending_summary":
1288
+ case "get_spending_summary": {
1289
+ const { clientEmail: _clientEmail, ...businessArgs } = args;
855
1290
  return formatResult(
856
1291
  await client.execute("query_analytics", {
857
1292
  ...args,
858
- message: args.query || JSON.stringify(args),
1293
+ message: args.query || JSON.stringify(businessArgs),
859
1294
  })
860
1295
  );
1296
+ }
861
1297
 
862
1298
  case "get_deep_analytics":
863
1299
  return formatResult(
@@ -1027,6 +1463,48 @@ async function handleTool(name, args) {
1027
1463
  })
1028
1464
  );
1029
1465
 
1466
+ case "trace_document":
1467
+ return formatResult(
1468
+ await client.execute("trace_document", {
1469
+ query: args.query,
1470
+ receiptId: args.receiptId,
1471
+ messageId: args.messageId,
1472
+ threadId: args.threadId,
1473
+ outcome: args.outcome || "all",
1474
+ days: args.days || 30,
1475
+ limit: args.limit || 80,
1476
+ })
1477
+ );
1478
+
1479
+ // ── Mileage & Subscriptions (v0.6.1) ──
1480
+ // Both proxy to query_analytics; classifyMileageIntent /
1481
+ // classifySubscriptionIntent route to the correct helper server-side.
1482
+ case "get_mileage_summary": {
1483
+ let q = args.query || "mileage summary";
1484
+ if (args.groupBy) q = `${q} grouped by ${args.groupBy}`;
1485
+ return formatResult(
1486
+ await client.execute("query_analytics", {
1487
+ ...args,
1488
+ message: q,
1489
+ intent: "mileage",
1490
+ })
1491
+ );
1492
+ }
1493
+
1494
+ case "get_subscription_audit": {
1495
+ let q = args.query || "subscription audit";
1496
+ if (args.focus && args.focus !== "all") {
1497
+ q = `${q} (focus: ${args.focus})`;
1498
+ }
1499
+ return formatResult(
1500
+ await client.execute("query_analytics", {
1501
+ ...args,
1502
+ message: q,
1503
+ intent: "subscriptions",
1504
+ })
1505
+ );
1506
+ }
1507
+
1030
1508
  // ── Read-only mutation helpers (v0.7.0) ──
1031
1509
  case "get_expense_by_id":
1032
1510
  return formatResult(
@@ -1108,6 +1586,79 @@ async function handleTool(name, args) {
1108
1586
  };
1109
1587
  }
1110
1588
 
1589
+ // ── Pulse CFO Slice 4 — What-If ──
1590
+ case "whatif_afford":
1591
+ return formatResult(
1592
+ await client.execute("whatif_afford", { deltaMonthly: args.deltaMonthly })
1593
+ );
1594
+
1595
+ case "whatif_client":
1596
+ return formatResult(
1597
+ await client.execute("whatif_client", { clientName: args.clientName, mode: args.mode })
1598
+ );
1599
+
1600
+ case "whatif_tax_setaside":
1601
+ return formatResult(await client.execute("whatif_tax_setaside", {}));
1602
+
1603
+ case "scan_gmail_years":
1604
+ return formatResult(
1605
+ await client.execute("scan_gmail_years", {
1606
+ years: args.years,
1607
+ accountEmail: args.accountEmail,
1608
+ confirmStart: args.confirmStart,
1609
+ })
1610
+ );
1611
+
1612
+ case "get_scan_status":
1613
+ return formatResult(await client.execute("get_scan_status", {}));
1614
+
1615
+ case "list_client_invoices":
1616
+ return formatResult(
1617
+ await client.execute("list_client_invoices", {
1618
+ clientEmail: args.clientEmail,
1619
+ status: args.status,
1620
+ clientName: args.clientName,
1621
+ limit: args.limit,
1622
+ })
1623
+ );
1624
+
1625
+ case "get_expense_splits":
1626
+ return formatResult(
1627
+ await client.execute("get_expense_splits", {
1628
+ clientEmail: args.clientEmail,
1629
+ receiptId: args.receiptId,
1630
+ dateRange: args.dateRange,
1631
+ onlySplit: args.onlySplit,
1632
+ limit: args.limit,
1633
+ })
1634
+ );
1635
+
1636
+ case "get_monthly_books_review":
1637
+ return formatResult(
1638
+ await client.execute("get_monthly_books_review", {
1639
+ clientEmail: args.clientEmail,
1640
+ period: args.period,
1641
+ })
1642
+ );
1643
+
1644
+ case "get_credits_refunds":
1645
+ return formatResult(
1646
+ await client.execute("get_credits_refunds", {
1647
+ clientEmail: args.clientEmail,
1648
+ dateRange: args.dateRange,
1649
+ limit: args.limit,
1650
+ })
1651
+ );
1652
+
1653
+ case "update_expense":
1654
+ return formatResult(
1655
+ await client.execute("update_expense", {
1656
+ expenseId: args.expenseId,
1657
+ fields: args.fields,
1658
+ confirm: args.confirm,
1659
+ })
1660
+ );
1661
+
1111
1662
  default:
1112
1663
  return {
1113
1664
  content: [{ type: "text", text: `Unknown tool: ${name}` }],
@@ -1174,7 +1725,7 @@ function formatResult(result) {
1174
1725
 
1175
1726
  async function main() {
1176
1727
  const server = new Server(
1177
- { name: "expensebot-auth", version: "0.6.0" },
1728
+ { name: "expensebot-auth", version: "0.6.2" },
1178
1729
  { capabilities: { tools: {} } }
1179
1730
  );
1180
1731
 
package/src/test.js CHANGED
@@ -21,7 +21,7 @@ import path from "node:path";
21
21
  const __dirname = path.dirname(fileURLToPath(import.meta.url));
22
22
  const SERVER_PATH = path.join(__dirname, "index.js");
23
23
 
24
- const EXPECTED_TOOL_COUNT = 31;
24
+ const EXPECTED_TOOL_COUNT = 44; // 37 + v1.0 Gmail year-scan/edit + Phase 4B reads
25
25
  const REQUIRED_TOOLS = [
26
26
  // v0.5.x
27
27
  "search_expenses",
@@ -34,12 +34,25 @@ const REQUIRED_TOOLS = [
34
34
  "get_per_tag_pnl",
35
35
  "list_income_categories",
36
36
  "get_recent_activity",
37
+ "trace_document",
38
+ // v0.6.1
39
+ "get_mileage_summary",
40
+ "get_subscription_audit",
37
41
  // v0.7.0
38
42
  "get_expense_by_id",
39
43
  "export_report",
40
44
  "get_pricing",
41
45
  "check_feature",
42
46
  "start_trial_link",
47
+ // v1.0 — Gmail year-scan/edit
48
+ "scan_gmail_years",
49
+ "get_scan_status",
50
+ "update_expense",
51
+ // Phase 4B — read-only surfaces for shipped product data
52
+ "list_client_invoices",
53
+ "get_expense_splits",
54
+ "get_monthly_books_review",
55
+ "get_credits_refunds",
43
56
  ];
44
57
 
45
58
  const REQUESTS = [
@@ -181,6 +194,18 @@ function check(label, ok, details = "") {
181
194
  noDesc.length === 0,
182
195
  noDesc.length ? `missing on: ${noDesc.map((t) => t.name).join(", ")}` : ""
183
196
  );
197
+ const updateExpense = tools.find((tool) => tool.name === "update_expense");
198
+ check(
199
+ "update_expense requires exact Column-Q expenseId and exposes no rowNumber",
200
+ updateExpense?.inputSchema?.required?.includes("expenseId") &&
201
+ !Object.prototype.hasOwnProperty.call(
202
+ updateExpense?.inputSchema?.properties || {},
203
+ "rowNumber"
204
+ ) &&
205
+ /Column Q|search_expenses/.test(
206
+ updateExpense?.inputSchema?.properties?.expenseId?.description || ""
207
+ )
208
+ );
184
209
  }
185
210
 
186
211
  // 2. get_pricing (id=3) — should succeed in onboarding mode
@@ -212,8 +237,9 @@ function check(label, ok, details = "") {
212
237
  const signupResp = byId.get(5);
213
238
  const signupText = signupResp?.result?.content?.[0]?.text || "";
214
239
  check(
215
- "get_signup_link succeeds + advertises 31 tools",
216
- !signupResp?.result?.isError && signupText.includes("31 tools")
240
+ `get_signup_link succeeds + advertises ${EXPECTED_TOOL_COUNT} tools`,
241
+ !signupResp?.result?.isError &&
242
+ signupText.includes(`${EXPECTED_TOOL_COUNT} tools`)
217
243
  );
218
244
 
219
245
  // 5. Token-gated tool (id=6) returns isError with helpful message