@expensebot/mcp-server-auth 0.6.13 → 0.6.17
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 +26 -8
- package/package.json +1 -1
- package/src/client.js +2 -2
- package/src/index.js +441 -24
- package/src/test.js +97 -1
- package/scripts/descriptions.generated.json +0 -10
package/README.md
CHANGED
|
@@ -2,11 +2,11 @@
|
|
|
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
|
+
**50 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), `get_last_receipt_result`, `add_cash_expense
|
|
9
|
+
- **Receipt and expense capture** — `submit_receipt` (photo/PDF), `get_last_receipt_result`, `add_cash_expense` (including confirmed client advances), `add_mileage_entry`, `add_income`, `add_income_from_file` (screenshot/PDF, parse-preview-confirm), `add_income_from_csv` (CSV/TSV/text, parse-preview-confirm), `parse_expense`, `get_expense_by_id`, `update_expense`, `group_expenses`, `correct_expenses`, `get_spreadsheet_url`
|
|
10
10
|
- **Gmail** — `scan_gmail`, `process_gmail_receipts`, `scan_gmail_years`, `get_scan_status`
|
|
11
11
|
- **Reports & invoicing** — `create_report`, `list_reports`, `get_report_details`, `share_report`, `export_report`, `list_client_invoices`
|
|
12
12
|
- **Expense review** — `get_expense_splits`, `get_monthly_books_review`, `get_credits_refunds`
|
|
@@ -33,7 +33,7 @@ prepended. `update_expense` refuses zero or multiple exact matches.
|
|
|
33
33
|
|
|
34
34
|
### Quick start (Claude Desktop)
|
|
35
35
|
|
|
36
|
-
1. Sign in
|
|
36
|
+
1. Sign in and open [AI Assistant Tokens](https://www.expensebot.ai/process-info?openMcpTokens=true&source=npm) → Generate
|
|
37
37
|
2. Copy the token (shown once)
|
|
38
38
|
3. Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (Mac) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
|
|
39
39
|
|
|
@@ -42,7 +42,10 @@ prepended. `update_expense` refuses zero or multiple exact matches.
|
|
|
42
42
|
"mcpServers": {
|
|
43
43
|
"expensebot": {
|
|
44
44
|
"command": "npx",
|
|
45
|
-
"args": ["-y", "@expensebot/mcp-server-auth",
|
|
45
|
+
"args": ["-y", "@expensebot/mcp-server-auth"],
|
|
46
|
+
"env": {
|
|
47
|
+
"EXPENSEBOT_TOKEN": "YOUR_TOKEN_HERE"
|
|
48
|
+
}
|
|
46
49
|
}
|
|
47
50
|
}
|
|
48
51
|
}
|
|
@@ -53,9 +56,11 @@ prepended. `update_expense` refuses zero or multiple exact matches.
|
|
|
53
56
|
### Quick start (Claude Code CLI)
|
|
54
57
|
|
|
55
58
|
```bash
|
|
56
|
-
claude mcp add expensebot -- npx -y @expensebot/mcp-server-auth
|
|
59
|
+
claude mcp add expensebot -- npx -y @expensebot/mcp-server-auth
|
|
57
60
|
```
|
|
58
61
|
|
|
62
|
+
Store `EXPENSEBOT_TOKEN` in Claude Code's environment or secret settings first. Do not put the token in the command or paste it into chat.
|
|
63
|
+
|
|
59
64
|
### Quick start (Cursor)
|
|
60
65
|
|
|
61
66
|
Edit `~/.cursor/mcp.json`:
|
|
@@ -65,7 +70,10 @@ Edit `~/.cursor/mcp.json`:
|
|
|
65
70
|
"mcpServers": {
|
|
66
71
|
"expensebot": {
|
|
67
72
|
"command": "npx",
|
|
68
|
-
"args": ["-y", "@expensebot/mcp-server-auth",
|
|
73
|
+
"args": ["-y", "@expensebot/mcp-server-auth"],
|
|
74
|
+
"env": {
|
|
75
|
+
"EXPENSEBOT_TOKEN": "YOUR_TOKEN_HERE"
|
|
76
|
+
}
|
|
69
77
|
}
|
|
70
78
|
}
|
|
71
79
|
}
|
|
@@ -75,7 +83,17 @@ Then in Cursor: Settings → Tools & Integrations → confirm the green dot next
|
|
|
75
83
|
|
|
76
84
|
### Continue, Cline, Windsurf, custom clients
|
|
77
85
|
|
|
78
|
-
|
|
86
|
+
Use `npx -y @expensebot/mcp-server-auth` in your client's MCP config and provide the token through its `EXPENSEBOT_TOKEN` environment or secret setting.
|
|
87
|
+
|
|
88
|
+
### Remote/custom agents (including Viktor)
|
|
89
|
+
|
|
90
|
+
If the client supports remote HTTP MCP with OAuth, add:
|
|
91
|
+
|
|
92
|
+
```text
|
|
93
|
+
https://mcp.expensebot.ai/mcp
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
Complete ExpenseBot sign-in and consent in the browser. No personal token or manual OAuth client secret is needed. If the client supports only local/stdio MCP, use the npm setup above. Never email a token or paste it into an AI conversation.
|
|
79
97
|
|
|
80
98
|
## Token model
|
|
81
99
|
|
|
@@ -121,7 +139,7 @@ Exposes the ExpenseBot knowledge base, FAQ, and feature docs as MCP resources. U
|
|
|
121
139
|
|
|
122
140
|
- Source: <https://github.com/TotesMagotes/expensebot/tree/master/mcp-server-auth>
|
|
123
141
|
- Issues: email `support@expensebot.ai`
|
|
124
|
-
-
|
|
142
|
+
- Complete setup chooser and remote/desktop instructions: <https://www.expensebot.ai/mcp#choose-connection>
|
|
125
143
|
|
|
126
144
|
## Maintainer: adding or changing a tool
|
|
127
145
|
|
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.17",
|
|
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/src/client.js
CHANGED
|
@@ -46,7 +46,7 @@ export class ExpenseBotClient {
|
|
|
46
46
|
headers: {
|
|
47
47
|
Authorization: `Bearer ${this.token}`,
|
|
48
48
|
"Content-Type": "application/json",
|
|
49
|
-
"User-Agent": "expensebot-mcp-auth/0.6.
|
|
49
|
+
"User-Agent": "expensebot-mcp-auth/0.6.17",
|
|
50
50
|
"X-ExpenseBot-MCP-Transport": "stdio",
|
|
51
51
|
...options.headers,
|
|
52
52
|
},
|
|
@@ -60,7 +60,7 @@ export class ExpenseBotClient {
|
|
|
60
60
|
"1. Go to https://www.expensebot.ai (sign up for free 60-day trial if you don't have an account)\n" +
|
|
61
61
|
"2. Click Settings → AI Assistant Tokens → Generate\n" +
|
|
62
62
|
"3. Copy the token (shown only once)\n" +
|
|
63
|
-
"4. Update your
|
|
63
|
+
"4. Update EXPENSEBOT_TOKEN in your AI client's secret or environment configuration\n" +
|
|
64
64
|
"5. Restart your AI client (Claude Desktop, Cursor, etc.)"
|
|
65
65
|
);
|
|
66
66
|
}
|
package/src/index.js
CHANGED
|
@@ -6,15 +6,17 @@
|
|
|
6
6
|
* create reports, get analytics, and more — using the user's actual
|
|
7
7
|
* ExpenseBot data.
|
|
8
8
|
*
|
|
9
|
-
* Usage:
|
|
10
|
-
*
|
|
9
|
+
* Usage: provide EXPENSEBOT_TOKEN through the client's secret/environment
|
|
10
|
+
* configuration, then run:
|
|
11
|
+
* npx @expensebot/mcp-server-auth
|
|
11
12
|
*
|
|
12
13
|
* Claude Desktop config:
|
|
13
14
|
* {
|
|
14
15
|
* "mcpServers": {
|
|
15
16
|
* "expensebot": {
|
|
16
17
|
* "command": "npx",
|
|
17
|
-
* "args": ["-y", "@expensebot/mcp-server-auth",
|
|
18
|
+
* "args": ["-y", "@expensebot/mcp-server-auth"],
|
|
19
|
+
* "env": { "EXPENSEBOT_TOKEN": "<stored securely by the client>" }
|
|
18
20
|
* }
|
|
19
21
|
* }
|
|
20
22
|
* }
|
|
@@ -28,7 +30,8 @@ import {
|
|
|
28
30
|
} from "@modelcontextprotocol/sdk/types.js";
|
|
29
31
|
import { ExpenseBotClient } from "./client.js";
|
|
30
32
|
|
|
31
|
-
//
|
|
33
|
+
// Environment configuration is canonical. Keep the legacy argument parser so
|
|
34
|
+
// existing installations do not break, but do not advertise secrets in argv.
|
|
32
35
|
const args = process.argv.slice(2);
|
|
33
36
|
let token = process.env.EXPENSEBOT_TOKEN;
|
|
34
37
|
for (const arg of args) {
|
|
@@ -43,6 +46,12 @@ const client = onboardingMode ? null : new ExpenseBotClient(token);
|
|
|
43
46
|
|
|
44
47
|
const SERVER_INSTRUCTIONS = [
|
|
45
48
|
"ExpenseBot tracks the user's business expenses and income in a Google Sheet they own.",
|
|
49
|
+
"For a requested multi-step workflow, be concise: show the grounded preview, ask one clear yes/no confirmation when required, then complete every approved step. Prefer group_expenses for group-and-report requests even when the expenses already have that group. Do not add unsolicited tax, audit, substantiation, or client-AP advice, and do not second-guess an approved scope unless a tool reports an ambiguity, conflict, or failure. A request to create, share, or bill from a report is NOT a request for compliance, tax, deductibility, report-detail, business-purpose, attendee, or reimbursement analysis: never call those tools as a preflight or follow-up unless the user explicitly asks for that analysis. 'Without personal expenses' is only a report filter. isReimbursable is ExpenseBot workflow state, not a judgment about whether an expense may be billed to a client.",
|
|
50
|
+
"For exact corrections across several expenses, use correct_expenses only after search_expenses has returned the exact expenseId values. Show its automatic preview, ask one yes/no question, then return its verified terminal result without adding advice. Use only attendee names the user explicitly supplied. For broad, ambiguous, mixed, or more than 100-row cleanup, link to Review Expenses instead.",
|
|
51
|
+
"Across every tool, treat returned counts, totals, currencies, statuses, and completion evidence as authoritative. Never recompute them from detail rows or reinterpret a successful result. After an approved write completes, report the outcome and relevant links without reopening the user's approved scope or adding unrequested advice. Ask another question only when the tool reports an ambiguity, conflict, failure, or required external side effect.",
|
|
52
|
+
"Across every answer, answer the user's requested task first and stop when it is complete. Do not infer intent, risk, tax treatment, reimbursement eligibility, business purpose, attendees, client expectations, or currency preferences from merchants, locations, dates, or amounts. Offer analysis, warnings, or follow-up work only when the user asks for it or an authoritative tool result says action is required.",
|
|
53
|
+
"A successful terminal write result supersedes intermediate search and preview observations. The final answer must follow the terminal result's responseGuidance and must not repeat exploratory candidates, excluded near-matches, or concerns that the terminal tool did not report. When a terminal result contains finalAnswer, return it verbatim and add nothing else. After a Bill Client handoff, do not offer report sharing or currency advice unless the user explicitly requested it.",
|
|
54
|
+
"Report provenance is literal: say a report was created only when the terminal result explicitly says creationStatus=created_this_call. Reports returned by list_reports are pre-existing; describe them as found, existing, or opened, never created or generated. If no new report was created, say so plainly and do not imply otherwise.",
|
|
46
55
|
"After submit_receipt returns a submissionId, call get_last_receipt_result with that exact ID using the polling interval and time allowance returned by submit_receipt. A small batch allows at least 5 minutes and larger batches allow longer. A pending result is normal; never resubmit the same file because that creates a duplicate. Report the final counts, then show spreadsheetUrl and reviewExpensesUrl.",
|
|
47
56
|
"After another expense submission, show the returned spreadsheetUrl and reviewExpensesUrl.",
|
|
48
57
|
"For income writes, show spreadsheetUrl and reviewIncomeUrl.",
|
|
@@ -278,8 +287,18 @@ const TOOLS = [
|
|
|
278
287
|
"excludes both the Personal tag and Personal expense category, matching " +
|
|
279
288
|
"ExpenseBot's Report Wizard. Returns the report summary, exact report " +
|
|
280
289
|
"link, Bill Client link, applied filters, and a prefilled Report Wizard " +
|
|
281
|
-
"fallback for criteria that need visual review.
|
|
282
|
-
"
|
|
290
|
+
"fallback for criteria that need visual review. Reports scoped to an " +
|
|
291
|
+
"existing client/project/trip group include matching expenses that are " +
|
|
292
|
+
"not already assigned to another ordinary report. Can optionally share " +
|
|
293
|
+
"with recipients. If no unreported matches remain, create no duplicate " +
|
|
294
|
+
"report and explain that the expenses are already in Reports. Terminal " +
|
|
295
|
+
"results also include accountingHandoffUrls for QuickBooks, Xero, and " +
|
|
296
|
+
"the existing file-export workflow. Use only the exact " +
|
|
297
|
+
"destination the user requested; the link opens the reviewed app flow " +
|
|
298
|
+
"and does not mean an export occurred. Complete " +
|
|
299
|
+
"the requested report directly; do not call " +
|
|
300
|
+
"check_compliance, get_report_details, or tax/deductibility tools before " +
|
|
301
|
+
"or after it unless the user explicitly asks for that separate analysis.",
|
|
283
302
|
inputSchema: {
|
|
284
303
|
type: "object",
|
|
285
304
|
properties: {
|
|
@@ -319,7 +338,10 @@ const TOOLS = [
|
|
|
319
338
|
name: "list_reports",
|
|
320
339
|
description:
|
|
321
340
|
"List the user's expense reports with pagination. Filter by status " +
|
|
322
|
-
"(All, Draft, Submitted, Shared)."
|
|
341
|
+
"(All, Draft, Submitted, Shared). Each exact report includes its app, " +
|
|
342
|
+
"Bill Client, and accounting handoff URLs. Use the matching accounting " +
|
|
343
|
+
"URL only when the user explicitly asks to send or export that report; " +
|
|
344
|
+
"the app keeps organization, mapping, preview, and final confirmation.",
|
|
323
345
|
inputSchema: {
|
|
324
346
|
type: "object",
|
|
325
347
|
properties: {
|
|
@@ -334,14 +356,22 @@ const TOOLS = [
|
|
|
334
356
|
name: "get_report_details",
|
|
335
357
|
description:
|
|
336
358
|
"Get full details of a specific expense report including all expenses, " +
|
|
337
|
-
"totals, and compliance status."
|
|
359
|
+
"totals, and compliance status. Use only when the user explicitly asks " +
|
|
360
|
+
"to inspect an existing report's details. Never call this as a preflight " +
|
|
361
|
+
"or follow-up to creating, sharing, or billing from a report; those tools " +
|
|
362
|
+
"already return the required result and links.",
|
|
338
363
|
inputSchema: {
|
|
339
364
|
type: "object",
|
|
340
365
|
properties: {
|
|
341
366
|
clientEmail: CLIENT_EMAIL_SCHEMA,
|
|
342
367
|
reportId: { type: "string", description: "The report/spreadsheet ID" },
|
|
368
|
+
userRequest: {
|
|
369
|
+
type: "string",
|
|
370
|
+
description:
|
|
371
|
+
"The user's exact request asking to inspect this report. Do not paraphrase or invent diagnostic intent.",
|
|
372
|
+
},
|
|
343
373
|
},
|
|
344
|
-
required: ["reportId"],
|
|
374
|
+
required: ["reportId", "userRequest"],
|
|
345
375
|
},
|
|
346
376
|
},
|
|
347
377
|
{
|
|
@@ -364,14 +394,22 @@ const TOOLS = [
|
|
|
364
394
|
{
|
|
365
395
|
name: "check_compliance",
|
|
366
396
|
description:
|
|
367
|
-
"
|
|
368
|
-
"purpose
|
|
397
|
+
"Use only when the user explicitly asks to check an existing report for " +
|
|
398
|
+
"compliance issues such as missing business purpose or policy violations. " +
|
|
399
|
+
"Creating a report, excluding Personal expenses, sharing a report, or " +
|
|
400
|
+
"billing a client is not a compliance request; never call this tool " +
|
|
401
|
+
"automatically as a preflight or follow-up for those workflows.",
|
|
369
402
|
inputSchema: {
|
|
370
403
|
type: "object",
|
|
371
404
|
properties: {
|
|
372
405
|
reportId: { type: "string", description: "Report ID to check" },
|
|
406
|
+
userRequest: {
|
|
407
|
+
type: "string",
|
|
408
|
+
description:
|
|
409
|
+
"The user's exact request explicitly asking for compliance, policy, audit, substantiation, or business-purpose analysis. Do not paraphrase or invent intent.",
|
|
410
|
+
},
|
|
373
411
|
},
|
|
374
|
-
required: ["reportId"],
|
|
412
|
+
required: ["reportId", "userRequest"],
|
|
375
413
|
},
|
|
376
414
|
},
|
|
377
415
|
{
|
|
@@ -448,6 +486,7 @@ const TOOLS = [
|
|
|
448
486
|
},
|
|
449
487
|
{
|
|
450
488
|
name: "submit_receipt",
|
|
489
|
+
_meta: { "openai/fileParams": ["photo"] },
|
|
451
490
|
description:
|
|
452
491
|
"Submit a photo or PDF of a receipt for processing. Covers requests " +
|
|
453
492
|
"phrased as 'log this', 'log this receipt', 'save this receipt', " +
|
|
@@ -628,15 +667,28 @@ const TOOLS = [
|
|
|
628
667
|
{
|
|
629
668
|
name: "add_cash_expense",
|
|
630
669
|
description:
|
|
631
|
-
"Add an expense without a receipt
|
|
632
|
-
"Writes directly to the user's expense spreadsheet.
|
|
633
|
-
"first and
|
|
634
|
-
"
|
|
670
|
+
"Add an expense without a receipt, or record money a client provided in advance for expenses. " +
|
|
671
|
+
"Writes directly to the user's expense spreadsheet after confirmation. For an ordinary expense, " +
|
|
672
|
+
"call list_categories first and provide a configured Expense Account. For a client advance, set " +
|
|
673
|
+
"isClientAdvance=true and clientName; ExpenseBot reuses or creates the canonical client group, " +
|
|
674
|
+
"applies Cash advance received, and stores the amount as a negative expense. Use this only for " +
|
|
675
|
+
"money supplied by a client before related spending, never for vendor refunds, reimbursements, " +
|
|
676
|
+
"earned fees, retainers, or generic deposits. " +
|
|
677
|
+
"Use the Manual expense link from get_spreadsheet_url instead when the user " +
|
|
678
|
+
"needs a reviewed form for multiple entries, credits/refunds, tax or tip " +
|
|
679
|
+
"breakdowns, per diem, or incomplete details.",
|
|
635
680
|
inputSchema: {
|
|
636
681
|
type: "object",
|
|
637
682
|
properties: {
|
|
638
|
-
merchant: {
|
|
639
|
-
|
|
683
|
+
merchant: {
|
|
684
|
+
type: "string",
|
|
685
|
+
description:
|
|
686
|
+
"Merchant/vendor name for an ordinary expense. Not needed for a client advance; ExpenseBot derives it from clientName.",
|
|
687
|
+
},
|
|
688
|
+
total: {
|
|
689
|
+
type: "number",
|
|
690
|
+
description: "Positive amount paid or received. ExpenseBot stores a client advance as negative.",
|
|
691
|
+
},
|
|
640
692
|
date: {
|
|
641
693
|
type: "string",
|
|
642
694
|
description: "Expense date (YYYY-MM-DD)",
|
|
@@ -653,8 +705,18 @@ const TOOLS = [
|
|
|
653
705
|
currency: { type: "string", description: "Currency code (default: USD)" },
|
|
654
706
|
city: { type: "string", description: "City/location" },
|
|
655
707
|
notes: { type: "string", description: "Notes or description" },
|
|
708
|
+
isClientAdvance: {
|
|
709
|
+
type: "boolean",
|
|
710
|
+
description:
|
|
711
|
+
"True only when a client supplied money in advance for expenses. Requires clientName and does not require category.",
|
|
712
|
+
},
|
|
713
|
+
clientName: {
|
|
714
|
+
type: "string",
|
|
715
|
+
description:
|
|
716
|
+
"Client name for a client advance, in ordinary language. ExpenseBot resolves the canonical Client – Name group.",
|
|
717
|
+
},
|
|
656
718
|
},
|
|
657
|
-
required: ["
|
|
719
|
+
required: ["total", "date"],
|
|
658
720
|
},
|
|
659
721
|
},
|
|
660
722
|
{
|
|
@@ -758,7 +820,10 @@ const TOOLS = [
|
|
|
758
820
|
"consultants, contractors, and anyone who drives for work. Requires " +
|
|
759
821
|
"the user to have configured their mileage rate (cents/km or cents/mi) " +
|
|
760
822
|
"and unit (mi/km) in ExpenseBot Settings. The trip writes a row to " +
|
|
761
|
-
"their expense spreadsheet with the calculated dollar value."
|
|
823
|
+
"their expense spreadsheet with the calculated dollar value. Use the " +
|
|
824
|
+
"Mileage and travel link from get_spreadsheet_url instead when the user " +
|
|
825
|
+
"needs Google Maps route calculation, mileage settings, repeated trips, " +
|
|
826
|
+
"calendar/rideshare import, per diem, or visual review.",
|
|
762
827
|
inputSchema: {
|
|
763
828
|
type: "object",
|
|
764
829
|
properties: {
|
|
@@ -838,6 +903,191 @@ const TOOLS = [
|
|
|
838
903
|
required: ["amount", "source", "paymentMethod"],
|
|
839
904
|
},
|
|
840
905
|
},
|
|
906
|
+
{
|
|
907
|
+
name: "add_income_from_file",
|
|
908
|
+
_meta: { "openai/fileParams": ["photo"] },
|
|
909
|
+
description:
|
|
910
|
+
"Import income from an attached screenshot, image (JPEG, PNG, WebP, HEIC/HEIF), or PDF " +
|
|
911
|
+
"(payment screenshots, wallet apps, payout or bank statements; max 10 MB). This is a " +
|
|
912
|
+
"two-step tool. STEP 1: call it with the file and WITHOUT confirm — ExpenseBot parses the " +
|
|
913
|
+
"file with the same importer as the app's Add Income screen, checks every row against the " +
|
|
914
|
+
"user's Income tab for duplicates, and returns a preview with a previewId, exact row count, " +
|
|
915
|
+
"totals by currency, per-row details, duplicate flags, and any rejected rows. NOTHING is " +
|
|
916
|
+
"saved in step 1; treat the attachment as consent to parse, not consent to write. Show the " +
|
|
917
|
+
"user the parsed rows and duplicates, then STEP 2: call again with confirm: true and the " +
|
|
918
|
+
"previewId to write exactly those rows. Only include user-approved changes in step 2 " +
|
|
919
|
+
"(selectedIndexes, keepBothIndexes, rowEdits, tag, bulkNote). Flagged duplicates are skipped " +
|
|
920
|
+
"unless the user explicitly asks to keep them (keepBothIndexes). The preview expires after " +
|
|
921
|
+
"15 minutes; an expired or unknown previewId never writes. After a successful confirm, show " +
|
|
922
|
+
"the returned spreadsheetUrl and reviewIncomeUrl. For a visually complex review (mixed " +
|
|
923
|
+
"income/expense rows, many edits), send the user to the Add Income app link returned by " +
|
|
924
|
+
"get_spreadsheet_url instead.",
|
|
925
|
+
inputSchema: {
|
|
926
|
+
type: "object",
|
|
927
|
+
properties: {
|
|
928
|
+
photo: {
|
|
929
|
+
type: "string",
|
|
930
|
+
description:
|
|
931
|
+
"Base64-encoded image/PDF bytes (step 1). On ChatGPT you may pass the attached file " +
|
|
932
|
+
"reference object directly; the server fetches the bytes.",
|
|
933
|
+
},
|
|
934
|
+
mimeType: {
|
|
935
|
+
type: "string",
|
|
936
|
+
enum: [
|
|
937
|
+
"image/jpeg",
|
|
938
|
+
"image/png",
|
|
939
|
+
"image/webp",
|
|
940
|
+
"image/heic",
|
|
941
|
+
"image/heif",
|
|
942
|
+
"application/pdf",
|
|
943
|
+
],
|
|
944
|
+
description: "MIME type of the file (default: image/jpeg)",
|
|
945
|
+
},
|
|
946
|
+
paymentMethod: {
|
|
947
|
+
type: "string",
|
|
948
|
+
description:
|
|
949
|
+
"Fallback payment rail for rows where the parser found none (Cash, Check, " +
|
|
950
|
+
"Bank transfer, Wallet app, Credit/Debit card, Payment processor, or Other).",
|
|
951
|
+
},
|
|
952
|
+
tag: {
|
|
953
|
+
type: "string",
|
|
954
|
+
description:
|
|
955
|
+
"Optional client/project tag. In step 1 it pre-fills the staged rows; in step 2 it " +
|
|
956
|
+
"applies to the confirmed selection.",
|
|
957
|
+
},
|
|
958
|
+
confirm: {
|
|
959
|
+
type: "boolean",
|
|
960
|
+
description:
|
|
961
|
+
"Step 2 only: true writes the staged rows. Omit it (with previewId absent) to parse " +
|
|
962
|
+
"and preview without writing.",
|
|
963
|
+
},
|
|
964
|
+
previewId: {
|
|
965
|
+
type: "string",
|
|
966
|
+
description: "Step 2 only: the previewId returned by the step-1 call.",
|
|
967
|
+
},
|
|
968
|
+
selectedIndexes: {
|
|
969
|
+
type: "array",
|
|
970
|
+
items: { type: "integer" },
|
|
971
|
+
description:
|
|
972
|
+
"Step 2 only: preview row indexes to write. Omit to write all staged rows.",
|
|
973
|
+
},
|
|
974
|
+
keepBothIndexes: {
|
|
975
|
+
type: "array",
|
|
976
|
+
items: { type: "integer" },
|
|
977
|
+
description:
|
|
978
|
+
"Step 2 only: preview indexes of duplicate-flagged rows the user explicitly wants to " +
|
|
979
|
+
"keep anyway (the app's 'Keep Both').",
|
|
980
|
+
},
|
|
981
|
+
rowEdits: {
|
|
982
|
+
type: "array",
|
|
983
|
+
description:
|
|
984
|
+
"Step 2 only: user-approved corrections, at most 50 rows. Fields: date (ISO " +
|
|
985
|
+
"YYYY-MM-DD), source, amount, currency, category, paymentMethod, description, notes, " +
|
|
986
|
+
"reference, fees, taxCollected, tag.",
|
|
987
|
+
items: {
|
|
988
|
+
type: "object",
|
|
989
|
+
properties: {
|
|
990
|
+
index: { type: "integer", description: "Preview row index" },
|
|
991
|
+
fields: { type: "object", additionalProperties: true },
|
|
992
|
+
},
|
|
993
|
+
required: ["index", "fields"],
|
|
994
|
+
},
|
|
995
|
+
},
|
|
996
|
+
bulkNote: {
|
|
997
|
+
type: "string",
|
|
998
|
+
description:
|
|
999
|
+
"Step 2 only: one note (max 120 chars) prepended to every confirmed row's Notes, " +
|
|
1000
|
+
"same as the app's 'Add note to all entries'.",
|
|
1001
|
+
},
|
|
1002
|
+
},
|
|
1003
|
+
required: [],
|
|
1004
|
+
},
|
|
1005
|
+
},
|
|
1006
|
+
{
|
|
1007
|
+
name: "add_income_from_csv",
|
|
1008
|
+
_meta: { "openai/fileParams": ["csvContent"] },
|
|
1009
|
+
description:
|
|
1010
|
+
"Import income from a CSV/TSV/text export (Stripe, PayPal, Square, Cash App, Venmo, " +
|
|
1011
|
+
"OnlyFans, Patreon, Clips4Sale, Ko-fi, Gumroad, Etsy, Uber/Lyft/DoorDash driver exports, " +
|
|
1012
|
+
"bank statements, and similar; max 500 KB). Same two-step contract as " +
|
|
1013
|
+
"add_income_from_file: STEP 1 call with csvContent and WITHOUT confirm parses the file " +
|
|
1014
|
+
"with the same platform-agnostic importer as the app's Add Income screen (platform " +
|
|
1015
|
+
"detection, fee handling, refunds, source aliases, ISO dates) and returns a duplicate-checked " +
|
|
1016
|
+
"preview with a previewId. NOTHING is saved in step 1. Show the user the parsed rows and " +
|
|
1017
|
+
"duplicates, then STEP 2 call again with confirm: true and the previewId to write exactly " +
|
|
1018
|
+
"those rows, optionally with user-approved selectedIndexes, keepBothIndexes, rowEdits, tag, " +
|
|
1019
|
+
"or bulkNote. Flagged duplicates are skipped unless the user explicitly keeps them. The " +
|
|
1020
|
+
"preview expires after 15 minutes and an expired or unknown previewId never writes. After a " +
|
|
1021
|
+
"successful confirm, show the returned spreadsheetUrl and reviewIncomeUrl.",
|
|
1022
|
+
inputSchema: {
|
|
1023
|
+
type: "object",
|
|
1024
|
+
properties: {
|
|
1025
|
+
csvContent: {
|
|
1026
|
+
type: "string",
|
|
1027
|
+
description:
|
|
1028
|
+
"Raw CSV/TSV/text content (step 1). On ChatGPT you may pass the attached file " +
|
|
1029
|
+
"reference object directly; the server fetches and decodes the bytes.",
|
|
1030
|
+
},
|
|
1031
|
+
paymentMethod: {
|
|
1032
|
+
type: "string",
|
|
1033
|
+
description:
|
|
1034
|
+
"Fallback payment rail for rows where the parser found none (Cash, Check, " +
|
|
1035
|
+
"Bank transfer, Wallet app, Credit/Debit card, Payment processor, or Other).",
|
|
1036
|
+
},
|
|
1037
|
+
tag: {
|
|
1038
|
+
type: "string",
|
|
1039
|
+
description:
|
|
1040
|
+
"Optional client/project tag. In step 1 it pre-fills the staged rows; in step 2 it " +
|
|
1041
|
+
"applies to the confirmed selection.",
|
|
1042
|
+
},
|
|
1043
|
+
confirm: {
|
|
1044
|
+
type: "boolean",
|
|
1045
|
+
description:
|
|
1046
|
+
"Step 2 only: true writes the staged rows. Omit it (with previewId absent) to parse " +
|
|
1047
|
+
"and preview without writing.",
|
|
1048
|
+
},
|
|
1049
|
+
previewId: {
|
|
1050
|
+
type: "string",
|
|
1051
|
+
description: "Step 2 only: the previewId returned by the step-1 call.",
|
|
1052
|
+
},
|
|
1053
|
+
selectedIndexes: {
|
|
1054
|
+
type: "array",
|
|
1055
|
+
items: { type: "integer" },
|
|
1056
|
+
description:
|
|
1057
|
+
"Step 2 only: preview row indexes to write. Omit to write all staged rows.",
|
|
1058
|
+
},
|
|
1059
|
+
keepBothIndexes: {
|
|
1060
|
+
type: "array",
|
|
1061
|
+
items: { type: "integer" },
|
|
1062
|
+
description:
|
|
1063
|
+
"Step 2 only: preview indexes of duplicate-flagged rows the user explicitly wants to " +
|
|
1064
|
+
"keep anyway (the app's 'Keep Both').",
|
|
1065
|
+
},
|
|
1066
|
+
rowEdits: {
|
|
1067
|
+
type: "array",
|
|
1068
|
+
description:
|
|
1069
|
+
"Step 2 only: user-approved corrections, at most 50 rows. Fields: date (ISO " +
|
|
1070
|
+
"YYYY-MM-DD), source, amount, currency, category, paymentMethod, description, notes, " +
|
|
1071
|
+
"reference, fees, taxCollected, tag.",
|
|
1072
|
+
items: {
|
|
1073
|
+
type: "object",
|
|
1074
|
+
properties: {
|
|
1075
|
+
index: { type: "integer", description: "Preview row index" },
|
|
1076
|
+
fields: { type: "object", additionalProperties: true },
|
|
1077
|
+
},
|
|
1078
|
+
required: ["index", "fields"],
|
|
1079
|
+
},
|
|
1080
|
+
},
|
|
1081
|
+
bulkNote: {
|
|
1082
|
+
type: "string",
|
|
1083
|
+
description:
|
|
1084
|
+
"Step 2 only: one note (max 120 chars) prepended to every confirmed row's Notes, " +
|
|
1085
|
+
"same as the app's 'Add note to all entries'.",
|
|
1086
|
+
},
|
|
1087
|
+
},
|
|
1088
|
+
required: [],
|
|
1089
|
+
},
|
|
1090
|
+
},
|
|
841
1091
|
{
|
|
842
1092
|
name: "list_categories",
|
|
843
1093
|
description:
|
|
@@ -1162,6 +1412,22 @@ const TOOLS = [
|
|
|
1162
1412
|
"or General Settings link. Category, G/L, and account-code requests use " +
|
|
1163
1413
|
"Category management; client, project, and trip groups use Group " +
|
|
1164
1414
|
"management; questions about what counts as Personal use Personal rules. " +
|
|
1415
|
+
"When the user asks to choose receipt images from Google Photos, use the " +
|
|
1416
|
+
"returned Google Photos link; it opens the existing authenticated picker " +
|
|
1417
|
+
"and handles any required Google consent in ExpenseBot. When they ask " +
|
|
1418
|
+
"where ExpenseBot stores receipt files, return the Drive folder link only " +
|
|
1419
|
+
"when it is available; never invent or request a folder ID. " +
|
|
1420
|
+
"For a complete, unambiguous cash expense or mileage trip, use the direct " +
|
|
1421
|
+
"write tool. Use the returned Manual expense link for multiple entries, " +
|
|
1422
|
+
"credits/refunds, detailed tax/tip entry, per diem, incomplete details, or " +
|
|
1423
|
+
"visual review. Use the Mileage and travel link for route calculation, " +
|
|
1424
|
+
"mileage settings, repeated trips, calendar/rideshare imports, per diem, " +
|
|
1425
|
+
"or visual review. These links open the existing reviewed app forms. " +
|
|
1426
|
+
"When the user wants to import income from a screenshot, PDF, or CSV but " +
|
|
1427
|
+
"no attachment is available in chat (or the review is visually complex), " +
|
|
1428
|
+
"use the returned Import income links — they open the existing Add Income " +
|
|
1429
|
+
"importer, which parses the file and shows every row for review before " +
|
|
1430
|
+
"anything is saved. " +
|
|
1165
1431
|
"Team setup requests use the returned role-aware Team setup handoff: " +
|
|
1166
1432
|
"eligible solo business owners open Add teammates, while existing team " +
|
|
1167
1433
|
"owners and co-admins open License Manager. If the handoff says owner " +
|
|
@@ -1470,9 +1736,13 @@ const TOOLS = [
|
|
|
1470
1736
|
"Examples: 'group my Mexico meals for client Rob', 'put these Vegas expenses under the Vegas project', " +
|
|
1471
1737
|
"or 'group these for client Rob and create a report'. The user does not need to know about tags: " +
|
|
1472
1738
|
"ExpenseBot resolves the requested name against existing groups and proposes creating one only when needed. " +
|
|
1473
|
-
"Use exact expenseId values returned by search_expenses.
|
|
1474
|
-
"
|
|
1475
|
-
"
|
|
1739
|
+
"Use exact expenseId values returned by search_expenses. A grounded preview is automatic for every bulk request; " +
|
|
1740
|
+
"the user does not need to ask for one. First call with confirm omitted/false, show the returned exact rows, count, " +
|
|
1741
|
+
"totals, proposed group, exclusions, and conflicts, then ask for approval. Only after explicit user approval, " +
|
|
1742
|
+
"repeat the same operationId and selection with confirm:true. A premature confirm:true is converted to preview. " +
|
|
1743
|
+
"When the request includes a report, set createReport:true on that confirmed group_expenses call and use its report result; do not run a separate broader create_report query. " +
|
|
1744
|
+
"For 'without personal expenses', set excludePersonal:true; ExpenseBot removes Personal-tagged and Personal-category rows before preview so their Personal marker is never overwritten. " +
|
|
1745
|
+
"The confirmed operation returns exact report and Bill Client links. Expenses already assigned to another ordinary report are excluded; if none remain, no duplicate report is created and the result links to Reports instead. Keep the user-facing response concise and do not add unsolicited tax or substantiation advice. Do not call check_compliance, get_report_details, or tax/deductibility tools before or after this workflow unless the user explicitly asks for that separate analysis. " +
|
|
1476
1746
|
"Sharing remains a separate share_report action with recipient confirmation.",
|
|
1477
1747
|
inputSchema: {
|
|
1478
1748
|
type: "object",
|
|
@@ -1521,6 +1791,20 @@ const TOOLS = [
|
|
|
1521
1791
|
approveNewGroup: { type: "boolean", description: "True only when the preview says a new group is required." },
|
|
1522
1792
|
createReport: { type: "boolean", description: "Create a report from the exact eligible grouped expenses." },
|
|
1523
1793
|
reportTitle: { type: "string" },
|
|
1794
|
+
excludePersonal: {
|
|
1795
|
+
type: "boolean",
|
|
1796
|
+
description: "Exclude Personal-tagged and Personal-category expenses from both grouping and the exact report.",
|
|
1797
|
+
},
|
|
1798
|
+
excludedTags: {
|
|
1799
|
+
type: "array",
|
|
1800
|
+
items: { type: "string" },
|
|
1801
|
+
description: "Existing groups to exclude before preview and grouping.",
|
|
1802
|
+
},
|
|
1803
|
+
excludedCategories: {
|
|
1804
|
+
type: "array",
|
|
1805
|
+
items: { type: "string" },
|
|
1806
|
+
description: "Expense categories to exclude before preview and grouping.",
|
|
1807
|
+
},
|
|
1524
1808
|
status: { type: "boolean", description: "Read operation status using operationId." },
|
|
1525
1809
|
undo: { type: "boolean", description: "Undo a completed grouping within its undo window." },
|
|
1526
1810
|
},
|
|
@@ -1565,6 +1849,105 @@ const TOOLS = [
|
|
|
1565
1849
|
required: ["expenseId", "fields"],
|
|
1566
1850
|
},
|
|
1567
1851
|
},
|
|
1852
|
+
{
|
|
1853
|
+
name: "correct_expenses",
|
|
1854
|
+
description:
|
|
1855
|
+
"Safely correct the category, business purpose, or explicit attendees on an exact bounded set of recorded expenses. " +
|
|
1856
|
+
"Examples: 'categorize these as Travel', 'add Client kickoff dinner as the business purpose for these meals', or " +
|
|
1857
|
+
"'add Fred, Rob, and Lamar to last night's business meal'. First use search_expenses to identify the exact rows, then pass their full expenseId values. " +
|
|
1858
|
+
"A grounded preview is automatic: first call with confirm omitted/false, show the exact count and proposed before-to-after changes, and ask once for approval. " +
|
|
1859
|
+
"Only after explicit approval repeat the same operationId, selection, and change with confirm:true. A premature confirm:true is converted to preview. " +
|
|
1860
|
+
"Attendee names must come explicitly from the user; never infer them. attendeeMode add preserves existing attendees, while replace substitutes only the attendee segment. " +
|
|
1861
|
+
"Business purpose and attendees preserve the structured Notes field, including card, description, inbox, and other typed segments. Formula Notes and changes that exceed the Notes limit are skipped safely. " +
|
|
1862
|
+
"The confirmed result reports applied/conflicted/failed counts and supports Undo. This tool does not omit duplicates, change amounts or dates, infer business context, or run broad Calendar matching. " +
|
|
1863
|
+
"For unsupported or more than 100-row cleanup, send the user to https://www.expensebot.ai/review-expenses?source=mcp.",
|
|
1864
|
+
inputSchema: {
|
|
1865
|
+
type: "object",
|
|
1866
|
+
additionalProperties: false,
|
|
1867
|
+
properties: {
|
|
1868
|
+
change: {
|
|
1869
|
+
type: "object",
|
|
1870
|
+
additionalProperties: false,
|
|
1871
|
+
description:
|
|
1872
|
+
"Exactly one correction. The selected type determines which matching value field is required.",
|
|
1873
|
+
properties: {
|
|
1874
|
+
type: {
|
|
1875
|
+
type: "string",
|
|
1876
|
+
enum: ["category", "businessPurpose", "attendees"],
|
|
1877
|
+
},
|
|
1878
|
+
category: { type: "string" },
|
|
1879
|
+
businessPurpose: { type: "string" },
|
|
1880
|
+
attendees: {
|
|
1881
|
+
type: "array",
|
|
1882
|
+
minItems: 1,
|
|
1883
|
+
maxItems: 25,
|
|
1884
|
+
items: { type: "string" },
|
|
1885
|
+
},
|
|
1886
|
+
attendeeMode: {
|
|
1887
|
+
type: "string",
|
|
1888
|
+
enum: ["add", "replace"],
|
|
1889
|
+
description:
|
|
1890
|
+
"Use add unless the user explicitly asks to replace existing attendees.",
|
|
1891
|
+
},
|
|
1892
|
+
},
|
|
1893
|
+
required: ["type"],
|
|
1894
|
+
},
|
|
1895
|
+
selection: {
|
|
1896
|
+
type: "object",
|
|
1897
|
+
additionalProperties: false,
|
|
1898
|
+
properties: {
|
|
1899
|
+
items: {
|
|
1900
|
+
type: "array",
|
|
1901
|
+
minItems: 1,
|
|
1902
|
+
maxItems: 100,
|
|
1903
|
+
items: {
|
|
1904
|
+
type: "object",
|
|
1905
|
+
additionalProperties: false,
|
|
1906
|
+
properties: {
|
|
1907
|
+
receiptId: {
|
|
1908
|
+
type: "string",
|
|
1909
|
+
description:
|
|
1910
|
+
"Exact full expenseId/Column-Q receipt identity from search_expenses.",
|
|
1911
|
+
},
|
|
1912
|
+
expected: {
|
|
1913
|
+
type: "object",
|
|
1914
|
+
additionalProperties: false,
|
|
1915
|
+
description:
|
|
1916
|
+
"Optional optimistic-concurrency values copied from the search result.",
|
|
1917
|
+
properties: {
|
|
1918
|
+
category: { type: "string" },
|
|
1919
|
+
notes: { type: "string" },
|
|
1920
|
+
},
|
|
1921
|
+
},
|
|
1922
|
+
},
|
|
1923
|
+
required: ["receiptId"],
|
|
1924
|
+
},
|
|
1925
|
+
},
|
|
1926
|
+
},
|
|
1927
|
+
required: ["items"],
|
|
1928
|
+
},
|
|
1929
|
+
operationId: {
|
|
1930
|
+
type: "string",
|
|
1931
|
+
pattern: "^expense-bulk:[a-zA-Z0-9_-]{8,100}$",
|
|
1932
|
+
description:
|
|
1933
|
+
"Stable idempotency key generated once for preview and reused unchanged.",
|
|
1934
|
+
},
|
|
1935
|
+
confirm: {
|
|
1936
|
+
type: "boolean",
|
|
1937
|
+
description: "Omit/false for preview; true only after explicit approval.",
|
|
1938
|
+
},
|
|
1939
|
+
status: {
|
|
1940
|
+
type: "boolean",
|
|
1941
|
+
description: "Read operation status using operationId.",
|
|
1942
|
+
},
|
|
1943
|
+
undo: {
|
|
1944
|
+
type: "boolean",
|
|
1945
|
+
description: "Undo a completed correction within its Undo window.",
|
|
1946
|
+
},
|
|
1947
|
+
},
|
|
1948
|
+
required: ["operationId"],
|
|
1949
|
+
},
|
|
1950
|
+
},
|
|
1568
1951
|
];
|
|
1569
1952
|
|
|
1570
1953
|
// Tools available without authentication (onboarding mode)
|
|
@@ -1657,6 +2040,7 @@ async function handleTool(name, args) {
|
|
|
1657
2040
|
return formatResult(
|
|
1658
2041
|
await client.execute("help_compliance", {
|
|
1659
2042
|
reportId: args.reportId,
|
|
2043
|
+
userRequest: args.userRequest,
|
|
1660
2044
|
})
|
|
1661
2045
|
);
|
|
1662
2046
|
|
|
@@ -1745,6 +2129,14 @@ async function handleTool(name, args) {
|
|
|
1745
2129
|
case "add_income":
|
|
1746
2130
|
return formatResult(await client.execute("add_income", args));
|
|
1747
2131
|
|
|
2132
|
+
// Two-phase income import (v-next) — pass-through; the backend owns the
|
|
2133
|
+
// parse -> durable preview -> confirm -> chunked canonical write contract.
|
|
2134
|
+
case "add_income_from_file":
|
|
2135
|
+
return formatResult(await client.execute("add_income_from_file", args));
|
|
2136
|
+
|
|
2137
|
+
case "add_income_from_csv":
|
|
2138
|
+
return formatResult(await client.execute("add_income_from_csv", args));
|
|
2139
|
+
|
|
1748
2140
|
case "list_categories":
|
|
1749
2141
|
return formatResult(await client.execute("list_categories", {}));
|
|
1750
2142
|
|
|
@@ -2004,6 +2396,21 @@ async function handleTool(name, args) {
|
|
|
2004
2396
|
approveNewGroup: args.approveNewGroup,
|
|
2005
2397
|
createReport: args.createReport,
|
|
2006
2398
|
reportTitle: args.reportTitle,
|
|
2399
|
+
excludePersonal: args.excludePersonal,
|
|
2400
|
+
excludedTags: args.excludedTags,
|
|
2401
|
+
excludedCategories: args.excludedCategories,
|
|
2402
|
+
status: args.status,
|
|
2403
|
+
undo: args.undo,
|
|
2404
|
+
})
|
|
2405
|
+
);
|
|
2406
|
+
|
|
2407
|
+
case "correct_expenses":
|
|
2408
|
+
return formatResult(
|
|
2409
|
+
await client.execute("correct_expenses", {
|
|
2410
|
+
change: args.change,
|
|
2411
|
+
selection: args.selection,
|
|
2412
|
+
operationId: args.operationId,
|
|
2413
|
+
confirm: args.confirm,
|
|
2007
2414
|
status: args.status,
|
|
2008
2415
|
undo: args.undo,
|
|
2009
2416
|
})
|
|
@@ -2047,6 +2454,16 @@ function formatResult(result) {
|
|
|
2047
2454
|
return { content: [{ type: "text", text: errText }], isError: true };
|
|
2048
2455
|
}
|
|
2049
2456
|
|
|
2457
|
+
// Terminal write results already contain the exact user-facing closeout.
|
|
2458
|
+
// Returning only that text keeps stdio aligned with remote and prevents a
|
|
2459
|
+
// model from reopening settled scope using raw report projections.
|
|
2460
|
+
if (typeof result?.finalAnswer === "string" && result.finalAnswer.trim()) {
|
|
2461
|
+
return {
|
|
2462
|
+
content: [{ type: "text", text: result.finalAnswer.trim() }],
|
|
2463
|
+
isError: false,
|
|
2464
|
+
};
|
|
2465
|
+
}
|
|
2466
|
+
|
|
2050
2467
|
// Extract the meaningful content
|
|
2051
2468
|
let text;
|
|
2052
2469
|
if (result?.message && typeof result.message === "string") {
|
|
@@ -2106,7 +2523,7 @@ function formatResult(result) {
|
|
|
2106
2523
|
|
|
2107
2524
|
async function main() {
|
|
2108
2525
|
const server = new Server(
|
|
2109
|
-
{ name: "expensebot-auth", version: "0.6.
|
|
2526
|
+
{ name: "expensebot-auth", version: "0.6.17" },
|
|
2110
2527
|
{ capabilities: { tools: {} }, instructions: SERVER_INSTRUCTIONS }
|
|
2111
2528
|
);
|
|
2112
2529
|
|
package/src/test.js
CHANGED
|
@@ -15,6 +15,7 @@
|
|
|
15
15
|
*/
|
|
16
16
|
|
|
17
17
|
import { spawn } from "node:child_process";
|
|
18
|
+
import { readFileSync } from "node:fs";
|
|
18
19
|
import { fileURLToPath } from "node:url";
|
|
19
20
|
import path from "node:path";
|
|
20
21
|
import { readStructuredHttpError } from "./client.js";
|
|
@@ -22,7 +23,7 @@ import { readStructuredHttpError } from "./client.js";
|
|
|
22
23
|
const __dirname = path.dirname(fileURLToPath(import.meta.url));
|
|
23
24
|
const SERVER_PATH = path.join(__dirname, "index.js");
|
|
24
25
|
|
|
25
|
-
const EXPECTED_TOOL_COUNT =
|
|
26
|
+
const EXPECTED_TOOL_COUNT = 50;
|
|
26
27
|
const REQUIRED_TOOLS = [
|
|
27
28
|
// v0.5.x
|
|
28
29
|
"search_expenses",
|
|
@@ -52,6 +53,7 @@ const REQUIRED_TOOLS = [
|
|
|
52
53
|
"get_scan_status",
|
|
53
54
|
"update_expense",
|
|
54
55
|
"group_expenses",
|
|
56
|
+
"correct_expenses",
|
|
55
57
|
// Phase 4B — read-only surfaces for shipped product data
|
|
56
58
|
"list_client_invoices",
|
|
57
59
|
"get_expense_splits",
|
|
@@ -165,6 +167,12 @@ function check(label, ok, details = "") {
|
|
|
165
167
|
|
|
166
168
|
(async () => {
|
|
167
169
|
console.log("=== mcp-server-auth smoke test ===\n");
|
|
170
|
+
const serverSource = readFileSync(SERVER_PATH, "utf8");
|
|
171
|
+
check(
|
|
172
|
+
"stdio formatter emits terminal finalAnswer without raw-data append",
|
|
173
|
+
/if \(typeof result\?\.finalAnswer === "string"/.test(serverSource) &&
|
|
174
|
+
/text: result\.finalAnswer\.trim\(\)/.test(serverSource)
|
|
175
|
+
);
|
|
168
176
|
const structuredFailure = await readStructuredHttpError(
|
|
169
177
|
new Response(
|
|
170
178
|
JSON.stringify({
|
|
@@ -194,6 +202,28 @@ function check(label, ok, details = "") {
|
|
|
194
202
|
/search_knowledge/.test(instructions) &&
|
|
195
203
|
/fullAnswer:true/.test(instructions)
|
|
196
204
|
);
|
|
205
|
+
check(
|
|
206
|
+
"initialize instructions keep approved workflows concise",
|
|
207
|
+
/one clear yes\/no confirmation/i.test(instructions) &&
|
|
208
|
+
/complete every approved step/i.test(instructions) &&
|
|
209
|
+
/unsolicited tax/i.test(instructions) &&
|
|
210
|
+
/NOT a request for compliance/i.test(instructions)
|
|
211
|
+
);
|
|
212
|
+
check(
|
|
213
|
+
"initialize instructions preserve authoritative tool outcomes",
|
|
214
|
+
/never recompute/i.test(instructions) &&
|
|
215
|
+
/without reopening/i.test(instructions) &&
|
|
216
|
+
/unrequested advice/i.test(instructions) &&
|
|
217
|
+
/terminal write result supersedes intermediate search/i.test(instructions) &&
|
|
218
|
+
/excluded near-matches/i.test(instructions) &&
|
|
219
|
+
/return it verbatim and add nothing else/i.test(instructions)
|
|
220
|
+
);
|
|
221
|
+
check(
|
|
222
|
+
"initialize instructions preserve report provenance",
|
|
223
|
+
/creationStatus=created_this_call/.test(instructions) &&
|
|
224
|
+
/list_reports are pre-existing/i.test(instructions) &&
|
|
225
|
+
/never created or generated/i.test(instructions)
|
|
226
|
+
);
|
|
197
227
|
|
|
198
228
|
// 1. tools/list shape
|
|
199
229
|
const listResp = byId.get(2);
|
|
@@ -204,6 +234,20 @@ function check(label, ok, details = "") {
|
|
|
204
234
|
`(got ${typeof tools})`
|
|
205
235
|
);
|
|
206
236
|
if (Array.isArray(tools)) {
|
|
237
|
+
const complianceTool = tools.find((tool) => tool.name === "check_compliance");
|
|
238
|
+
const reportDetailsTool = tools.find((tool) => tool.name === "get_report_details");
|
|
239
|
+
check(
|
|
240
|
+
"compliance and report-detail tools are explicit opt-in",
|
|
241
|
+
/only when the user explicitly asks/i.test(complianceTool?.description || "") &&
|
|
242
|
+
/billing a client is not a compliance request/i.test(
|
|
243
|
+
complianceTool?.description || ""
|
|
244
|
+
) &&
|
|
245
|
+
complianceTool?.inputSchema?.required?.includes("userRequest") &&
|
|
246
|
+
/only when the user explicitly asks/i.test(
|
|
247
|
+
reportDetailsTool?.description || ""
|
|
248
|
+
) &&
|
|
249
|
+
reportDetailsTool?.inputSchema?.required?.includes("userRequest")
|
|
250
|
+
);
|
|
207
251
|
check(
|
|
208
252
|
`tools/list count = ${EXPECTED_TOOL_COUNT}`,
|
|
209
253
|
tools.length === EXPECTED_TOOL_COUNT,
|
|
@@ -223,6 +267,19 @@ function check(label, ok, details = "") {
|
|
|
223
267
|
noDesc.length === 0,
|
|
224
268
|
noDesc.length ? `missing on: ${noDesc.map((t) => t.name).join(", ")}` : ""
|
|
225
269
|
);
|
|
270
|
+
const fileParamContracts = {
|
|
271
|
+
submit_receipt: "photo",
|
|
272
|
+
add_income_from_file: "photo",
|
|
273
|
+
add_income_from_csv: "csvContent",
|
|
274
|
+
};
|
|
275
|
+
check(
|
|
276
|
+
"binary/text attachment tools advertise OpenAI file parameters",
|
|
277
|
+
Object.entries(fileParamContracts).every(([name, field]) =>
|
|
278
|
+
tools
|
|
279
|
+
.find((tool) => tool.name === name)
|
|
280
|
+
?._meta?.["openai/fileParams"]?.includes(field)
|
|
281
|
+
)
|
|
282
|
+
);
|
|
226
283
|
const updateExpense = tools.find((tool) => tool.name === "update_expense");
|
|
227
284
|
check(
|
|
228
285
|
"update_expense requires exact Column-Q expenseId and exposes no rowNumber",
|
|
@@ -238,6 +295,17 @@ function check(label, ok, details = "") {
|
|
|
238
295
|
updateExpense?.inputSchema?.properties?.expenseId?.description || ""
|
|
239
296
|
)
|
|
240
297
|
);
|
|
298
|
+
const addCashExpense = tools.find((tool) => tool.name === "add_cash_expense");
|
|
299
|
+
check(
|
|
300
|
+
"add_cash_expense exposes canonical client-advance intake",
|
|
301
|
+
addCashExpense?.inputSchema?.properties?.isClientAdvance?.type ===
|
|
302
|
+
"boolean" &&
|
|
303
|
+
addCashExpense?.inputSchema?.properties?.clientName?.type === "string" &&
|
|
304
|
+
!addCashExpense?.inputSchema?.required?.includes("merchant") &&
|
|
305
|
+
!addCashExpense?.inputSchema?.required?.includes("category") &&
|
|
306
|
+
/negative expense/i.test(addCashExpense?.description || "") &&
|
|
307
|
+
/never for vendor refunds/i.test(addCashExpense?.description || "")
|
|
308
|
+
);
|
|
241
309
|
const searchExpenses = tools.find((tool) => tool.name === "search_expenses");
|
|
242
310
|
check(
|
|
243
311
|
"search_expenses exposes opaque cursor pagination",
|
|
@@ -263,6 +331,34 @@ function check(label, ok, details = "") {
|
|
|
263
331
|
createReport?.description || ""
|
|
264
332
|
)
|
|
265
333
|
);
|
|
334
|
+
const groupExpenses = tools.find((tool) => tool.name === "group_expenses");
|
|
335
|
+
check(
|
|
336
|
+
"group_expenses makes preview automatic before every bulk write",
|
|
337
|
+
groupExpenses?.inputSchema?.properties?.confirm?.type === "boolean" &&
|
|
338
|
+
groupExpenses?.inputSchema?.properties?.excludePersonal?.type ===
|
|
339
|
+
"boolean" &&
|
|
340
|
+
groupExpenses?.inputSchema?.properties?.excludedTags?.items?.type ===
|
|
341
|
+
"string" &&
|
|
342
|
+
/preview is automatic/i.test(groupExpenses?.description || "") &&
|
|
343
|
+
/premature confirm:true is converted to preview/i.test(
|
|
344
|
+
groupExpenses?.description || ""
|
|
345
|
+
)
|
|
346
|
+
);
|
|
347
|
+
const correctExpenses = tools.find(
|
|
348
|
+
(tool) => tool.name === "correct_expenses"
|
|
349
|
+
);
|
|
350
|
+
check(
|
|
351
|
+
"correct_expenses is exact, bounded, typed, and reversible",
|
|
352
|
+
correctExpenses?.inputSchema?.properties?.selection?.properties?.items
|
|
353
|
+
?.maxItems === 100 &&
|
|
354
|
+
correctExpenses?.inputSchema?.properties?.change?.properties?.attendees
|
|
355
|
+
?.maxItems === 25 &&
|
|
356
|
+
correctExpenses?.inputSchema?.properties?.change?.properties?.attendeeMode
|
|
357
|
+
?.enum?.includes("replace") &&
|
|
358
|
+
/preview is automatic/i.test(correctExpenses?.description || "") &&
|
|
359
|
+
/supports Undo/i.test(correctExpenses?.description || "") &&
|
|
360
|
+
/does not omit duplicates/i.test(correctExpenses?.description || "")
|
|
361
|
+
);
|
|
266
362
|
const searchKnowledge = tools.find((tool) => tool.name === "search_knowledge");
|
|
267
363
|
check(
|
|
268
364
|
"search_knowledge exposes bounded full-answer retrieval",
|
|
@@ -1,10 +0,0 @@
|
|
|
1
|
-
{
|
|
2
|
-
"_meta": {
|
|
3
|
-
"generatedAt": "2026-05-07T05:13:24.014Z",
|
|
4
|
-
"sourceKb": "../server/config/kb/entries/income-and-pnl-analytics.md",
|
|
5
|
-
"note": "Auto-generated from KB. Do NOT edit by hand — re-run `npm run gen-descriptions` after the KB changes."
|
|
6
|
-
},
|
|
7
|
-
"get_income_summary": "Get income totals and breakdowns from the Income tab — Schedule C / T2125 basis. Excludes Schedule B (interest, dividends), tax refunds, and security deposits (mirrors year-end report routing). Examples: \"How much income YTD?\", \"Income by source\", \"by month\", \"by payment method\".",
|
|
8
|
-
"get_pnl": "Compute Profit & Loss across the Income tab and expenses. Examples: \"Am I profitable this year?\", \"Net income last quarter\", \"What's my margin?\", \"P&L for Q1\".",
|
|
9
|
-
"get_per_tag_pnl": "Per-tag P&L — revenue, cost, profit, and margin grouped by tag. Requires both income AND expense rows to be tagged consistently. Examples: ."
|
|
10
|
-
}
|