@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 +46 -5
- package/package.json +1 -1
- package/scripts/sync-check.js +12 -7
- package/src/client.js +1 -1
- package/src/index.js +666 -115
- package/src/test.js +29 -3
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
|
-
**
|
|
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
|
-
- **
|
|
9
|
-
- **
|
|
10
|
-
- **
|
|
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.
|
|
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" },
|
|
@@ -94,31 +183,29 @@ const TOOLS = [
|
|
|
94
183
|
{
|
|
95
184
|
name: "get_spending_summary",
|
|
96
185
|
description:
|
|
97
|
-
"
|
|
98
|
-
"
|
|
99
|
-
"
|
|
100
|
-
"
|
|
101
|
-
"
|
|
102
|
-
"
|
|
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: {
|
|
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
|
|
409
|
-
|
|
410
|
-
"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.",
|
|
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
|
|
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: "
|
|
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,
|
|
568
|
-
"tax refunds, rental income, and
|
|
569
|
-
"
|
|
570
|
-
"
|
|
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'
|
|
573
|
-
"
|
|
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
|
|
611
|
-
"
|
|
612
|
-
"
|
|
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
|
|
638
|
-
"expense rows to be tagged with matching labels
|
|
639
|
-
"
|
|
640
|
-
"
|
|
641
|
-
"
|
|
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
|
|
671
|
-
"
|
|
672
|
-
"
|
|
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
|
|
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
|
|
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
|
-
|
|
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(
|
|
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.
|
|
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 =
|
|
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
|
-
|
|
216
|
-
!signupResp?.result?.isError &&
|
|
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
|