@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 +43 -5
- package/package.json +1 -1
- package/scripts/sync-check.js +12 -7
- package/src/client.js +1 -1
- package/src/index.js +539 -116
- package/src/test.js +26 -3
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
|
-
**
|
|
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.
|
|
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": {
|
package/scripts/sync-check.js
CHANGED
|
@@ -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
|
-
|
|
70
|
-
);
|
|
71
|
-
const advertisedCount =
|
|
72
|
-
?
|
|
73
|
-
:
|
|
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(
|
|
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.
|
|
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: {
|
|
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
|
|
415
|
-
|
|
416
|
-
"in the UI.
|
|
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
|
|
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: "
|
|
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
|
|
690
|
-
"
|
|
691
|
-
"
|
|
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
|
|
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
|
|
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
|
-
|
|
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(
|
|
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.
|
|
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 =
|
|
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
|
-
|
|
219
|
-
!signupResp?.result?.isError &&
|
|
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
|