@expensebot/mcp-server-auth 0.6.1 → 0.6.3
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 +563 -132
- 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.3",
|
|
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.3",
|
|
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,37 +183,22 @@ const TOOLS = [
|
|
|
94
183
|
{
|
|
95
184
|
name: "get_spending_summary",
|
|
96
185
|
description:
|
|
97
|
-
"
|
|
98
|
-
"
|
|
99
|
-
"
|
|
100
|
-
"
|
|
101
|
-
"
|
|
102
|
-
"property', 'P&L for Q1', 'profit by client', 'mileage this year', " +
|
|
103
|
-
"'recurring subscriptions', 'price increases', 'duplicate " +
|
|
104
|
-
"subscriptions', 'trial conversions'. Supports period comparison " +
|
|
105
|
-
"phrasing — 'this year vs last' (YoY), 'vs last month' (MoM), 'Q1 " +
|
|
106
|
-
"vs Q2' (QoQ), same-month-prev-year. Margin renders as multiplier " +
|
|
107
|
-
"('expenses 5.4× revenue') when in loss territory. Returns: " +
|
|
108
|
-
"{ message, data: { total, breakdown?, comparison?, sampleMeta? } }.",
|
|
186
|
+
"Summarize the user's recorded expenses with totals and breakdowns by " +
|
|
187
|
+
"category, merchant, month, tag, source, or payment method. Supports " +
|
|
188
|
+
"date ranges, period comparisons, and total, count, or average metrics. " +
|
|
189
|
+
"Read-only. Returns: { message, data: { total, breakdown?, comparison?, " +
|
|
190
|
+
"sampleMeta? } }.",
|
|
109
191
|
inputSchema: {
|
|
110
192
|
type: "object",
|
|
111
193
|
properties: {
|
|
194
|
+
clientEmail: CLIENT_EMAIL_SCHEMA,
|
|
112
195
|
query: {
|
|
113
196
|
type: "string",
|
|
114
197
|
description:
|
|
115
|
-
"Natural language question (e.g., 'how much did I spend in March', '
|
|
198
|
+
"Natural language question (e.g., 'how much did I spend in March', 'top merchants this quarter')",
|
|
116
199
|
},
|
|
117
200
|
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
|
-
},
|
|
201
|
+
dateRange: DATE_RANGE_SCHEMA,
|
|
128
202
|
groupBy: { type: "string", enum: ["category", "merchant", "month", "tag", "source", "paymentMethod"] },
|
|
129
203
|
metric: { type: "string", enum: ["total", "count", "average"] },
|
|
130
204
|
},
|
|
@@ -146,15 +220,7 @@ const TOOLS = [
|
|
|
146
220
|
type: "string",
|
|
147
221
|
description: "The analytics question to answer",
|
|
148
222
|
},
|
|
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
|
-
},
|
|
223
|
+
dateRange: DATE_RANGE_SCHEMA,
|
|
158
224
|
},
|
|
159
225
|
required: ["query"],
|
|
160
226
|
},
|
|
@@ -167,18 +233,7 @@ const TOOLS = [
|
|
|
167
233
|
inputSchema: {
|
|
168
234
|
type: "object",
|
|
169
235
|
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
|
-
},
|
|
236
|
+
dateRange: DATE_RANGE_SCHEMA,
|
|
182
237
|
title: { type: "string", description: "Custom report title" },
|
|
183
238
|
categories: { type: "array", items: { type: "string" } },
|
|
184
239
|
tags: { type: "array", items: { type: "string" } },
|
|
@@ -199,6 +254,7 @@ const TOOLS = [
|
|
|
199
254
|
inputSchema: {
|
|
200
255
|
type: "object",
|
|
201
256
|
properties: {
|
|
257
|
+
clientEmail: CLIENT_EMAIL_SCHEMA,
|
|
202
258
|
page: { type: "integer", default: 1 },
|
|
203
259
|
limit: { type: "integer", default: 20 },
|
|
204
260
|
filter: { type: "string", enum: ["All", "Draft", "Submitted", "Shared"], default: "All" },
|
|
@@ -213,6 +269,7 @@ const TOOLS = [
|
|
|
213
269
|
inputSchema: {
|
|
214
270
|
type: "object",
|
|
215
271
|
properties: {
|
|
272
|
+
clientEmail: CLIENT_EMAIL_SCHEMA,
|
|
216
273
|
reportId: { type: "string", description: "The report/spreadsheet ID" },
|
|
217
274
|
},
|
|
218
275
|
required: ["reportId"],
|
|
@@ -343,7 +400,9 @@ const TOOLS = [
|
|
|
343
400
|
name: "add_cash_expense",
|
|
344
401
|
description:
|
|
345
402
|
"Add an expense without a receipt (cash purchase, tip, etc.). " +
|
|
346
|
-
"Writes directly to the user's expense spreadsheet."
|
|
403
|
+
"Writes directly to the user's expense spreadsheet. Call list_categories " +
|
|
404
|
+
"first and choose one of the user's configured Expense Accounts. A unique " +
|
|
405
|
+
"account-label alias may be canonicalized, but unknown or ambiguous categories are rejected.",
|
|
347
406
|
inputSchema: {
|
|
348
407
|
type: "object",
|
|
349
408
|
properties: {
|
|
@@ -354,7 +413,11 @@ const TOOLS = [
|
|
|
354
413
|
description: "Expense date (YYYY-MM-DD)",
|
|
355
414
|
format: "date",
|
|
356
415
|
},
|
|
357
|
-
category: {
|
|
416
|
+
category: {
|
|
417
|
+
type: "string",
|
|
418
|
+
description:
|
|
419
|
+
"A configured Expense Account returned by list_categories. Do not invent a category.",
|
|
420
|
+
},
|
|
358
421
|
subtotal: { type: "number", description: "Subtotal before tax" },
|
|
359
422
|
tax: { type: "number", description: "Tax amount" },
|
|
360
423
|
tip: { type: "number", description: "Tip amount" },
|
|
@@ -411,9 +474,11 @@ const TOOLS = [
|
|
|
411
474
|
name: "scan_gmail",
|
|
412
475
|
description:
|
|
413
476
|
"Trigger a background Gmail scan to discover and process receipt " +
|
|
414
|
-
"emails
|
|
415
|
-
|
|
416
|
-
"in the UI.
|
|
477
|
+
"emails from the last ~60 days (default). Runs asynchronously — " +
|
|
478
|
+
"returns immediately, user gets an email summary when done. Like " +
|
|
479
|
+
'clicking "Find Receipts in Gmail" in the UI. For whole PAST YEARS ' +
|
|
480
|
+
"(e.g. 2023, or 2020-2022) use scan_gmail_years instead; to check a " +
|
|
481
|
+
"scan's progress use get_scan_status.",
|
|
417
482
|
inputSchema: {
|
|
418
483
|
type: "object",
|
|
419
484
|
properties: {
|
|
@@ -512,7 +577,9 @@ const TOOLS = [
|
|
|
512
577
|
description:
|
|
513
578
|
"Log an income entry manually (cash, check, Stripe payout, etc.). " +
|
|
514
579
|
"Writes to the Income tab of the user's expense spreadsheet. Useful " +
|
|
515
|
-
"for income that isn't auto-detected from Gmail or Plaid."
|
|
580
|
+
"for income that isn't auto-detected from Gmail or Plaid. Call " +
|
|
581
|
+
"list_income_categories first and use one of its fixed tax categories; " +
|
|
582
|
+
"an omitted category defaults to Service income and an unknown category is rejected.",
|
|
516
583
|
inputSchema: {
|
|
517
584
|
type: "object",
|
|
518
585
|
properties: {
|
|
@@ -523,7 +590,7 @@ const TOOLS = [
|
|
|
523
590
|
},
|
|
524
591
|
paymentMethod: {
|
|
525
592
|
type: "string",
|
|
526
|
-
description: "How you got paid
|
|
593
|
+
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
594
|
},
|
|
528
595
|
date: {
|
|
529
596
|
type: "string",
|
|
@@ -532,7 +599,7 @@ const TOOLS = [
|
|
|
532
599
|
},
|
|
533
600
|
currency: { type: "string", description: "Currency code (default: home currency)" },
|
|
534
601
|
description: { type: "string", description: "What the income was for" },
|
|
535
|
-
category: { type: "string", description: "
|
|
602
|
+
category: { type: "string", description: "A category returned by list_income_categories (optional; defaults to Service income)" },
|
|
536
603
|
reference: { type: "string", description: "Invoice or transaction reference" },
|
|
537
604
|
fees: { type: "number", description: "Processor/transfer fees deducted" },
|
|
538
605
|
taxCollected: { type: "number", description: "Sales tax/GST/HST collected" },
|
|
@@ -595,16 +662,7 @@ const TOOLS = [
|
|
|
595
662
|
enum: ["source", "category", "month", "paymentMethod", "tag"],
|
|
596
663
|
description: "How to group the breakdown",
|
|
597
664
|
},
|
|
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
|
-
},
|
|
665
|
+
dateRange: DATE_RANGE_SCHEMA,
|
|
608
666
|
incomeTagPrefix: {
|
|
609
667
|
type: "string",
|
|
610
668
|
description:
|
|
@@ -628,20 +686,12 @@ const TOOLS = [
|
|
|
628
686
|
inputSchema: {
|
|
629
687
|
type: "object",
|
|
630
688
|
properties: {
|
|
689
|
+
clientEmail: CLIENT_EMAIL_SCHEMA,
|
|
631
690
|
query: {
|
|
632
691
|
type: "string",
|
|
633
692
|
description: "Natural language P&L question (e.g., 'P&L for Q1 2025', 'am I profitable')",
|
|
634
693
|
},
|
|
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
|
-
},
|
|
694
|
+
dateRange: DATE_RANGE_SCHEMA,
|
|
645
695
|
},
|
|
646
696
|
},
|
|
647
697
|
},
|
|
@@ -670,28 +720,16 @@ const TOOLS = [
|
|
|
670
720
|
description:
|
|
671
721
|
"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
722
|
},
|
|
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
|
-
},
|
|
723
|
+
dateRange: DATE_RANGE_SCHEMA,
|
|
683
724
|
},
|
|
684
725
|
},
|
|
685
726
|
},
|
|
686
727
|
{
|
|
687
728
|
name: "list_income_categories",
|
|
688
729
|
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.).",
|
|
730
|
+
"List ExpenseBot's fixed income tax categories. Unlike Expense Accounts, " +
|
|
731
|
+
"these are not user-configured. Use this BEFORE calling add_income so " +
|
|
732
|
+
"you pass an exact canonical category instead of guessing.",
|
|
695
733
|
inputSchema: { type: "object", properties: {} },
|
|
696
734
|
},
|
|
697
735
|
{
|
|
@@ -699,9 +737,10 @@ const TOOLS = [
|
|
|
699
737
|
description:
|
|
700
738
|
"Show what the user (or their AI assistants) has recently done in " +
|
|
701
739
|
"ExpenseBot via this MCP server: which tools were called, when, with " +
|
|
702
|
-
"what arguments, and whether they succeeded.
|
|
703
|
-
"
|
|
704
|
-
"
|
|
740
|
+
"what arguments, and whether they succeeded. This is a log of assistant " +
|
|
741
|
+
"TOOL CALLS, not the processing history of a document. Useful for " +
|
|
742
|
+
"questions like 'what did I do this week' or 'which tools has my " +
|
|
743
|
+
"assistant run', and to give the user transparency into AI-assisted " +
|
|
705
744
|
"actions. Returns the most recent N entries from the audit log " +
|
|
706
745
|
"(default 20, max 100).",
|
|
707
746
|
inputSchema: {
|
|
@@ -725,7 +764,55 @@ const TOOLS = [
|
|
|
725
764
|
},
|
|
726
765
|
},
|
|
727
766
|
},
|
|
728
|
-
|
|
767
|
+
{
|
|
768
|
+
name: "trace_document",
|
|
769
|
+
description:
|
|
770
|
+
"Trace what happened to a specific receipt, invoice, forwarded email, Gmail receipt, or PDF in ExpenseBot processing. " +
|
|
771
|
+
"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. " +
|
|
772
|
+
"Returns a read-only timeline from the user's lineage audit trail.",
|
|
773
|
+
inputSchema: {
|
|
774
|
+
type: "object",
|
|
775
|
+
properties: {
|
|
776
|
+
query: {
|
|
777
|
+
type: "string",
|
|
778
|
+
description:
|
|
779
|
+
"Merchant, sender, subject, invoice number, or phrase to search for, e.g. 'Blue Rocket', 'Driversnote', 'Uber receipt'.",
|
|
780
|
+
},
|
|
781
|
+
receiptId: {
|
|
782
|
+
type: "string",
|
|
783
|
+
description: "ExpenseBot receipt/invoice ID if known, e.g. IR-123, RO-abc, RR-456.",
|
|
784
|
+
},
|
|
785
|
+
messageId: {
|
|
786
|
+
type: "string",
|
|
787
|
+
description: "Gmail message ID if known.",
|
|
788
|
+
},
|
|
789
|
+
threadId: {
|
|
790
|
+
type: "string",
|
|
791
|
+
description: "Gmail thread ID if known.",
|
|
792
|
+
},
|
|
793
|
+
outcome: {
|
|
794
|
+
type: "string",
|
|
795
|
+
enum: ["all", "created", "skipped", "suggested", "income_routed", "deduped", "removed_as_duplicate"],
|
|
796
|
+
description: "Optional processing outcome filter.",
|
|
797
|
+
default: "all",
|
|
798
|
+
},
|
|
799
|
+
days: {
|
|
800
|
+
type: "integer",
|
|
801
|
+
minimum: 1,
|
|
802
|
+
maximum: 180,
|
|
803
|
+
default: 30,
|
|
804
|
+
description: "How many days back to search.",
|
|
805
|
+
},
|
|
806
|
+
limit: {
|
|
807
|
+
type: "integer",
|
|
808
|
+
minimum: 1,
|
|
809
|
+
maximum: 250,
|
|
810
|
+
default: 80,
|
|
811
|
+
description: "Maximum lineage events to return.",
|
|
812
|
+
},
|
|
813
|
+
},
|
|
814
|
+
},
|
|
815
|
+
},
|
|
729
816
|
// ── Mileage & Subscriptions (v0.6.1) ─────────────────────────────────
|
|
730
817
|
// Both proxy to the same query_analytics action that powers the chat
|
|
731
818
|
// widget — runtime is auto-routed via classifyMileageIntent /
|
|
@@ -756,16 +843,7 @@ const TOOLS = [
|
|
|
756
843
|
enum: ["month", "tag", "purpose", "category"],
|
|
757
844
|
description: "How to group the breakdown",
|
|
758
845
|
},
|
|
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
|
-
},
|
|
846
|
+
dateRange: DATE_RANGE_SCHEMA,
|
|
769
847
|
},
|
|
770
848
|
},
|
|
771
849
|
},
|
|
@@ -792,16 +870,7 @@ const TOOLS = [
|
|
|
792
870
|
enum: ["recurring", "duplicates", "price_increases", "trial_conversions", "all"],
|
|
793
871
|
description: "Narrow the audit to a single category (default: all)",
|
|
794
872
|
},
|
|
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
|
-
},
|
|
873
|
+
dateRange: DATE_RANGE_SCHEMA,
|
|
805
874
|
},
|
|
806
875
|
},
|
|
807
876
|
},
|
|
@@ -811,7 +880,7 @@ const TOOLS = [
|
|
|
811
880
|
name: "get_expense_by_id",
|
|
812
881
|
description:
|
|
813
882
|
"Fetch a single expense row by its sheet row number or by its " +
|
|
814
|
-
"ExpenseBot expenseId (the
|
|
883
|
+
"ExpenseBot expenseId (the exact Receipt ID in Column Q). Returns the row's " +
|
|
815
884
|
"headers + values + a labeled {header → value} map so you can refer " +
|
|
816
885
|
"to a specific expense the user mentioned. Read-only.",
|
|
817
886
|
inputSchema: {
|
|
@@ -824,7 +893,7 @@ const TOOLS = [
|
|
|
824
893
|
},
|
|
825
894
|
expenseId: {
|
|
826
895
|
type: "string",
|
|
827
|
-
description: "ExpenseBot
|
|
896
|
+
description: "Exact full ExpenseBot Receipt ID from Column Q",
|
|
828
897
|
},
|
|
829
898
|
},
|
|
830
899
|
},
|
|
@@ -893,6 +962,280 @@ const TOOLS = [
|
|
|
893
962
|
},
|
|
894
963
|
},
|
|
895
964
|
},
|
|
965
|
+
|
|
966
|
+
// ── Pulse CFO Slice 4 — What-If ───────────────────────────────────────
|
|
967
|
+
// Deterministic scenario math (Safe Draw recompute + client income
|
|
968
|
+
// impact + tax set-aside). No model call: numbers always come from the
|
|
969
|
+
// pure functions, never from the AI. All three carry
|
|
970
|
+
// "estimates — confirm with your tax professional" in their response.
|
|
971
|
+
{
|
|
972
|
+
name: "whatif_afford",
|
|
973
|
+
description:
|
|
974
|
+
"Can I afford $X/month? Recomputes the user's Safe Monthly Draw " +
|
|
975
|
+
"(how much they can safely pay themselves) with an added recurring " +
|
|
976
|
+
"monthly cost, and returns a yes/tight/no verdict plus the before/" +
|
|
977
|
+
"after numbers. Use for questions like 'can I afford a $500/mo " +
|
|
978
|
+
"hire' or 'what if I add a $200/mo software subscription'. Requires " +
|
|
979
|
+
"at least 3 months of income history — otherwise returns " +
|
|
980
|
+
"insufficient_data rather than a guess.",
|
|
981
|
+
inputSchema: {
|
|
982
|
+
type: "object",
|
|
983
|
+
properties: {
|
|
984
|
+
deltaMonthly: {
|
|
985
|
+
type: "number",
|
|
986
|
+
minimum: 0,
|
|
987
|
+
description: "The new recurring monthly cost being considered, in the user's home currency",
|
|
988
|
+
},
|
|
989
|
+
},
|
|
990
|
+
required: ["deltaMonthly"],
|
|
991
|
+
},
|
|
992
|
+
},
|
|
993
|
+
{
|
|
994
|
+
name: "whatif_client",
|
|
995
|
+
description:
|
|
996
|
+
"What if a client pays late or leaves? mode='late30' shifts that " +
|
|
997
|
+
"client's OPEN invoice amounts out of the near-term expectation " +
|
|
998
|
+
"(they still owe it, it's just not landing this month). " +
|
|
999
|
+
"mode='gone' removes that client's trailing monthly income " +
|
|
1000
|
+
"contribution and recomputes Safe Draw against the reduced " +
|
|
1001
|
+
"baseline. Use for questions like 'what if Acme Corp pays 30 days " +
|
|
1002
|
+
"late' or 'what happens if I lose my biggest client'. Client " +
|
|
1003
|
+
"identity is matched against the Income tab's tag/source/" +
|
|
1004
|
+
"description fields — best effort, not a guaranteed match.",
|
|
1005
|
+
inputSchema: {
|
|
1006
|
+
type: "object",
|
|
1007
|
+
properties: {
|
|
1008
|
+
clientName: {
|
|
1009
|
+
type: "string",
|
|
1010
|
+
description: "The client's name as it appears on invoices or income rows",
|
|
1011
|
+
},
|
|
1012
|
+
mode: {
|
|
1013
|
+
type: "string",
|
|
1014
|
+
enum: ["late30", "gone"],
|
|
1015
|
+
description: "'late30' = shift open invoices 30 days late; 'gone' = client stops paying entirely",
|
|
1016
|
+
},
|
|
1017
|
+
},
|
|
1018
|
+
required: ["clientName", "mode"],
|
|
1019
|
+
},
|
|
1020
|
+
},
|
|
1021
|
+
{
|
|
1022
|
+
name: "whatif_tax_setaside",
|
|
1023
|
+
description:
|
|
1024
|
+
"What should I set aside for taxes? Surfaces the same monthly tax " +
|
|
1025
|
+
"set-aside estimate already computed for Safe Monthly Draw — wiring, " +
|
|
1026
|
+
"not new math. Flat-rate estimate (default 30%) against trailing " +
|
|
1027
|
+
"income minus recurring + variable spend. Use for 'how much should " +
|
|
1028
|
+
"I set aside for taxes this month'.",
|
|
1029
|
+
inputSchema: { type: "object", properties: {} },
|
|
1030
|
+
},
|
|
1031
|
+
{
|
|
1032
|
+
name: "scan_gmail_years",
|
|
1033
|
+
description:
|
|
1034
|
+
"Scan one or more COMPLETED PRIOR years of the user's Gmail for " +
|
|
1035
|
+
"receipts (e.g. years:[2023] or years:[2020,2021,2022]). Long-running " +
|
|
1036
|
+
"background job: the first eligible year starts immediately and the " +
|
|
1037
|
+
"rest queue, running one at a time (each full year typically takes a " +
|
|
1038
|
+
"couple of hours; the user can close the app). ALWAYS call first " +
|
|
1039
|
+
"WITHOUT confirmStart to preview which years are eligible, then ask " +
|
|
1040
|
+
"the user to confirm, then call again with confirmStart:true. For " +
|
|
1041
|
+
"receipts from the last ~60 days use scan_gmail instead. To check how " +
|
|
1042
|
+
"a scan is going, use get_scan_status. The current in-progress year " +
|
|
1043
|
+
"cannot be year-scanned.",
|
|
1044
|
+
inputSchema: {
|
|
1045
|
+
type: "object",
|
|
1046
|
+
properties: {
|
|
1047
|
+
years: {
|
|
1048
|
+
type: "array",
|
|
1049
|
+
items: { type: "number" },
|
|
1050
|
+
description: "Completed prior years to scan, e.g. [2020, 2021]. Max 10.",
|
|
1051
|
+
},
|
|
1052
|
+
accountEmail: {
|
|
1053
|
+
type: "string",
|
|
1054
|
+
description:
|
|
1055
|
+
"Optional: which connected Gmail inbox to scan (multi-inbox users). Defaults to the primary.",
|
|
1056
|
+
},
|
|
1057
|
+
confirmStart: {
|
|
1058
|
+
type: "boolean",
|
|
1059
|
+
description:
|
|
1060
|
+
"Omit or false = preview only (no scan starts). Must be exactly true to start scanning.",
|
|
1061
|
+
},
|
|
1062
|
+
},
|
|
1063
|
+
required: ["years"],
|
|
1064
|
+
},
|
|
1065
|
+
},
|
|
1066
|
+
{
|
|
1067
|
+
name: "get_scan_status",
|
|
1068
|
+
description:
|
|
1069
|
+
"Check the status of the user's Gmail receipt scans: whether a scan " +
|
|
1070
|
+
"is running right now, which years are queued for scanning, and " +
|
|
1071
|
+
"recent scan history (per inbox, with date range and counts). Call " +
|
|
1072
|
+
"this when the user asks how their scan is going or whether a year " +
|
|
1073
|
+
"has finished. Read-only.",
|
|
1074
|
+
inputSchema: { type: "object", properties: {} },
|
|
1075
|
+
},
|
|
1076
|
+
{
|
|
1077
|
+
name: "list_client_invoices",
|
|
1078
|
+
description:
|
|
1079
|
+
"List the user's issued client invoices (accounts receivable) — who owes " +
|
|
1080
|
+
"them money, how much, and when it is due. Examples: 'which invoices are " +
|
|
1081
|
+
"outstanding', 'what does Acme still owe me', 'any overdue invoices', " +
|
|
1082
|
+
"'how much am I waiting to get paid'. status accepts 'open' (default), " +
|
|
1083
|
+
"'paid', or 'all'. Read-only — it does not create, send, or mark invoices paid.",
|
|
1084
|
+
inputSchema: {
|
|
1085
|
+
type: "object",
|
|
1086
|
+
properties: {
|
|
1087
|
+
clientEmail: CLIENT_EMAIL_SCHEMA,
|
|
1088
|
+
status: {
|
|
1089
|
+
type: "string",
|
|
1090
|
+
enum: ["open", "paid", "all"],
|
|
1091
|
+
description: "Filter by invoice status (default open).",
|
|
1092
|
+
},
|
|
1093
|
+
clientName: {
|
|
1094
|
+
type: "string",
|
|
1095
|
+
description: "Optional: exact client name (case-insensitive).",
|
|
1096
|
+
},
|
|
1097
|
+
limit: {
|
|
1098
|
+
type: "number",
|
|
1099
|
+
description: "Max invoices to return (default 25, max 100).",
|
|
1100
|
+
},
|
|
1101
|
+
},
|
|
1102
|
+
},
|
|
1103
|
+
},
|
|
1104
|
+
{
|
|
1105
|
+
name: "get_expense_splits",
|
|
1106
|
+
description:
|
|
1107
|
+
"Show how an expense was split across categories, clients, properties, or " +
|
|
1108
|
+
"business vs personal portions. Returns the single parent payment with its " +
|
|
1109
|
+
"nested allocation lines — split lines are never counted as separate " +
|
|
1110
|
+
"expenses, so totals stay correct. Examples: 'how is that expense split', " +
|
|
1111
|
+
"'what was the business portion of that bill', 'show the allocation for " +
|
|
1112
|
+
"this receipt'. Read-only — splits are edited in ExpenseBot's Review workspace.",
|
|
1113
|
+
inputSchema: {
|
|
1114
|
+
type: "object",
|
|
1115
|
+
properties: {
|
|
1116
|
+
clientEmail: CLIENT_EMAIL_SCHEMA,
|
|
1117
|
+
receiptId: {
|
|
1118
|
+
type: "string",
|
|
1119
|
+
description: "Optional Receipt ID for one expense.",
|
|
1120
|
+
},
|
|
1121
|
+
dateRange: {
|
|
1122
|
+
description:
|
|
1123
|
+
"Optional window to search for split expenses. Both bounds inclusive, YYYY-MM-DD.",
|
|
1124
|
+
type: "object",
|
|
1125
|
+
properties: {
|
|
1126
|
+
startDate: {
|
|
1127
|
+
type: "string",
|
|
1128
|
+
description: "Inclusive start date in YYYY-MM-DD format.",
|
|
1129
|
+
},
|
|
1130
|
+
endDate: {
|
|
1131
|
+
type: "string",
|
|
1132
|
+
description: "Inclusive end date in YYYY-MM-DD format.",
|
|
1133
|
+
},
|
|
1134
|
+
},
|
|
1135
|
+
},
|
|
1136
|
+
onlySplit: {
|
|
1137
|
+
type: "boolean",
|
|
1138
|
+
description:
|
|
1139
|
+
"Return only expenses with active splits (default true). Set false to inspect an unsplit Receipt ID.",
|
|
1140
|
+
},
|
|
1141
|
+
limit: {
|
|
1142
|
+
type: "number",
|
|
1143
|
+
description: "Max parent expenses to return (default 25, max 100).",
|
|
1144
|
+
},
|
|
1145
|
+
},
|
|
1146
|
+
},
|
|
1147
|
+
},
|
|
1148
|
+
{
|
|
1149
|
+
name: "get_monthly_books_review",
|
|
1150
|
+
description:
|
|
1151
|
+
"Month-end summary of the user's books for one calendar month: income " +
|
|
1152
|
+
"recorded, money spent, net, top spending categories and merchants, plus " +
|
|
1153
|
+
"alerts for anything unusual that month. Examples: 'how did last month " +
|
|
1154
|
+
"go', 'close out my books for June', 'monthly review', 'what did I make " +
|
|
1155
|
+
"and spend in May'. Defaults to the last completed month. Figures come " +
|
|
1156
|
+
"from the user's own recorded data; advisory notes are estimates, not " +
|
|
1157
|
+
"tax advice.",
|
|
1158
|
+
inputSchema: {
|
|
1159
|
+
type: "object",
|
|
1160
|
+
properties: {
|
|
1161
|
+
clientEmail: CLIENT_EMAIL_SCHEMA,
|
|
1162
|
+
period: {
|
|
1163
|
+
type: "string",
|
|
1164
|
+
pattern: "^\\d{4}-\\d{2}$",
|
|
1165
|
+
description:
|
|
1166
|
+
"Calendar month in YYYY-MM format. Defaults to the last completed month.",
|
|
1167
|
+
},
|
|
1168
|
+
},
|
|
1169
|
+
},
|
|
1170
|
+
},
|
|
1171
|
+
{
|
|
1172
|
+
name: "get_credits_refunds",
|
|
1173
|
+
description:
|
|
1174
|
+
"List card refunds, cashback/rewards, and statement credits that " +
|
|
1175
|
+
"ExpenseBot has already recorded — either as negative expenses or matched " +
|
|
1176
|
+
"against the original charge. Examples: 'did my refund come through', " +
|
|
1177
|
+
"'show my statement credits', 'was that return recorded'. Returns the " +
|
|
1178
|
+
"most recent items (default 25, newest first); narrow with dateRange. " +
|
|
1179
|
+
"Read-only: it never scans cards, changes review decisions, or adds rows.",
|
|
1180
|
+
inputSchema: {
|
|
1181
|
+
type: "object",
|
|
1182
|
+
properties: {
|
|
1183
|
+
clientEmail: CLIENT_EMAIL_SCHEMA,
|
|
1184
|
+
dateRange: {
|
|
1185
|
+
description:
|
|
1186
|
+
"Optional window to narrow results. Both bounds inclusive, YYYY-MM-DD.",
|
|
1187
|
+
type: "object",
|
|
1188
|
+
properties: {
|
|
1189
|
+
startDate: {
|
|
1190
|
+
type: "string",
|
|
1191
|
+
description: "Inclusive start date in YYYY-MM-DD format.",
|
|
1192
|
+
},
|
|
1193
|
+
endDate: {
|
|
1194
|
+
type: "string",
|
|
1195
|
+
description: "Inclusive end date in YYYY-MM-DD format.",
|
|
1196
|
+
},
|
|
1197
|
+
},
|
|
1198
|
+
},
|
|
1199
|
+
limit: {
|
|
1200
|
+
type: "number",
|
|
1201
|
+
description: "Maximum results to return (default 25, max 100).",
|
|
1202
|
+
},
|
|
1203
|
+
},
|
|
1204
|
+
},
|
|
1205
|
+
},
|
|
1206
|
+
{
|
|
1207
|
+
name: "update_expense",
|
|
1208
|
+
description:
|
|
1209
|
+
"Update a single existing expense row's category, tag, merchant, or " +
|
|
1210
|
+
"business purpose (e.g. 'recategorize expense X to Meals' or 'tag it " +
|
|
1211
|
+
"Client – Acme'). Identify it only by the exact expenseId returned by " +
|
|
1212
|
+
"search_expenses (the full Receipt ID from Column Q). Never use a date, " +
|
|
1213
|
+
"displayed number, or sheet row number as expenseId. " +
|
|
1214
|
+
"Two-phase operation: calls with confirm omitted or false return a " +
|
|
1215
|
+
"preview of the current→proposed change and make no change. After user " +
|
|
1216
|
+
"confirmation, a call with confirm:true applies the proposed change. " +
|
|
1217
|
+
"Only category/tag/merchant/businessPurpose are " +
|
|
1218
|
+
"editable — amounts, dates, and notes are not editable via the " +
|
|
1219
|
+
"assistant. Does not create or delete rows.",
|
|
1220
|
+
inputSchema: {
|
|
1221
|
+
type: "object",
|
|
1222
|
+
properties: {
|
|
1223
|
+
expenseId: { type: "string", description: "Exact full Receipt ID from Column Q, returned as expenseId by search_expenses." },
|
|
1224
|
+
fields: {
|
|
1225
|
+
type: "object",
|
|
1226
|
+
description: "The fields to change. Only these keys are honored.",
|
|
1227
|
+
properties: {
|
|
1228
|
+
category: { type: "string" },
|
|
1229
|
+
tag: { type: "string" },
|
|
1230
|
+
merchant: { type: "string" },
|
|
1231
|
+
businessPurpose: { type: "string" },
|
|
1232
|
+
},
|
|
1233
|
+
},
|
|
1234
|
+
confirm: { type: "boolean", description: "Omit or false = preview only (no write). Must be exactly true to apply the change." },
|
|
1235
|
+
},
|
|
1236
|
+
required: ["expenseId", "fields"],
|
|
1237
|
+
},
|
|
1238
|
+
},
|
|
896
1239
|
];
|
|
897
1240
|
|
|
898
1241
|
// Tools available without authentication (onboarding mode)
|
|
@@ -938,7 +1281,7 @@ async function handleTool(name, args) {
|
|
|
938
1281
|
text:
|
|
939
1282
|
"**ExpenseBot — 60-day free trial, no credit card required**\n\n" +
|
|
940
1283
|
`Sign up: https://www.expensebot.ai?utm_source=${args?.utmSource || "mcp"}&utm_medium=ai-assistant\n\n` +
|
|
941
|
-
|
|
1284
|
+
`After signing up, generate an AI Assistant Token from Settings to unlock all ${TOOLS.length} tools ` +
|
|
942
1285
|
"(submit receipts, scan Gmail, search expenses, run income / P&L / per-tag P&L analytics, create reports).\n\n" +
|
|
943
1286
|
"Free for accountants forever. $10/month for everyone else.",
|
|
944
1287
|
},
|
|
@@ -950,13 +1293,15 @@ async function handleTool(name, args) {
|
|
|
950
1293
|
await client.execute("query_expenses", args)
|
|
951
1294
|
);
|
|
952
1295
|
|
|
953
|
-
case "get_spending_summary":
|
|
1296
|
+
case "get_spending_summary": {
|
|
1297
|
+
const { clientEmail: _clientEmail, ...businessArgs } = args;
|
|
954
1298
|
return formatResult(
|
|
955
1299
|
await client.execute("query_analytics", {
|
|
956
1300
|
...args,
|
|
957
|
-
message: args.query || JSON.stringify(
|
|
1301
|
+
message: args.query || JSON.stringify(businessArgs),
|
|
958
1302
|
})
|
|
959
1303
|
);
|
|
1304
|
+
}
|
|
960
1305
|
|
|
961
1306
|
case "get_deep_analytics":
|
|
962
1307
|
return formatResult(
|
|
@@ -1126,6 +1471,19 @@ async function handleTool(name, args) {
|
|
|
1126
1471
|
})
|
|
1127
1472
|
);
|
|
1128
1473
|
|
|
1474
|
+
case "trace_document":
|
|
1475
|
+
return formatResult(
|
|
1476
|
+
await client.execute("trace_document", {
|
|
1477
|
+
query: args.query,
|
|
1478
|
+
receiptId: args.receiptId,
|
|
1479
|
+
messageId: args.messageId,
|
|
1480
|
+
threadId: args.threadId,
|
|
1481
|
+
outcome: args.outcome || "all",
|
|
1482
|
+
days: args.days || 30,
|
|
1483
|
+
limit: args.limit || 80,
|
|
1484
|
+
})
|
|
1485
|
+
);
|
|
1486
|
+
|
|
1129
1487
|
// ── Mileage & Subscriptions (v0.6.1) ──
|
|
1130
1488
|
// Both proxy to query_analytics; classifyMileageIntent /
|
|
1131
1489
|
// classifySubscriptionIntent route to the correct helper server-side.
|
|
@@ -1236,6 +1594,79 @@ async function handleTool(name, args) {
|
|
|
1236
1594
|
};
|
|
1237
1595
|
}
|
|
1238
1596
|
|
|
1597
|
+
// ── Pulse CFO Slice 4 — What-If ──
|
|
1598
|
+
case "whatif_afford":
|
|
1599
|
+
return formatResult(
|
|
1600
|
+
await client.execute("whatif_afford", { deltaMonthly: args.deltaMonthly })
|
|
1601
|
+
);
|
|
1602
|
+
|
|
1603
|
+
case "whatif_client":
|
|
1604
|
+
return formatResult(
|
|
1605
|
+
await client.execute("whatif_client", { clientName: args.clientName, mode: args.mode })
|
|
1606
|
+
);
|
|
1607
|
+
|
|
1608
|
+
case "whatif_tax_setaside":
|
|
1609
|
+
return formatResult(await client.execute("whatif_tax_setaside", {}));
|
|
1610
|
+
|
|
1611
|
+
case "scan_gmail_years":
|
|
1612
|
+
return formatResult(
|
|
1613
|
+
await client.execute("scan_gmail_years", {
|
|
1614
|
+
years: args.years,
|
|
1615
|
+
accountEmail: args.accountEmail,
|
|
1616
|
+
confirmStart: args.confirmStart,
|
|
1617
|
+
})
|
|
1618
|
+
);
|
|
1619
|
+
|
|
1620
|
+
case "get_scan_status":
|
|
1621
|
+
return formatResult(await client.execute("get_scan_status", {}));
|
|
1622
|
+
|
|
1623
|
+
case "list_client_invoices":
|
|
1624
|
+
return formatResult(
|
|
1625
|
+
await client.execute("list_client_invoices", {
|
|
1626
|
+
clientEmail: args.clientEmail,
|
|
1627
|
+
status: args.status,
|
|
1628
|
+
clientName: args.clientName,
|
|
1629
|
+
limit: args.limit,
|
|
1630
|
+
})
|
|
1631
|
+
);
|
|
1632
|
+
|
|
1633
|
+
case "get_expense_splits":
|
|
1634
|
+
return formatResult(
|
|
1635
|
+
await client.execute("get_expense_splits", {
|
|
1636
|
+
clientEmail: args.clientEmail,
|
|
1637
|
+
receiptId: args.receiptId,
|
|
1638
|
+
dateRange: args.dateRange,
|
|
1639
|
+
onlySplit: args.onlySplit,
|
|
1640
|
+
limit: args.limit,
|
|
1641
|
+
})
|
|
1642
|
+
);
|
|
1643
|
+
|
|
1644
|
+
case "get_monthly_books_review":
|
|
1645
|
+
return formatResult(
|
|
1646
|
+
await client.execute("get_monthly_books_review", {
|
|
1647
|
+
clientEmail: args.clientEmail,
|
|
1648
|
+
period: args.period,
|
|
1649
|
+
})
|
|
1650
|
+
);
|
|
1651
|
+
|
|
1652
|
+
case "get_credits_refunds":
|
|
1653
|
+
return formatResult(
|
|
1654
|
+
await client.execute("get_credits_refunds", {
|
|
1655
|
+
clientEmail: args.clientEmail,
|
|
1656
|
+
dateRange: args.dateRange,
|
|
1657
|
+
limit: args.limit,
|
|
1658
|
+
})
|
|
1659
|
+
);
|
|
1660
|
+
|
|
1661
|
+
case "update_expense":
|
|
1662
|
+
return formatResult(
|
|
1663
|
+
await client.execute("update_expense", {
|
|
1664
|
+
expenseId: args.expenseId,
|
|
1665
|
+
fields: args.fields,
|
|
1666
|
+
confirm: args.confirm,
|
|
1667
|
+
})
|
|
1668
|
+
);
|
|
1669
|
+
|
|
1239
1670
|
default:
|
|
1240
1671
|
return {
|
|
1241
1672
|
content: [{ type: "text", text: `Unknown tool: ${name}` }],
|
|
@@ -1302,7 +1733,7 @@ function formatResult(result) {
|
|
|
1302
1733
|
|
|
1303
1734
|
async function main() {
|
|
1304
1735
|
const server = new Server(
|
|
1305
|
-
{ name: "expensebot-auth", version: "0.6.
|
|
1736
|
+
{ name: "expensebot-auth", version: "0.6.3" },
|
|
1306
1737
|
{ capabilities: { tools: {} } }
|
|
1307
1738
|
);
|
|
1308
1739
|
|
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
|