@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 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
- **47 tools** across:
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`, `add_mileage_entry`, `add_income`, `parse_expense`, `get_expense_by_id`, `update_expense`, `group_expenses`, `get_spreadsheet_url`
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.12",
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.12",
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 Business " +
173
- "purpose), Tag, and category. Each matching result includes " +
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 Business purpose, " +
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. Can optionally share " +
275
- "with recipients.",
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
- "Check an expense report for compliance issues (missing business " +
361
- "purpose, policy violations, etc.).",
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 (cash purchase, tip, etc.). " +
625
- "Writes directly to the user's expense spreadsheet. Call list_categories " +
626
- "first and choose one of the user's configured Expense Accounts. A unique " +
627
- "account-label alias may be canonicalized, but unknown or ambiguous categories are rejected.",
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: { type: "string", description: "Merchant/vendor name" },
632
- total: { type: "number", description: "Total amount" },
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: ["merchant", "total", "date", "category"],
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. First call with confirm omitted/false for a grounded " +
1467
- "preview; after explicit user approval, repeat the same operationId and selection with confirm:true. " +
1468
- "The confirmed operation can create a report and returns exact report and Bill Client links. " +
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.12" },
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 = 47; // + conversational client/project grouping
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
- }