@expensebot/mcp-server-auth 0.6.12 → 0.6.16
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 +2 -2
- package/package.json +1 -1
- package/src/client.js +1 -1
- package/src/index.js +324 -22
- package/src/test.js +85 -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
|
+
**49 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`, `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`
|
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.16",
|
|
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.16",
|
|
50
50
|
"X-ExpenseBot-MCP-Transport": "stdio",
|
|
51
51
|
...options.headers,
|
|
52
52
|
},
|
package/src/index.js
CHANGED
|
@@ -43,6 +43,11 @@ const client = onboardingMode ? null : new ExpenseBotClient(token);
|
|
|
43
43
|
|
|
44
44
|
const SERVER_INSTRUCTIONS = [
|
|
45
45
|
"ExpenseBot tracks the user's business expenses and income in a Google Sheet they own.",
|
|
46
|
+
"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.",
|
|
47
|
+
"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.",
|
|
48
|
+
"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.",
|
|
49
|
+
"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.",
|
|
50
|
+
"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
51
|
"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
52
|
"After another expense submission, show the returned spreadsheetUrl and reviewExpensesUrl.",
|
|
48
53
|
"For income writes, show spreadsheetUrl and reviewIncomeUrl.",
|
|
@@ -169,8 +174,9 @@ const TOOLS = [
|
|
|
169
174
|
"again with nextCursor and the same filters. Do not split a date " +
|
|
170
175
|
"range into repeated overlapping searches.\n\n" +
|
|
171
176
|
"Use the optional query parameter for deterministic natural-language " +
|
|
172
|
-
"recall over merchant, city/location, Notes (including
|
|
173
|
-
"purpose), Tag, and category.
|
|
177
|
+
"recall over merchant, city/location, Notes (including receipt items, " +
|
|
178
|
+
"delivery source, payer, and Business purpose), Tag, and category. " +
|
|
179
|
+
"Each matching result includes " +
|
|
174
180
|
"matchedFields and a short matchReason so you can explain why it " +
|
|
175
181
|
"was selected. When several rows plausibly match, a disambiguation " +
|
|
176
182
|
"list is returned; each option carries the exact expenseId. " +
|
|
@@ -186,7 +192,8 @@ const TOOLS = [
|
|
|
186
192
|
type: "string",
|
|
187
193
|
description:
|
|
188
194
|
"Optional natural-language recall over the user's existing expense " +
|
|
189
|
-
"fields (merchant, city/location, Notes including
|
|
195
|
+
"fields (merchant, city/location, Notes including receipt items, " +
|
|
196
|
+
"delivery source, payer, and Business purpose, " +
|
|
190
197
|
"Tag, category). Deterministic case-insensitive matching — no " +
|
|
191
198
|
"embeddings or model classifiers. Combine with structured filters " +
|
|
192
199
|
"using AND semantics. Examples: 'Tribeca restaurant', 'Bodewell " +
|
|
@@ -206,6 +213,11 @@ const TOOLS = [
|
|
|
206
213
|
minAmount: { type: "number", description: "Minimum expense amount" },
|
|
207
214
|
maxAmount: { type: "number", description: "Maximum expense amount" },
|
|
208
215
|
tags: { type: "array", items: { type: "string" }, description: "Filter by tags" },
|
|
216
|
+
hasReceipt: {
|
|
217
|
+
type: "boolean",
|
|
218
|
+
description:
|
|
219
|
+
"When true, return only expenses with a receipt link. When false, return only expenses without one.",
|
|
220
|
+
},
|
|
209
221
|
limit: { type: "integer", minimum: 1, maximum: 50, description: "Results per page (default 20, maximum 50)", default: 20 },
|
|
210
222
|
cursor: {
|
|
211
223
|
type: "string",
|
|
@@ -271,8 +283,14 @@ const TOOLS = [
|
|
|
271
283
|
"excludes both the Personal tag and Personal expense category, matching " +
|
|
272
284
|
"ExpenseBot's Report Wizard. Returns the report summary, exact report " +
|
|
273
285
|
"link, Bill Client link, applied filters, and a prefilled Report Wizard " +
|
|
274
|
-
"fallback for criteria that need visual review.
|
|
275
|
-
"
|
|
286
|
+
"fallback for criteria that need visual review. Reports scoped to an " +
|
|
287
|
+
"existing client/project/trip group include matching expenses that are " +
|
|
288
|
+
"not already assigned to another ordinary report. Can optionally share " +
|
|
289
|
+
"with recipients. If no unreported matches remain, create no duplicate " +
|
|
290
|
+
"report and explain that the expenses are already in Reports. Complete " +
|
|
291
|
+
"the requested report directly; do not call " +
|
|
292
|
+
"check_compliance, get_report_details, or tax/deductibility tools before " +
|
|
293
|
+
"or after it unless the user explicitly asks for that separate analysis.",
|
|
276
294
|
inputSchema: {
|
|
277
295
|
type: "object",
|
|
278
296
|
properties: {
|
|
@@ -327,14 +345,22 @@ const TOOLS = [
|
|
|
327
345
|
name: "get_report_details",
|
|
328
346
|
description:
|
|
329
347
|
"Get full details of a specific expense report including all expenses, " +
|
|
330
|
-
"totals, and compliance status."
|
|
348
|
+
"totals, and compliance status. Use only when the user explicitly asks " +
|
|
349
|
+
"to inspect an existing report's details. Never call this as a preflight " +
|
|
350
|
+
"or follow-up to creating, sharing, or billing from a report; those tools " +
|
|
351
|
+
"already return the required result and links.",
|
|
331
352
|
inputSchema: {
|
|
332
353
|
type: "object",
|
|
333
354
|
properties: {
|
|
334
355
|
clientEmail: CLIENT_EMAIL_SCHEMA,
|
|
335
356
|
reportId: { type: "string", description: "The report/spreadsheet ID" },
|
|
357
|
+
userRequest: {
|
|
358
|
+
type: "string",
|
|
359
|
+
description:
|
|
360
|
+
"The user's exact request asking to inspect this report. Do not paraphrase or invent diagnostic intent.",
|
|
361
|
+
},
|
|
336
362
|
},
|
|
337
|
-
required: ["reportId"],
|
|
363
|
+
required: ["reportId", "userRequest"],
|
|
338
364
|
},
|
|
339
365
|
},
|
|
340
366
|
{
|
|
@@ -357,14 +383,22 @@ const TOOLS = [
|
|
|
357
383
|
{
|
|
358
384
|
name: "check_compliance",
|
|
359
385
|
description:
|
|
360
|
-
"
|
|
361
|
-
"purpose
|
|
386
|
+
"Use only when the user explicitly asks to check an existing report for " +
|
|
387
|
+
"compliance issues such as missing business purpose or policy violations. " +
|
|
388
|
+
"Creating a report, excluding Personal expenses, sharing a report, or " +
|
|
389
|
+
"billing a client is not a compliance request; never call this tool " +
|
|
390
|
+
"automatically as a preflight or follow-up for those workflows.",
|
|
362
391
|
inputSchema: {
|
|
363
392
|
type: "object",
|
|
364
393
|
properties: {
|
|
365
394
|
reportId: { type: "string", description: "Report ID to check" },
|
|
395
|
+
userRequest: {
|
|
396
|
+
type: "string",
|
|
397
|
+
description:
|
|
398
|
+
"The user's exact request explicitly asking for compliance, policy, audit, substantiation, or business-purpose analysis. Do not paraphrase or invent intent.",
|
|
399
|
+
},
|
|
366
400
|
},
|
|
367
|
-
required: ["reportId"],
|
|
401
|
+
required: ["reportId", "userRequest"],
|
|
368
402
|
},
|
|
369
403
|
},
|
|
370
404
|
{
|
|
@@ -441,6 +475,7 @@ const TOOLS = [
|
|
|
441
475
|
},
|
|
442
476
|
{
|
|
443
477
|
name: "submit_receipt",
|
|
478
|
+
_meta: { "openai/fileParams": ["photo"] },
|
|
444
479
|
description:
|
|
445
480
|
"Submit a photo or PDF of a receipt for processing. Covers requests " +
|
|
446
481
|
"phrased as 'log this', 'log this receipt', 'save this receipt', " +
|
|
@@ -621,15 +656,28 @@ const TOOLS = [
|
|
|
621
656
|
{
|
|
622
657
|
name: "add_cash_expense",
|
|
623
658
|
description:
|
|
624
|
-
"Add an expense without a receipt
|
|
625
|
-
"Writes directly to the user's expense spreadsheet.
|
|
626
|
-
"first and
|
|
627
|
-
"
|
|
659
|
+
"Add an expense without a receipt, or record money a client provided in advance for expenses. " +
|
|
660
|
+
"Writes directly to the user's expense spreadsheet after confirmation. For an ordinary expense, " +
|
|
661
|
+
"call list_categories first and provide a configured Expense Account. For a client advance, set " +
|
|
662
|
+
"isClientAdvance=true and clientName; ExpenseBot reuses or creates the canonical client group, " +
|
|
663
|
+
"applies Cash advance received, and stores the amount as a negative expense. Use this only for " +
|
|
664
|
+
"money supplied by a client before related spending, never for vendor refunds, reimbursements, " +
|
|
665
|
+
"earned fees, retainers, or generic deposits. " +
|
|
666
|
+
"Use the Manual expense link from get_spreadsheet_url instead when the user " +
|
|
667
|
+
"needs a reviewed form for multiple entries, credits/refunds, tax or tip " +
|
|
668
|
+
"breakdowns, per diem, or incomplete details.",
|
|
628
669
|
inputSchema: {
|
|
629
670
|
type: "object",
|
|
630
671
|
properties: {
|
|
631
|
-
merchant: {
|
|
632
|
-
|
|
672
|
+
merchant: {
|
|
673
|
+
type: "string",
|
|
674
|
+
description:
|
|
675
|
+
"Merchant/vendor name for an ordinary expense. Not needed for a client advance; ExpenseBot derives it from clientName.",
|
|
676
|
+
},
|
|
677
|
+
total: {
|
|
678
|
+
type: "number",
|
|
679
|
+
description: "Positive amount paid or received. ExpenseBot stores a client advance as negative.",
|
|
680
|
+
},
|
|
633
681
|
date: {
|
|
634
682
|
type: "string",
|
|
635
683
|
description: "Expense date (YYYY-MM-DD)",
|
|
@@ -646,8 +694,18 @@ const TOOLS = [
|
|
|
646
694
|
currency: { type: "string", description: "Currency code (default: USD)" },
|
|
647
695
|
city: { type: "string", description: "City/location" },
|
|
648
696
|
notes: { type: "string", description: "Notes or description" },
|
|
697
|
+
isClientAdvance: {
|
|
698
|
+
type: "boolean",
|
|
699
|
+
description:
|
|
700
|
+
"True only when a client supplied money in advance for expenses. Requires clientName and does not require category.",
|
|
701
|
+
},
|
|
702
|
+
clientName: {
|
|
703
|
+
type: "string",
|
|
704
|
+
description:
|
|
705
|
+
"Client name for a client advance, in ordinary language. ExpenseBot resolves the canonical Client – Name group.",
|
|
706
|
+
},
|
|
649
707
|
},
|
|
650
|
-
required: ["
|
|
708
|
+
required: ["total", "date"],
|
|
651
709
|
},
|
|
652
710
|
},
|
|
653
711
|
{
|
|
@@ -751,7 +809,10 @@ const TOOLS = [
|
|
|
751
809
|
"consultants, contractors, and anyone who drives for work. Requires " +
|
|
752
810
|
"the user to have configured their mileage rate (cents/km or cents/mi) " +
|
|
753
811
|
"and unit (mi/km) in ExpenseBot Settings. The trip writes a row to " +
|
|
754
|
-
"their expense spreadsheet with the calculated dollar value."
|
|
812
|
+
"their expense spreadsheet with the calculated dollar value. Use the " +
|
|
813
|
+
"Mileage and travel link from get_spreadsheet_url instead when the user " +
|
|
814
|
+
"needs Google Maps route calculation, mileage settings, repeated trips, " +
|
|
815
|
+
"calendar/rideshare import, per diem, or visual review.",
|
|
755
816
|
inputSchema: {
|
|
756
817
|
type: "object",
|
|
757
818
|
properties: {
|
|
@@ -831,6 +892,191 @@ const TOOLS = [
|
|
|
831
892
|
required: ["amount", "source", "paymentMethod"],
|
|
832
893
|
},
|
|
833
894
|
},
|
|
895
|
+
{
|
|
896
|
+
name: "add_income_from_file",
|
|
897
|
+
_meta: { "openai/fileParams": ["photo"] },
|
|
898
|
+
description:
|
|
899
|
+
"Import income from an attached screenshot, image (JPEG, PNG, WebP, HEIC/HEIF), or PDF " +
|
|
900
|
+
"(payment screenshots, wallet apps, payout or bank statements; max 10 MB). This is a " +
|
|
901
|
+
"two-step tool. STEP 1: call it with the file and WITHOUT confirm — ExpenseBot parses the " +
|
|
902
|
+
"file with the same importer as the app's Add Income screen, checks every row against the " +
|
|
903
|
+
"user's Income tab for duplicates, and returns a preview with a previewId, exact row count, " +
|
|
904
|
+
"totals by currency, per-row details, duplicate flags, and any rejected rows. NOTHING is " +
|
|
905
|
+
"saved in step 1; treat the attachment as consent to parse, not consent to write. Show the " +
|
|
906
|
+
"user the parsed rows and duplicates, then STEP 2: call again with confirm: true and the " +
|
|
907
|
+
"previewId to write exactly those rows. Only include user-approved changes in step 2 " +
|
|
908
|
+
"(selectedIndexes, keepBothIndexes, rowEdits, tag, bulkNote). Flagged duplicates are skipped " +
|
|
909
|
+
"unless the user explicitly asks to keep them (keepBothIndexes). The preview expires after " +
|
|
910
|
+
"15 minutes; an expired or unknown previewId never writes. After a successful confirm, show " +
|
|
911
|
+
"the returned spreadsheetUrl and reviewIncomeUrl. For a visually complex review (mixed " +
|
|
912
|
+
"income/expense rows, many edits), send the user to the Add Income app link returned by " +
|
|
913
|
+
"get_spreadsheet_url instead.",
|
|
914
|
+
inputSchema: {
|
|
915
|
+
type: "object",
|
|
916
|
+
properties: {
|
|
917
|
+
photo: {
|
|
918
|
+
type: "string",
|
|
919
|
+
description:
|
|
920
|
+
"Base64-encoded image/PDF bytes (step 1). On ChatGPT you may pass the attached file " +
|
|
921
|
+
"reference object directly; the server fetches the bytes.",
|
|
922
|
+
},
|
|
923
|
+
mimeType: {
|
|
924
|
+
type: "string",
|
|
925
|
+
enum: [
|
|
926
|
+
"image/jpeg",
|
|
927
|
+
"image/png",
|
|
928
|
+
"image/webp",
|
|
929
|
+
"image/heic",
|
|
930
|
+
"image/heif",
|
|
931
|
+
"application/pdf",
|
|
932
|
+
],
|
|
933
|
+
description: "MIME type of the file (default: image/jpeg)",
|
|
934
|
+
},
|
|
935
|
+
paymentMethod: {
|
|
936
|
+
type: "string",
|
|
937
|
+
description:
|
|
938
|
+
"Fallback payment rail for rows where the parser found none (Cash, Check, " +
|
|
939
|
+
"Bank transfer, Wallet app, Credit/Debit card, Payment processor, or Other).",
|
|
940
|
+
},
|
|
941
|
+
tag: {
|
|
942
|
+
type: "string",
|
|
943
|
+
description:
|
|
944
|
+
"Optional client/project tag. In step 1 it pre-fills the staged rows; in step 2 it " +
|
|
945
|
+
"applies to the confirmed selection.",
|
|
946
|
+
},
|
|
947
|
+
confirm: {
|
|
948
|
+
type: "boolean",
|
|
949
|
+
description:
|
|
950
|
+
"Step 2 only: true writes the staged rows. Omit it (with previewId absent) to parse " +
|
|
951
|
+
"and preview without writing.",
|
|
952
|
+
},
|
|
953
|
+
previewId: {
|
|
954
|
+
type: "string",
|
|
955
|
+
description: "Step 2 only: the previewId returned by the step-1 call.",
|
|
956
|
+
},
|
|
957
|
+
selectedIndexes: {
|
|
958
|
+
type: "array",
|
|
959
|
+
items: { type: "integer" },
|
|
960
|
+
description:
|
|
961
|
+
"Step 2 only: preview row indexes to write. Omit to write all staged rows.",
|
|
962
|
+
},
|
|
963
|
+
keepBothIndexes: {
|
|
964
|
+
type: "array",
|
|
965
|
+
items: { type: "integer" },
|
|
966
|
+
description:
|
|
967
|
+
"Step 2 only: preview indexes of duplicate-flagged rows the user explicitly wants to " +
|
|
968
|
+
"keep anyway (the app's 'Keep Both').",
|
|
969
|
+
},
|
|
970
|
+
rowEdits: {
|
|
971
|
+
type: "array",
|
|
972
|
+
description:
|
|
973
|
+
"Step 2 only: user-approved corrections, at most 50 rows. Fields: date (ISO " +
|
|
974
|
+
"YYYY-MM-DD), source, amount, currency, category, paymentMethod, description, notes, " +
|
|
975
|
+
"reference, fees, taxCollected, tag.",
|
|
976
|
+
items: {
|
|
977
|
+
type: "object",
|
|
978
|
+
properties: {
|
|
979
|
+
index: { type: "integer", description: "Preview row index" },
|
|
980
|
+
fields: { type: "object", additionalProperties: true },
|
|
981
|
+
},
|
|
982
|
+
required: ["index", "fields"],
|
|
983
|
+
},
|
|
984
|
+
},
|
|
985
|
+
bulkNote: {
|
|
986
|
+
type: "string",
|
|
987
|
+
description:
|
|
988
|
+
"Step 2 only: one note (max 120 chars) prepended to every confirmed row's Notes, " +
|
|
989
|
+
"same as the app's 'Add note to all entries'.",
|
|
990
|
+
},
|
|
991
|
+
},
|
|
992
|
+
required: [],
|
|
993
|
+
},
|
|
994
|
+
},
|
|
995
|
+
{
|
|
996
|
+
name: "add_income_from_csv",
|
|
997
|
+
_meta: { "openai/fileParams": ["csvContent"] },
|
|
998
|
+
description:
|
|
999
|
+
"Import income from a CSV/TSV/text export (Stripe, PayPal, Square, Cash App, Venmo, " +
|
|
1000
|
+
"OnlyFans, Patreon, Clips4Sale, Ko-fi, Gumroad, Etsy, Uber/Lyft/DoorDash driver exports, " +
|
|
1001
|
+
"bank statements, and similar; max 500 KB). Same two-step contract as " +
|
|
1002
|
+
"add_income_from_file: STEP 1 call with csvContent and WITHOUT confirm parses the file " +
|
|
1003
|
+
"with the same platform-agnostic importer as the app's Add Income screen (platform " +
|
|
1004
|
+
"detection, fee handling, refunds, source aliases, ISO dates) and returns a duplicate-checked " +
|
|
1005
|
+
"preview with a previewId. NOTHING is saved in step 1. Show the user the parsed rows and " +
|
|
1006
|
+
"duplicates, then STEP 2 call again with confirm: true and the previewId to write exactly " +
|
|
1007
|
+
"those rows, optionally with user-approved selectedIndexes, keepBothIndexes, rowEdits, tag, " +
|
|
1008
|
+
"or bulkNote. Flagged duplicates are skipped unless the user explicitly keeps them. The " +
|
|
1009
|
+
"preview expires after 15 minutes and an expired or unknown previewId never writes. After a " +
|
|
1010
|
+
"successful confirm, show the returned spreadsheetUrl and reviewIncomeUrl.",
|
|
1011
|
+
inputSchema: {
|
|
1012
|
+
type: "object",
|
|
1013
|
+
properties: {
|
|
1014
|
+
csvContent: {
|
|
1015
|
+
type: "string",
|
|
1016
|
+
description:
|
|
1017
|
+
"Raw CSV/TSV/text content (step 1). On ChatGPT you may pass the attached file " +
|
|
1018
|
+
"reference object directly; the server fetches and decodes the bytes.",
|
|
1019
|
+
},
|
|
1020
|
+
paymentMethod: {
|
|
1021
|
+
type: "string",
|
|
1022
|
+
description:
|
|
1023
|
+
"Fallback payment rail for rows where the parser found none (Cash, Check, " +
|
|
1024
|
+
"Bank transfer, Wallet app, Credit/Debit card, Payment processor, or Other).",
|
|
1025
|
+
},
|
|
1026
|
+
tag: {
|
|
1027
|
+
type: "string",
|
|
1028
|
+
description:
|
|
1029
|
+
"Optional client/project tag. In step 1 it pre-fills the staged rows; in step 2 it " +
|
|
1030
|
+
"applies to the confirmed selection.",
|
|
1031
|
+
},
|
|
1032
|
+
confirm: {
|
|
1033
|
+
type: "boolean",
|
|
1034
|
+
description:
|
|
1035
|
+
"Step 2 only: true writes the staged rows. Omit it (with previewId absent) to parse " +
|
|
1036
|
+
"and preview without writing.",
|
|
1037
|
+
},
|
|
1038
|
+
previewId: {
|
|
1039
|
+
type: "string",
|
|
1040
|
+
description: "Step 2 only: the previewId returned by the step-1 call.",
|
|
1041
|
+
},
|
|
1042
|
+
selectedIndexes: {
|
|
1043
|
+
type: "array",
|
|
1044
|
+
items: { type: "integer" },
|
|
1045
|
+
description:
|
|
1046
|
+
"Step 2 only: preview row indexes to write. Omit to write all staged rows.",
|
|
1047
|
+
},
|
|
1048
|
+
keepBothIndexes: {
|
|
1049
|
+
type: "array",
|
|
1050
|
+
items: { type: "integer" },
|
|
1051
|
+
description:
|
|
1052
|
+
"Step 2 only: preview indexes of duplicate-flagged rows the user explicitly wants to " +
|
|
1053
|
+
"keep anyway (the app's 'Keep Both').",
|
|
1054
|
+
},
|
|
1055
|
+
rowEdits: {
|
|
1056
|
+
type: "array",
|
|
1057
|
+
description:
|
|
1058
|
+
"Step 2 only: user-approved corrections, at most 50 rows. Fields: date (ISO " +
|
|
1059
|
+
"YYYY-MM-DD), source, amount, currency, category, paymentMethod, description, notes, " +
|
|
1060
|
+
"reference, fees, taxCollected, tag.",
|
|
1061
|
+
items: {
|
|
1062
|
+
type: "object",
|
|
1063
|
+
properties: {
|
|
1064
|
+
index: { type: "integer", description: "Preview row index" },
|
|
1065
|
+
fields: { type: "object", additionalProperties: true },
|
|
1066
|
+
},
|
|
1067
|
+
required: ["index", "fields"],
|
|
1068
|
+
},
|
|
1069
|
+
},
|
|
1070
|
+
bulkNote: {
|
|
1071
|
+
type: "string",
|
|
1072
|
+
description:
|
|
1073
|
+
"Step 2 only: one note (max 120 chars) prepended to every confirmed row's Notes, " +
|
|
1074
|
+
"same as the app's 'Add note to all entries'.",
|
|
1075
|
+
},
|
|
1076
|
+
},
|
|
1077
|
+
required: [],
|
|
1078
|
+
},
|
|
1079
|
+
},
|
|
834
1080
|
{
|
|
835
1081
|
name: "list_categories",
|
|
836
1082
|
description:
|
|
@@ -1155,6 +1401,22 @@ const TOOLS = [
|
|
|
1155
1401
|
"or General Settings link. Category, G/L, and account-code requests use " +
|
|
1156
1402
|
"Category management; client, project, and trip groups use Group " +
|
|
1157
1403
|
"management; questions about what counts as Personal use Personal rules. " +
|
|
1404
|
+
"When the user asks to choose receipt images from Google Photos, use the " +
|
|
1405
|
+
"returned Google Photos link; it opens the existing authenticated picker " +
|
|
1406
|
+
"and handles any required Google consent in ExpenseBot. When they ask " +
|
|
1407
|
+
"where ExpenseBot stores receipt files, return the Drive folder link only " +
|
|
1408
|
+
"when it is available; never invent or request a folder ID. " +
|
|
1409
|
+
"For a complete, unambiguous cash expense or mileage trip, use the direct " +
|
|
1410
|
+
"write tool. Use the returned Manual expense link for multiple entries, " +
|
|
1411
|
+
"credits/refunds, detailed tax/tip entry, per diem, incomplete details, or " +
|
|
1412
|
+
"visual review. Use the Mileage and travel link for route calculation, " +
|
|
1413
|
+
"mileage settings, repeated trips, calendar/rideshare imports, per diem, " +
|
|
1414
|
+
"or visual review. These links open the existing reviewed app forms. " +
|
|
1415
|
+
"When the user wants to import income from a screenshot, PDF, or CSV but " +
|
|
1416
|
+
"no attachment is available in chat (or the review is visually complex), " +
|
|
1417
|
+
"use the returned Import income links — they open the existing Add Income " +
|
|
1418
|
+
"importer, which parses the file and shows every row for review before " +
|
|
1419
|
+
"anything is saved. " +
|
|
1158
1420
|
"Team setup requests use the returned role-aware Team setup handoff: " +
|
|
1159
1421
|
"eligible solo business owners open Add teammates, while existing team " +
|
|
1160
1422
|
"owners and co-admins open License Manager. If the handoff says owner " +
|
|
@@ -1463,9 +1725,13 @@ const TOOLS = [
|
|
|
1463
1725
|
"Examples: 'group my Mexico meals for client Rob', 'put these Vegas expenses under the Vegas project', " +
|
|
1464
1726
|
"or 'group these for client Rob and create a report'. The user does not need to know about tags: " +
|
|
1465
1727
|
"ExpenseBot resolves the requested name against existing groups and proposes creating one only when needed. " +
|
|
1466
|
-
"Use exact expenseId values returned by search_expenses.
|
|
1467
|
-
"
|
|
1468
|
-
"
|
|
1728
|
+
"Use exact expenseId values returned by search_expenses. A grounded preview is automatic for every bulk request; " +
|
|
1729
|
+
"the user does not need to ask for one. First call with confirm omitted/false, show the returned exact rows, count, " +
|
|
1730
|
+
"totals, proposed group, exclusions, and conflicts, then ask for approval. Only after explicit user approval, " +
|
|
1731
|
+
"repeat the same operationId and selection with confirm:true. A premature confirm:true is converted to preview. " +
|
|
1732
|
+
"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. " +
|
|
1733
|
+
"For 'without personal expenses', set excludePersonal:true; ExpenseBot removes Personal-tagged and Personal-category rows before preview so their Personal marker is never overwritten. " +
|
|
1734
|
+
"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. " +
|
|
1469
1735
|
"Sharing remains a separate share_report action with recipient confirmation.",
|
|
1470
1736
|
inputSchema: {
|
|
1471
1737
|
type: "object",
|
|
@@ -1514,6 +1780,20 @@ const TOOLS = [
|
|
|
1514
1780
|
approveNewGroup: { type: "boolean", description: "True only when the preview says a new group is required." },
|
|
1515
1781
|
createReport: { type: "boolean", description: "Create a report from the exact eligible grouped expenses." },
|
|
1516
1782
|
reportTitle: { type: "string" },
|
|
1783
|
+
excludePersonal: {
|
|
1784
|
+
type: "boolean",
|
|
1785
|
+
description: "Exclude Personal-tagged and Personal-category expenses from both grouping and the exact report.",
|
|
1786
|
+
},
|
|
1787
|
+
excludedTags: {
|
|
1788
|
+
type: "array",
|
|
1789
|
+
items: { type: "string" },
|
|
1790
|
+
description: "Existing groups to exclude before preview and grouping.",
|
|
1791
|
+
},
|
|
1792
|
+
excludedCategories: {
|
|
1793
|
+
type: "array",
|
|
1794
|
+
items: { type: "string" },
|
|
1795
|
+
description: "Expense categories to exclude before preview and grouping.",
|
|
1796
|
+
},
|
|
1517
1797
|
status: { type: "boolean", description: "Read operation status using operationId." },
|
|
1518
1798
|
undo: { type: "boolean", description: "Undo a completed grouping within its undo window." },
|
|
1519
1799
|
},
|
|
@@ -1650,6 +1930,7 @@ async function handleTool(name, args) {
|
|
|
1650
1930
|
return formatResult(
|
|
1651
1931
|
await client.execute("help_compliance", {
|
|
1652
1932
|
reportId: args.reportId,
|
|
1933
|
+
userRequest: args.userRequest,
|
|
1653
1934
|
})
|
|
1654
1935
|
);
|
|
1655
1936
|
|
|
@@ -1738,6 +2019,14 @@ async function handleTool(name, args) {
|
|
|
1738
2019
|
case "add_income":
|
|
1739
2020
|
return formatResult(await client.execute("add_income", args));
|
|
1740
2021
|
|
|
2022
|
+
// Two-phase income import (v-next) — pass-through; the backend owns the
|
|
2023
|
+
// parse -> durable preview -> confirm -> chunked canonical write contract.
|
|
2024
|
+
case "add_income_from_file":
|
|
2025
|
+
return formatResult(await client.execute("add_income_from_file", args));
|
|
2026
|
+
|
|
2027
|
+
case "add_income_from_csv":
|
|
2028
|
+
return formatResult(await client.execute("add_income_from_csv", args));
|
|
2029
|
+
|
|
1741
2030
|
case "list_categories":
|
|
1742
2031
|
return formatResult(await client.execute("list_categories", {}));
|
|
1743
2032
|
|
|
@@ -1997,6 +2286,9 @@ async function handleTool(name, args) {
|
|
|
1997
2286
|
approveNewGroup: args.approveNewGroup,
|
|
1998
2287
|
createReport: args.createReport,
|
|
1999
2288
|
reportTitle: args.reportTitle,
|
|
2289
|
+
excludePersonal: args.excludePersonal,
|
|
2290
|
+
excludedTags: args.excludedTags,
|
|
2291
|
+
excludedCategories: args.excludedCategories,
|
|
2000
2292
|
status: args.status,
|
|
2001
2293
|
undo: args.undo,
|
|
2002
2294
|
})
|
|
@@ -2040,6 +2332,16 @@ function formatResult(result) {
|
|
|
2040
2332
|
return { content: [{ type: "text", text: errText }], isError: true };
|
|
2041
2333
|
}
|
|
2042
2334
|
|
|
2335
|
+
// Terminal write results already contain the exact user-facing closeout.
|
|
2336
|
+
// Returning only that text keeps stdio aligned with remote and prevents a
|
|
2337
|
+
// model from reopening settled scope using raw report projections.
|
|
2338
|
+
if (typeof result?.finalAnswer === "string" && result.finalAnswer.trim()) {
|
|
2339
|
+
return {
|
|
2340
|
+
content: [{ type: "text", text: result.finalAnswer.trim() }],
|
|
2341
|
+
isError: false,
|
|
2342
|
+
};
|
|
2343
|
+
}
|
|
2344
|
+
|
|
2043
2345
|
// Extract the meaningful content
|
|
2044
2346
|
let text;
|
|
2045
2347
|
if (result?.message && typeof result.message === "string") {
|
|
@@ -2099,7 +2401,7 @@ function formatResult(result) {
|
|
|
2099
2401
|
|
|
2100
2402
|
async function main() {
|
|
2101
2403
|
const server = new Server(
|
|
2102
|
-
{ name: "expensebot-auth", version: "0.6.
|
|
2404
|
+
{ name: "expensebot-auth", version: "0.6.16" },
|
|
2103
2405
|
{ capabilities: { tools: {} }, instructions: SERVER_INSTRUCTIONS }
|
|
2104
2406
|
);
|
|
2105
2407
|
|
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 = 49; // + two-phase income file/CSV import tools
|
|
26
27
|
const REQUIRED_TOOLS = [
|
|
27
28
|
// v0.5.x
|
|
28
29
|
"search_expenses",
|
|
@@ -165,6 +166,12 @@ function check(label, ok, details = "") {
|
|
|
165
166
|
|
|
166
167
|
(async () => {
|
|
167
168
|
console.log("=== mcp-server-auth smoke test ===\n");
|
|
169
|
+
const serverSource = readFileSync(SERVER_PATH, "utf8");
|
|
170
|
+
check(
|
|
171
|
+
"stdio formatter emits terminal finalAnswer without raw-data append",
|
|
172
|
+
/if \(typeof result\?\.finalAnswer === "string"/.test(serverSource) &&
|
|
173
|
+
/text: result\.finalAnswer\.trim\(\)/.test(serverSource)
|
|
174
|
+
);
|
|
168
175
|
const structuredFailure = await readStructuredHttpError(
|
|
169
176
|
new Response(
|
|
170
177
|
JSON.stringify({
|
|
@@ -194,6 +201,28 @@ function check(label, ok, details = "") {
|
|
|
194
201
|
/search_knowledge/.test(instructions) &&
|
|
195
202
|
/fullAnswer:true/.test(instructions)
|
|
196
203
|
);
|
|
204
|
+
check(
|
|
205
|
+
"initialize instructions keep approved workflows concise",
|
|
206
|
+
/one clear yes\/no confirmation/i.test(instructions) &&
|
|
207
|
+
/complete every approved step/i.test(instructions) &&
|
|
208
|
+
/unsolicited tax/i.test(instructions) &&
|
|
209
|
+
/NOT a request for compliance/i.test(instructions)
|
|
210
|
+
);
|
|
211
|
+
check(
|
|
212
|
+
"initialize instructions preserve authoritative tool outcomes",
|
|
213
|
+
/never recompute/i.test(instructions) &&
|
|
214
|
+
/without reopening/i.test(instructions) &&
|
|
215
|
+
/unrequested advice/i.test(instructions) &&
|
|
216
|
+
/terminal write result supersedes intermediate search/i.test(instructions) &&
|
|
217
|
+
/excluded near-matches/i.test(instructions) &&
|
|
218
|
+
/return it verbatim and add nothing else/i.test(instructions)
|
|
219
|
+
);
|
|
220
|
+
check(
|
|
221
|
+
"initialize instructions preserve report provenance",
|
|
222
|
+
/creationStatus=created_this_call/.test(instructions) &&
|
|
223
|
+
/list_reports are pre-existing/i.test(instructions) &&
|
|
224
|
+
/never created or generated/i.test(instructions)
|
|
225
|
+
);
|
|
197
226
|
|
|
198
227
|
// 1. tools/list shape
|
|
199
228
|
const listResp = byId.get(2);
|
|
@@ -204,6 +233,20 @@ function check(label, ok, details = "") {
|
|
|
204
233
|
`(got ${typeof tools})`
|
|
205
234
|
);
|
|
206
235
|
if (Array.isArray(tools)) {
|
|
236
|
+
const complianceTool = tools.find((tool) => tool.name === "check_compliance");
|
|
237
|
+
const reportDetailsTool = tools.find((tool) => tool.name === "get_report_details");
|
|
238
|
+
check(
|
|
239
|
+
"compliance and report-detail tools are explicit opt-in",
|
|
240
|
+
/only when the user explicitly asks/i.test(complianceTool?.description || "") &&
|
|
241
|
+
/billing a client is not a compliance request/i.test(
|
|
242
|
+
complianceTool?.description || ""
|
|
243
|
+
) &&
|
|
244
|
+
complianceTool?.inputSchema?.required?.includes("userRequest") &&
|
|
245
|
+
/only when the user explicitly asks/i.test(
|
|
246
|
+
reportDetailsTool?.description || ""
|
|
247
|
+
) &&
|
|
248
|
+
reportDetailsTool?.inputSchema?.required?.includes("userRequest")
|
|
249
|
+
);
|
|
207
250
|
check(
|
|
208
251
|
`tools/list count = ${EXPECTED_TOOL_COUNT}`,
|
|
209
252
|
tools.length === EXPECTED_TOOL_COUNT,
|
|
@@ -223,6 +266,19 @@ function check(label, ok, details = "") {
|
|
|
223
266
|
noDesc.length === 0,
|
|
224
267
|
noDesc.length ? `missing on: ${noDesc.map((t) => t.name).join(", ")}` : ""
|
|
225
268
|
);
|
|
269
|
+
const fileParamContracts = {
|
|
270
|
+
submit_receipt: "photo",
|
|
271
|
+
add_income_from_file: "photo",
|
|
272
|
+
add_income_from_csv: "csvContent",
|
|
273
|
+
};
|
|
274
|
+
check(
|
|
275
|
+
"binary/text attachment tools advertise OpenAI file parameters",
|
|
276
|
+
Object.entries(fileParamContracts).every(([name, field]) =>
|
|
277
|
+
tools
|
|
278
|
+
.find((tool) => tool.name === name)
|
|
279
|
+
?._meta?.["openai/fileParams"]?.includes(field)
|
|
280
|
+
)
|
|
281
|
+
);
|
|
226
282
|
const updateExpense = tools.find((tool) => tool.name === "update_expense");
|
|
227
283
|
check(
|
|
228
284
|
"update_expense requires exact Column-Q expenseId and exposes no rowNumber",
|
|
@@ -238,6 +294,17 @@ function check(label, ok, details = "") {
|
|
|
238
294
|
updateExpense?.inputSchema?.properties?.expenseId?.description || ""
|
|
239
295
|
)
|
|
240
296
|
);
|
|
297
|
+
const addCashExpense = tools.find((tool) => tool.name === "add_cash_expense");
|
|
298
|
+
check(
|
|
299
|
+
"add_cash_expense exposes canonical client-advance intake",
|
|
300
|
+
addCashExpense?.inputSchema?.properties?.isClientAdvance?.type ===
|
|
301
|
+
"boolean" &&
|
|
302
|
+
addCashExpense?.inputSchema?.properties?.clientName?.type === "string" &&
|
|
303
|
+
!addCashExpense?.inputSchema?.required?.includes("merchant") &&
|
|
304
|
+
!addCashExpense?.inputSchema?.required?.includes("category") &&
|
|
305
|
+
/negative expense/i.test(addCashExpense?.description || "") &&
|
|
306
|
+
/never for vendor refunds/i.test(addCashExpense?.description || "")
|
|
307
|
+
);
|
|
241
308
|
const searchExpenses = tools.find((tool) => tool.name === "search_expenses");
|
|
242
309
|
check(
|
|
243
310
|
"search_expenses exposes opaque cursor pagination",
|
|
@@ -245,6 +312,10 @@ function check(label, ok, details = "") {
|
|
|
245
312
|
searchExpenses?.inputSchema?.properties?.limit?.maximum === 50 &&
|
|
246
313
|
/nextCursor/.test(searchExpenses?.description || "")
|
|
247
314
|
);
|
|
315
|
+
check(
|
|
316
|
+
"search_expenses exposes the shared receipt-state filter",
|
|
317
|
+
searchExpenses?.inputSchema?.properties?.hasReceipt?.type === "boolean"
|
|
318
|
+
);
|
|
248
319
|
const createReport = tools.find((tool) => tool.name === "create_report");
|
|
249
320
|
check(
|
|
250
321
|
"create_report exposes Report Wizard-compatible exclusions",
|
|
@@ -259,6 +330,19 @@ function check(label, ok, details = "") {
|
|
|
259
330
|
createReport?.description || ""
|
|
260
331
|
)
|
|
261
332
|
);
|
|
333
|
+
const groupExpenses = tools.find((tool) => tool.name === "group_expenses");
|
|
334
|
+
check(
|
|
335
|
+
"group_expenses makes preview automatic before every bulk write",
|
|
336
|
+
groupExpenses?.inputSchema?.properties?.confirm?.type === "boolean" &&
|
|
337
|
+
groupExpenses?.inputSchema?.properties?.excludePersonal?.type ===
|
|
338
|
+
"boolean" &&
|
|
339
|
+
groupExpenses?.inputSchema?.properties?.excludedTags?.items?.type ===
|
|
340
|
+
"string" &&
|
|
341
|
+
/preview is automatic/i.test(groupExpenses?.description || "") &&
|
|
342
|
+
/premature confirm:true is converted to preview/i.test(
|
|
343
|
+
groupExpenses?.description || ""
|
|
344
|
+
)
|
|
345
|
+
);
|
|
262
346
|
const searchKnowledge = tools.find((tool) => tool.name === "search_knowledge");
|
|
263
347
|
check(
|
|
264
348
|
"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
|
-
}
|