@expensebot/mcp-server-auth 0.6.13 → 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.13",
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.13",
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.",
@@ -278,8 +283,14 @@ const TOOLS = [
278
283
  "excludes both the Personal tag and Personal expense category, matching " +
279
284
  "ExpenseBot's Report Wizard. Returns the report summary, exact report " +
280
285
  "link, Bill Client link, applied filters, and a prefilled Report Wizard " +
281
- "fallback for criteria that need visual review. Can optionally share " +
282
- "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.",
283
294
  inputSchema: {
284
295
  type: "object",
285
296
  properties: {
@@ -334,14 +345,22 @@ const TOOLS = [
334
345
  name: "get_report_details",
335
346
  description:
336
347
  "Get full details of a specific expense report including all expenses, " +
337
- "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.",
338
352
  inputSchema: {
339
353
  type: "object",
340
354
  properties: {
341
355
  clientEmail: CLIENT_EMAIL_SCHEMA,
342
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
+ },
343
362
  },
344
- required: ["reportId"],
363
+ required: ["reportId", "userRequest"],
345
364
  },
346
365
  },
347
366
  {
@@ -364,14 +383,22 @@ const TOOLS = [
364
383
  {
365
384
  name: "check_compliance",
366
385
  description:
367
- "Check an expense report for compliance issues (missing business " +
368
- "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.",
369
391
  inputSchema: {
370
392
  type: "object",
371
393
  properties: {
372
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
+ },
373
400
  },
374
- required: ["reportId"],
401
+ required: ["reportId", "userRequest"],
375
402
  },
376
403
  },
377
404
  {
@@ -448,6 +475,7 @@ const TOOLS = [
448
475
  },
449
476
  {
450
477
  name: "submit_receipt",
478
+ _meta: { "openai/fileParams": ["photo"] },
451
479
  description:
452
480
  "Submit a photo or PDF of a receipt for processing. Covers requests " +
453
481
  "phrased as 'log this', 'log this receipt', 'save this receipt', " +
@@ -628,15 +656,28 @@ const TOOLS = [
628
656
  {
629
657
  name: "add_cash_expense",
630
658
  description:
631
- "Add an expense without a receipt (cash purchase, tip, etc.). " +
632
- "Writes directly to the user's expense spreadsheet. Call list_categories " +
633
- "first and choose one of the user's configured Expense Accounts. A unique " +
634
- "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.",
635
669
  inputSchema: {
636
670
  type: "object",
637
671
  properties: {
638
- merchant: { type: "string", description: "Merchant/vendor name" },
639
- 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
+ },
640
681
  date: {
641
682
  type: "string",
642
683
  description: "Expense date (YYYY-MM-DD)",
@@ -653,8 +694,18 @@ const TOOLS = [
653
694
  currency: { type: "string", description: "Currency code (default: USD)" },
654
695
  city: { type: "string", description: "City/location" },
655
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
+ },
656
707
  },
657
- required: ["merchant", "total", "date", "category"],
708
+ required: ["total", "date"],
658
709
  },
659
710
  },
660
711
  {
@@ -758,7 +809,10 @@ const TOOLS = [
758
809
  "consultants, contractors, and anyone who drives for work. Requires " +
759
810
  "the user to have configured their mileage rate (cents/km or cents/mi) " +
760
811
  "and unit (mi/km) in ExpenseBot Settings. The trip writes a row to " +
761
- "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.",
762
816
  inputSchema: {
763
817
  type: "object",
764
818
  properties: {
@@ -838,6 +892,191 @@ const TOOLS = [
838
892
  required: ["amount", "source", "paymentMethod"],
839
893
  },
840
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
+ },
841
1080
  {
842
1081
  name: "list_categories",
843
1082
  description:
@@ -1162,6 +1401,22 @@ const TOOLS = [
1162
1401
  "or General Settings link. Category, G/L, and account-code requests use " +
1163
1402
  "Category management; client, project, and trip groups use Group " +
1164
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. " +
1165
1420
  "Team setup requests use the returned role-aware Team setup handoff: " +
1166
1421
  "eligible solo business owners open Add teammates, while existing team " +
1167
1422
  "owners and co-admins open License Manager. If the handoff says owner " +
@@ -1470,9 +1725,13 @@ const TOOLS = [
1470
1725
  "Examples: 'group my Mexico meals for client Rob', 'put these Vegas expenses under the Vegas project', " +
1471
1726
  "or 'group these for client Rob and create a report'. The user does not need to know about tags: " +
1472
1727
  "ExpenseBot resolves the requested name against existing groups and proposes creating one only when needed. " +
1473
- "Use exact expenseId values returned by search_expenses. First call with confirm omitted/false for a grounded " +
1474
- "preview; after explicit user approval, repeat the same operationId and selection with confirm:true. " +
1475
- "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. " +
1476
1735
  "Sharing remains a separate share_report action with recipient confirmation.",
1477
1736
  inputSchema: {
1478
1737
  type: "object",
@@ -1521,6 +1780,20 @@ const TOOLS = [
1521
1780
  approveNewGroup: { type: "boolean", description: "True only when the preview says a new group is required." },
1522
1781
  createReport: { type: "boolean", description: "Create a report from the exact eligible grouped expenses." },
1523
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
+ },
1524
1797
  status: { type: "boolean", description: "Read operation status using operationId." },
1525
1798
  undo: { type: "boolean", description: "Undo a completed grouping within its undo window." },
1526
1799
  },
@@ -1657,6 +1930,7 @@ async function handleTool(name, args) {
1657
1930
  return formatResult(
1658
1931
  await client.execute("help_compliance", {
1659
1932
  reportId: args.reportId,
1933
+ userRequest: args.userRequest,
1660
1934
  })
1661
1935
  );
1662
1936
 
@@ -1745,6 +2019,14 @@ async function handleTool(name, args) {
1745
2019
  case "add_income":
1746
2020
  return formatResult(await client.execute("add_income", args));
1747
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
+
1748
2030
  case "list_categories":
1749
2031
  return formatResult(await client.execute("list_categories", {}));
1750
2032
 
@@ -2004,6 +2286,9 @@ async function handleTool(name, args) {
2004
2286
  approveNewGroup: args.approveNewGroup,
2005
2287
  createReport: args.createReport,
2006
2288
  reportTitle: args.reportTitle,
2289
+ excludePersonal: args.excludePersonal,
2290
+ excludedTags: args.excludedTags,
2291
+ excludedCategories: args.excludedCategories,
2007
2292
  status: args.status,
2008
2293
  undo: args.undo,
2009
2294
  })
@@ -2047,6 +2332,16 @@ function formatResult(result) {
2047
2332
  return { content: [{ type: "text", text: errText }], isError: true };
2048
2333
  }
2049
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
+
2050
2345
  // Extract the meaningful content
2051
2346
  let text;
2052
2347
  if (result?.message && typeof result.message === "string") {
@@ -2106,7 +2401,7 @@ function formatResult(result) {
2106
2401
 
2107
2402
  async function main() {
2108
2403
  const server = new Server(
2109
- { name: "expensebot-auth", version: "0.6.13" },
2404
+ { name: "expensebot-auth", version: "0.6.16" },
2110
2405
  { capabilities: { tools: {} }, instructions: SERVER_INSTRUCTIONS }
2111
2406
  );
2112
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",
@@ -263,6 +330,19 @@ function check(label, ok, details = "") {
263
330
  createReport?.description || ""
264
331
  )
265
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
+ );
266
346
  const searchKnowledge = tools.find((tool) => tool.name === "search_knowledge");
267
347
  check(
268
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
- }