@expensebot/mcp-server-auth 0.6.1 → 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,15 +2,26 @@
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
- **33 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
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`
10
- - **Gmail** — `scan_gmail`, `process_gmail_receipts`
11
- - **Reports** — `create_report`, `list_reports`, `get_report_details`, `share_report`, `export_report`
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`
12
13
  - **Compliance & tax** — `check_compliance`, `fix_compliance`, `check_tax_deductibility`
13
- - **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.
14
25
 
15
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".
16
27
 
@@ -112,6 +123,33 @@ Exposes the ExpenseBot knowledge base, FAQ, and feature docs as MCP resources. U
112
123
  - Issues: email `support@expensebot.ai`
113
124
  - Roadmap (remote HTTPS MCP for ChatGPT + Claude.ai web): <https://www.expensebot.ai/mcp>
114
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
+
115
153
  ## License
116
154
 
117
155
  MIT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@expensebot/mcp-server-auth",
3
- "version": "0.6.1",
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.1",
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" },
@@ -109,22 +198,14 @@ const TOOLS = [
109
198
  inputSchema: {
110
199
  type: "object",
111
200
  properties: {
201
+ clientEmail: CLIENT_EMAIL_SCHEMA,
112
202
  query: {
113
203
  type: "string",
114
204
  description:
115
205
  "Natural language question (e.g., 'how much did I spend in March', 'rental income by property')",
116
206
  },
117
207
  categories: { type: "array", items: { type: "string" } },
118
- dateRange: {
119
- type: "object",
120
- properties: {
121
- type: { type: "string" },
122
- month: { type: "string" },
123
- year: { type: "integer" },
124
- quarter: { type: "integer" },
125
- value: { type: "string" },
126
- },
127
- },
208
+ dateRange: DATE_RANGE_SCHEMA,
128
209
  groupBy: { type: "string", enum: ["category", "merchant", "month", "tag", "source", "paymentMethod"] },
129
210
  metric: { type: "string", enum: ["total", "count", "average"] },
130
211
  },
@@ -146,15 +227,7 @@ const TOOLS = [
146
227
  type: "string",
147
228
  description: "The analytics question to answer",
148
229
  },
149
- dateRange: {
150
- type: "object",
151
- properties: {
152
- type: { type: "string" },
153
- month: { type: "string" },
154
- year: { type: "integer" },
155
- quarter: { type: "integer" },
156
- },
157
- },
230
+ dateRange: DATE_RANGE_SCHEMA,
158
231
  },
159
232
  required: ["query"],
160
233
  },
@@ -167,18 +240,7 @@ const TOOLS = [
167
240
  inputSchema: {
168
241
  type: "object",
169
242
  properties: {
170
- dateRange: {
171
- type: "object",
172
- description: "Time period for the report (required)",
173
- properties: {
174
- type: { type: "string", enum: ["month", "quarter", "year", "specific"] },
175
- month: { type: "string" },
176
- year: { type: "integer" },
177
- quarter: { type: "integer" },
178
- start: { type: "string", format: "date" },
179
- end: { type: "string", format: "date" },
180
- },
181
- },
243
+ dateRange: DATE_RANGE_SCHEMA,
182
244
  title: { type: "string", description: "Custom report title" },
183
245
  categories: { type: "array", items: { type: "string" } },
184
246
  tags: { type: "array", items: { type: "string" } },
@@ -199,6 +261,7 @@ const TOOLS = [
199
261
  inputSchema: {
200
262
  type: "object",
201
263
  properties: {
264
+ clientEmail: CLIENT_EMAIL_SCHEMA,
202
265
  page: { type: "integer", default: 1 },
203
266
  limit: { type: "integer", default: 20 },
204
267
  filter: { type: "string", enum: ["All", "Draft", "Submitted", "Shared"], default: "All" },
@@ -213,6 +276,7 @@ const TOOLS = [
213
276
  inputSchema: {
214
277
  type: "object",
215
278
  properties: {
279
+ clientEmail: CLIENT_EMAIL_SCHEMA,
216
280
  reportId: { type: "string", description: "The report/spreadsheet ID" },
217
281
  },
218
282
  required: ["reportId"],
@@ -343,7 +407,9 @@ const TOOLS = [
343
407
  name: "add_cash_expense",
344
408
  description:
345
409
  "Add an expense without a receipt (cash purchase, tip, etc.). " +
346
- "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.",
347
413
  inputSchema: {
348
414
  type: "object",
349
415
  properties: {
@@ -354,7 +420,11 @@ const TOOLS = [
354
420
  description: "Expense date (YYYY-MM-DD)",
355
421
  format: "date",
356
422
  },
357
- 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
+ },
358
428
  subtotal: { type: "number", description: "Subtotal before tax" },
359
429
  tax: { type: "number", description: "Tax amount" },
360
430
  tip: { type: "number", description: "Tip amount" },
@@ -411,9 +481,11 @@ const TOOLS = [
411
481
  name: "scan_gmail",
412
482
  description:
413
483
  "Trigger a background Gmail scan to discover and process receipt " +
414
- "emails. Runs asynchronously — returns immediately, user gets an " +
415
- 'email summary when done. Like clicking "Find Receipts in Gmail" ' +
416
- "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.",
417
489
  inputSchema: {
418
490
  type: "object",
419
491
  properties: {
@@ -512,7 +584,9 @@ const TOOLS = [
512
584
  description:
513
585
  "Log an income entry manually (cash, check, Stripe payout, etc.). " +
514
586
  "Writes to the Income tab of the user's expense spreadsheet. Useful " +
515
- "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.",
516
590
  inputSchema: {
517
591
  type: "object",
518
592
  properties: {
@@ -523,7 +597,7 @@ const TOOLS = [
523
597
  },
524
598
  paymentMethod: {
525
599
  type: "string",
526
- 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.",
527
601
  },
528
602
  date: {
529
603
  type: "string",
@@ -532,7 +606,7 @@ const TOOLS = [
532
606
  },
533
607
  currency: { type: "string", description: "Currency code (default: home currency)" },
534
608
  description: { type: "string", description: "What the income was for" },
535
- category: { type: "string", description: "Income category (optional)" },
609
+ category: { type: "string", description: "A category returned by list_income_categories (optional; defaults to Service income)" },
536
610
  reference: { type: "string", description: "Invoice or transaction reference" },
537
611
  fees: { type: "number", description: "Processor/transfer fees deducted" },
538
612
  taxCollected: { type: "number", description: "Sales tax/GST/HST collected" },
@@ -595,16 +669,7 @@ const TOOLS = [
595
669
  enum: ["source", "category", "month", "paymentMethod", "tag"],
596
670
  description: "How to group the breakdown",
597
671
  },
598
- dateRange: {
599
- type: "object",
600
- properties: {
601
- type: { type: "string" },
602
- month: { type: "string" },
603
- year: { type: "integer" },
604
- quarter: { type: "integer" },
605
- value: { type: "string", description: "Relative date like 'YTD', 'last quarter'" },
606
- },
607
- },
672
+ dateRange: DATE_RANGE_SCHEMA,
608
673
  incomeTagPrefix: {
609
674
  type: "string",
610
675
  description:
@@ -628,20 +693,12 @@ const TOOLS = [
628
693
  inputSchema: {
629
694
  type: "object",
630
695
  properties: {
696
+ clientEmail: CLIENT_EMAIL_SCHEMA,
631
697
  query: {
632
698
  type: "string",
633
699
  description: "Natural language P&L question (e.g., 'P&L for Q1 2025', 'am I profitable')",
634
700
  },
635
- dateRange: {
636
- type: "object",
637
- properties: {
638
- type: { type: "string" },
639
- month: { type: "string" },
640
- year: { type: "integer" },
641
- quarter: { type: "integer" },
642
- value: { type: "string" },
643
- },
644
- },
701
+ dateRange: DATE_RANGE_SCHEMA,
645
702
  },
646
703
  },
647
704
  },
@@ -670,28 +727,16 @@ const TOOLS = [
670
727
  description:
671
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.",
672
729
  },
673
- dateRange: {
674
- type: "object",
675
- properties: {
676
- type: { type: "string" },
677
- month: { type: "string" },
678
- year: { type: "integer" },
679
- quarter: { type: "integer" },
680
- value: { type: "string" },
681
- },
682
- },
730
+ dateRange: DATE_RANGE_SCHEMA,
683
731
  },
684
732
  },
685
733
  },
686
734
  {
687
735
  name: "list_income_categories",
688
736
  description:
689
- "List the user's configured income categories (mirrors " +
690
- "list_categories for the Income tab). Use this BEFORE calling " +
691
- "add_income with a category so you pass the user's actual income " +
692
- "category names, not guesses. Returns the canonical INCOME_CATEGORIES " +
693
- "enum (Service Revenue, Product Sales, Rental Income, Interest " +
694
- "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.",
695
740
  inputSchema: { type: "object", properties: {} },
696
741
  },
697
742
  {
@@ -725,7 +770,55 @@ const TOOLS = [
725
770
  },
726
771
  },
727
772
  },
728
-
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
+ },
729
822
  // ── Mileage & Subscriptions (v0.6.1) ─────────────────────────────────
730
823
  // Both proxy to the same query_analytics action that powers the chat
731
824
  // widget — runtime is auto-routed via classifyMileageIntent /
@@ -756,16 +849,7 @@ const TOOLS = [
756
849
  enum: ["month", "tag", "purpose", "category"],
757
850
  description: "How to group the breakdown",
758
851
  },
759
- dateRange: {
760
- type: "object",
761
- properties: {
762
- type: { type: "string" },
763
- month: { type: "string" },
764
- year: { type: "integer" },
765
- quarter: { type: "integer" },
766
- value: { type: "string" },
767
- },
768
- },
852
+ dateRange: DATE_RANGE_SCHEMA,
769
853
  },
770
854
  },
771
855
  },
@@ -792,16 +876,7 @@ const TOOLS = [
792
876
  enum: ["recurring", "duplicates", "price_increases", "trial_conversions", "all"],
793
877
  description: "Narrow the audit to a single category (default: all)",
794
878
  },
795
- dateRange: {
796
- type: "object",
797
- properties: {
798
- type: { type: "string" },
799
- month: { type: "string" },
800
- year: { type: "integer" },
801
- quarter: { type: "integer" },
802
- value: { type: "string" },
803
- },
804
- },
879
+ dateRange: DATE_RANGE_SCHEMA,
805
880
  },
806
881
  },
807
882
  },
@@ -811,7 +886,7 @@ const TOOLS = [
811
886
  name: "get_expense_by_id",
812
887
  description:
813
888
  "Fetch a single expense row by its sheet row number or by its " +
814
- "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 " +
815
890
  "headers + values + a labeled {header → value} map so you can refer " +
816
891
  "to a specific expense the user mentioned. Read-only.",
817
892
  inputSchema: {
@@ -824,7 +899,7 @@ const TOOLS = [
824
899
  },
825
900
  expenseId: {
826
901
  type: "string",
827
- description: "ExpenseBot expense ID (column J)",
902
+ description: "Exact full ExpenseBot Receipt ID from Column Q",
828
903
  },
829
904
  },
830
905
  },
@@ -893,6 +968,266 @@ const TOOLS = [
893
968
  },
894
969
  },
895
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
+ },
896
1231
  ];
897
1232
 
898
1233
  // Tools available without authentication (onboarding mode)
@@ -938,7 +1273,7 @@ async function handleTool(name, args) {
938
1273
  text:
939
1274
  "**ExpenseBot — 60-day free trial, no credit card required**\n\n" +
940
1275
  `Sign up: https://www.expensebot.ai?utm_source=${args?.utmSource || "mcp"}&utm_medium=ai-assistant\n\n` +
941
- "After signing up, generate an AI Assistant Token from Settings to unlock all 33 tools " +
1276
+ `After signing up, generate an AI Assistant Token from Settings to unlock all ${TOOLS.length} tools ` +
942
1277
  "(submit receipts, scan Gmail, search expenses, run income / P&L / per-tag P&L analytics, create reports).\n\n" +
943
1278
  "Free for accountants forever. $10/month for everyone else.",
944
1279
  },
@@ -950,13 +1285,15 @@ async function handleTool(name, args) {
950
1285
  await client.execute("query_expenses", args)
951
1286
  );
952
1287
 
953
- case "get_spending_summary":
1288
+ case "get_spending_summary": {
1289
+ const { clientEmail: _clientEmail, ...businessArgs } = args;
954
1290
  return formatResult(
955
1291
  await client.execute("query_analytics", {
956
1292
  ...args,
957
- message: args.query || JSON.stringify(args),
1293
+ message: args.query || JSON.stringify(businessArgs),
958
1294
  })
959
1295
  );
1296
+ }
960
1297
 
961
1298
  case "get_deep_analytics":
962
1299
  return formatResult(
@@ -1126,6 +1463,19 @@ async function handleTool(name, args) {
1126
1463
  })
1127
1464
  );
1128
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
+
1129
1479
  // ── Mileage & Subscriptions (v0.6.1) ──
1130
1480
  // Both proxy to query_analytics; classifyMileageIntent /
1131
1481
  // classifySubscriptionIntent route to the correct helper server-side.
@@ -1236,6 +1586,79 @@ async function handleTool(name, args) {
1236
1586
  };
1237
1587
  }
1238
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
+
1239
1662
  default:
1240
1663
  return {
1241
1664
  content: [{ type: "text", text: `Unknown tool: ${name}` }],
@@ -1302,7 +1725,7 @@ function formatResult(result) {
1302
1725
 
1303
1726
  async function main() {
1304
1727
  const server = new Server(
1305
- { name: "expensebot-auth", version: "0.6.1" },
1728
+ { name: "expensebot-auth", version: "0.6.2" },
1306
1729
  { capabilities: { tools: {} } }
1307
1730
  );
1308
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 = 33;
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,6 +34,7 @@ const REQUIRED_TOOLS = [
34
34
  "get_per_tag_pnl",
35
35
  "list_income_categories",
36
36
  "get_recent_activity",
37
+ "trace_document",
37
38
  // v0.6.1
38
39
  "get_mileage_summary",
39
40
  "get_subscription_audit",
@@ -43,6 +44,15 @@ const REQUIRED_TOOLS = [
43
44
  "get_pricing",
44
45
  "check_feature",
45
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",
46
56
  ];
47
57
 
48
58
  const REQUESTS = [
@@ -184,6 +194,18 @@ function check(label, ok, details = "") {
184
194
  noDesc.length === 0,
185
195
  noDesc.length ? `missing on: ${noDesc.map((t) => t.name).join(", ")}` : ""
186
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
+ );
187
209
  }
188
210
 
189
211
  // 2. get_pricing (id=3) — should succeed in onboarding mode
@@ -215,8 +237,9 @@ function check(label, ok, details = "") {
215
237
  const signupResp = byId.get(5);
216
238
  const signupText = signupResp?.result?.content?.[0]?.text || "";
217
239
  check(
218
- "get_signup_link succeeds + advertises 33 tools",
219
- !signupResp?.result?.isError && signupText.includes("33 tools")
240
+ `get_signup_link succeeds + advertises ${EXPECTED_TOOL_COUNT} tools`,
241
+ !signupResp?.result?.isError &&
242
+ signupText.includes(`${EXPECTED_TOOL_COUNT} tools`)
220
243
  );
221
244
 
222
245
  // 5. Token-gated tool (id=6) returns isError with helpful message