@expensebot/mcp-server-auth 0.6.5 → 0.6.7

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
- **44 tools** across:
5
+ **46 tools** across:
6
6
  - **Search & analytics** — `search_expenses`, `get_spending_summary`, `get_deep_analytics`, `list_categories`, `list_tags`, `list_income_categories`, `search_knowledge`
7
7
  - **Income & P&L** *(v0.6.0)* — `get_income_summary`, `get_pnl`, `get_per_tag_pnl`
8
8
  - **Mileage & Subscriptions** *(v0.6.1)* — `get_mileage_summary`, `get_subscription_audit`
9
- - **Receipt capture** — `submit_receipt` (photo/PDF), `add_cash_expense`, `add_mileage_entry`, `add_income`, `parse_expense`, `get_expense_by_id`, `update_expense`
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`, `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.5",
3
+ "version": "0.6.7",
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
@@ -20,7 +20,7 @@ export class ExpenseBotClient {
20
20
  headers: {
21
21
  Authorization: `Bearer ${this.token}`,
22
22
  "Content-Type": "application/json",
23
- "User-Agent": "expensebot-mcp-auth/0.6.5",
23
+ "User-Agent": "expensebot-mcp-auth/0.6.7",
24
24
  "X-ExpenseBot-MCP-Transport": "stdio",
25
25
  ...options.headers,
26
26
  },
package/src/index.js CHANGED
@@ -41,6 +41,15 @@ for (const arg of args) {
41
41
  const onboardingMode = !token;
42
42
  const client = onboardingMode ? null : new ExpenseBotClient(token);
43
43
 
44
+ const SERVER_INSTRUCTIONS = [
45
+ "ExpenseBot tracks the user's business expenses and income in a Google Sheet they own.",
46
+ "After submit_receipt returns a submissionId, call get_last_receipt_result with that exact ID after about 15 seconds; retry every 15 seconds for up to 2 minutes. Report the final added/duplicate/skipped/error counts, then show spreadsheetUrl and reviewExpensesUrl.",
47
+ "After another expense submission, show the returned spreadsheetUrl and reviewExpensesUrl.",
48
+ "For income writes, show spreadsheetUrl and reviewIncomeUrl.",
49
+ "For Gmail scan progress or completion, call get_scan_status. Report its authoritative status and live phase; on completion show spreadsheetUrl and reviewExpensesUrl, and when action is needed show gmailScanUrl.",
50
+ "For product, setup, billing, Gmail, report, workflow, or troubleshooting questions, call search_knowledge instead of guessing. Use fullAnswer:true when complete instructions are needed.",
51
+ ].join("\n");
52
+
44
53
  if (onboardingMode) {
45
54
  console.error(
46
55
  "[expensebot-auth] No token provided — running in ONBOARDING MODE.\n" +
@@ -358,13 +367,28 @@ const TOOLS = [
358
367
  {
359
368
  name: "search_knowledge",
360
369
  description:
361
- "Search the ExpenseBot knowledge base for help articles and " +
362
- "how-to guides. Use when the user asks about ExpenseBot features.",
370
+ "Search ExpenseBot's complete product and help knowledge base. Use this " +
371
+ "before guessing when the user asks how a feature works, what ExpenseBot " +
372
+ "supports, or needs setup, billing, Gmail, scan, report, workflow, or " +
373
+ "troubleshooting instructions. Results are query-ranked; request the full " +
374
+ "answer after identifying the relevant article.",
363
375
  inputSchema: {
364
376
  type: "object",
365
377
  properties: {
366
378
  query: { type: "string", description: "Search terms" },
367
- limit: { type: "integer", default: 5 },
379
+ limit: {
380
+ type: "integer",
381
+ minimum: 1,
382
+ maximum: 10,
383
+ default: 5,
384
+ description: "Number of ranked matching articles to return (1-10).",
385
+ },
386
+ fullAnswer: {
387
+ type: "boolean",
388
+ default: false,
389
+ description:
390
+ "Set true to return complete article answers instead of short excerpts.",
391
+ },
368
392
  },
369
393
  required: ["query"],
370
394
  },
@@ -376,16 +400,88 @@ const TOOLS = [
376
400
  "phrased as 'log this', 'log this receipt', 'save this receipt', " +
377
401
  "'expense this', or 'add this to my expenses', including when the user " +
378
402
  "simply shares a photo of a receipt or invoice. The receipt image " +
379
- "is sent as base64, validated, uploaded to cloud storage, and processed " +
403
+ "is validated, uploaded to cloud storage, and processed " +
380
404
  "by AI to extract vendor, amount, date, tax, and category. The expense " +
381
- "appears in the user's spreadsheet within 30 seconds.",
405
+ "appears in the user's spreadsheet within 30 seconds. Handles images and " +
406
+ "PDFs, mixed together in one batch.\n\n" +
407
+ "TO SEND FILES (preferred, and required for PDFs): call this tool with " +
408
+ "filesToUpload listing every file the user gave you. It returns one " +
409
+ "signed upload URL per file. Upload them ONE AT A TIME with an HTTP PUT, " +
410
+ "telling the user which file you just finished and how many remain, then " +
411
+ "call this tool ONCE with uploadRefs for all of them — that processes " +
412
+ "the whole set as a single batch, like the ExpenseBot web app. Do not " +
413
+ "call this tool once per file.\n\n" +
414
+ "Only use the photo parameter for a single small image whose base64 you " +
415
+ "can reliably include in full — large base64 payloads are frequently " +
416
+ "dropped in transit, which silently loses the receipt.",
382
417
  inputSchema: {
383
418
  type: "object",
384
419
  properties: {
420
+ filesToUpload: {
421
+ type: "array",
422
+ description:
423
+ "Request upload URLs for one or more files. Include EVERY file the " +
424
+ "user provided in a single call. Returns one signedUrl + uploadRef " +
425
+ "per file; upload each, then call this tool again with uploadRefs.",
426
+ items: {
427
+ type: "object",
428
+ properties: {
429
+ id: {
430
+ type: "string",
431
+ description:
432
+ "Your own identifier for this file, echoed back so you can " +
433
+ "match URLs to files. E.g. '1', '2'.",
434
+ },
435
+ filename: {
436
+ type: "string",
437
+ description: "Original filename, e.g. 'lunch.jpg' or 'invoice.pdf'.",
438
+ },
439
+ mimeType: {
440
+ type: "string",
441
+ enum: [
442
+ "image/jpeg",
443
+ "image/png",
444
+ "image/heic",
445
+ "image/heif",
446
+ "image/webp",
447
+ "application/pdf",
448
+ ],
449
+ description:
450
+ "MIME type. Must match the Content-Type header used in the " +
451
+ "PUT exactly. The real format is re-detected from the file's " +
452
+ "contents on submit, so a close guess still works.",
453
+ },
454
+ },
455
+ required: ["filename"],
456
+ },
457
+ },
458
+ uploadRefs: {
459
+ type: "array",
460
+ description:
461
+ "Submit previously uploaded files as ONE batch. Include every " +
462
+ "uploadRef from the filesToUpload step. If any file fails " +
463
+ "validation the whole batch is rejected and nothing is processed.",
464
+ items: {
465
+ type: "object",
466
+ properties: {
467
+ id: { type: "string", description: "The id you supplied in filesToUpload." },
468
+ uploadRef: { type: "string", description: "uploadRef returned for that file." },
469
+ },
470
+ required: ["uploadRef"],
471
+ },
472
+ },
473
+ uploadRef: {
474
+ type: "string",
475
+ description:
476
+ "Single-file shorthand for uploadRefs. Use uploadRefs when there " +
477
+ "is more than one file.",
478
+ },
385
479
  photo: {
386
480
  type: "string",
387
481
  description:
388
- "Base64-encoded image or PDF data (JPEG, PNG, HEIC, WebP, or PDF). Max 15MB.",
482
+ "Base64-encoded image or PDF data (JPEG, PNG, HEIC, WebP, or PDF). " +
483
+ "Max 15MB. Only for small images — large payloads get truncated or " +
484
+ "dropped in transit; use uploadRef instead.",
389
485
  },
390
486
  filename: {
391
487
  type: "string",
@@ -403,7 +499,42 @@ const TOOLS = [
403
499
  description: "MIME type of the file (default: image/jpeg)",
404
500
  },
405
501
  },
406
- required: ["photo"],
502
+ // Neither is individually required: the server accepts uploadRef OR
503
+ // photo and returns a clear 400 naming both when it gets neither.
504
+ // Keeping photo in `required` would reintroduce the original failure --
505
+ // the client rejecting the call locally when a model omits base64, so
506
+ // nothing ever reaches the server and no diagnostic is recorded.
507
+ required: [],
508
+ },
509
+ },
510
+ {
511
+ name: "get_last_receipt_result",
512
+ description:
513
+ "Check the authoritative final outcome of a receipt image/PDF batch submitted " +
514
+ "with submit_receipt. After submit_receipt returns submissionId, wait about " +
515
+ "15 seconds and call this tool with that exact ID; if found is false, retry " +
516
+ "every 15 seconds for up to 2 minutes. Returns added, duplicate, skipped, or " +
517
+ "errored verdicts with exact counts and up to 10 processed receipt summaries. " +
518
+ "On completion, tell the user what happened and show spreadsheetUrl plus " +
519
+ "reviewExpensesUrl. This is for uploaded receipts; use get_scan_status for " +
520
+ "Gmail scans. Read-only.",
521
+ inputSchema: {
522
+ type: "object",
523
+ properties: {
524
+ submissionId: {
525
+ type: "string",
526
+ description:
527
+ "Exact submissionId returned by submit_receipt. Strongly preferred because it binds the result to this upload instead of an earlier receipt.",
528
+ },
529
+ withinSeconds: {
530
+ type: "integer",
531
+ minimum: 30,
532
+ maximum: 3600,
533
+ default: 600,
534
+ description:
535
+ "Fallback lookback window when submissionId is unavailable (30-3600 seconds; default 600).",
536
+ },
537
+ },
407
538
  },
408
539
  },
409
540
  {
@@ -924,6 +1055,22 @@ const TOOLS = [
924
1055
  required: ["reportId"],
925
1056
  },
926
1057
  },
1058
+ {
1059
+ name: "get_spreadsheet_url",
1060
+ description:
1061
+ "Return the user's master ExpenseBot Google Sheet plus authenticated " +
1062
+ "ExpenseBot workspace links, each with a label and a description of when " +
1063
+ "to use it. Use this when the user asks to open, view, check, or edit their " +
1064
+ "spreadsheet; review expenses or income; manually scan Gmail; reconcile; " +
1065
+ "open reports; or asks where a submitted receipt went. Choose and show the " +
1066
+ "one or two links relevant to the request instead of listing the entire " +
1067
+ "catalog. After a receipt submission, prefer Review expenses plus the " +
1068
+ "Google Sheet. After an income write, prefer Review income plus the Sheet. " +
1069
+ "For a Gmail scan or connection request, use the Scan Gmail link, which " +
1070
+ "opens the existing Gmail scanning interface. Read-only; this tool does " +
1071
+ "not create or modify spreadsheet rows.",
1072
+ inputSchema: { type: "object", properties: {} },
1073
+ },
927
1074
  {
928
1075
  name: "get_pricing",
929
1076
  description:
@@ -1076,11 +1223,13 @@ const TOOLS = [
1076
1223
  {
1077
1224
  name: "get_scan_status",
1078
1225
  description:
1079
- "Check the status of the user's Gmail receipt scans: whether a scan " +
1080
- "is running right now, which years are queued for scanning, and " +
1081
- "recent scan history (per inbox, with date range and counts). Call " +
1082
- "this when the user asks how their scan is going or whether a year " +
1083
- "has finished. Read-only.",
1226
+ "Check the authoritative status of the user's Gmail receipt scans. " +
1227
+ "Returns the active scan lock, the same live phase and item progress " +
1228
+ "shown by ExpenseBot's in-app status pill, queued or attention-needed " +
1229
+ "years, and recent outcomes. Call when the user asks whether a scan is " +
1230
+ "running, finished, stuck, or what it is doing. When complete, show the " +
1231
+ "returned spreadsheetUrl or reviewExpensesUrl; when setup or reconnection " +
1232
+ "is needed, show gmailScanUrl. Read-only.",
1084
1233
  inputSchema: { type: "object", properties: {} },
1085
1234
  },
1086
1235
  {
@@ -1233,7 +1382,12 @@ const TOOLS = [
1233
1382
  expenseId: { type: "string", description: "Exact full Receipt ID from Column Q, returned as expenseId by search_expenses." },
1234
1383
  fields: {
1235
1384
  type: "object",
1236
- description: "The fields to change. Only these keys are honored.",
1385
+ description:
1386
+ "Partial update object. Include one or more of these optional keys; " +
1387
+ "omit every field that should remain unchanged.",
1388
+ minProperties: 1,
1389
+ maxProperties: 4,
1390
+ additionalProperties: false,
1237
1391
  properties: {
1238
1392
  category: { type: "string" },
1239
1393
  tag: { type: "string" },
@@ -1378,13 +1532,20 @@ async function handleTool(name, args) {
1378
1532
 
1379
1533
  case "submit_receipt":
1380
1534
  return formatResult(
1381
- await client.execute("submit_receipt", {
1382
- photo: args.photo,
1383
- filename: args.filename,
1384
- mimeType: args.mimeType,
1535
+ await client.execute("submit_receipt", args)
1536
+ );
1537
+
1538
+ case "get_last_receipt_result":
1539
+ return formatResult(
1540
+ await client.execute("get_last_receipt_result", {
1541
+ submissionId: args.submissionId,
1542
+ withinSeconds: args.withinSeconds,
1385
1543
  })
1386
1544
  );
1387
1545
 
1546
+ case "get_spreadsheet_url":
1547
+ return formatResult(await client.execute("get_spreadsheet_url", {}));
1548
+
1388
1549
  case "add_cash_expense":
1389
1550
  return formatResult(
1390
1551
  await client.execute("add_cash_expense", args)
@@ -1743,8 +1904,8 @@ function formatResult(result) {
1743
1904
 
1744
1905
  async function main() {
1745
1906
  const server = new Server(
1746
- { name: "expensebot-auth", version: "0.6.5" },
1747
- { capabilities: { tools: {} } }
1907
+ { name: "expensebot-auth", version: "0.6.7" },
1908
+ { capabilities: { tools: {} }, instructions: SERVER_INSTRUCTIONS }
1748
1909
  );
1749
1910
 
1750
1911
  server.setRequestHandler(ListToolsRequestSchema, async () => ({
package/src/test.js CHANGED
@@ -21,11 +21,12 @@ import path from "node:path";
21
21
  const __dirname = path.dirname(fileURLToPath(import.meta.url));
22
22
  const SERVER_PATH = path.join(__dirname, "index.js");
23
23
 
24
- const EXPECTED_TOOL_COUNT = 44; // 37 + v1.0 Gmail year-scan/edit + Phase 4B reads
24
+ const EXPECTED_TOOL_COUNT = 46; // + receipt completion + direct workspace links
25
25
  const REQUIRED_TOOLS = [
26
26
  // v0.5.x
27
27
  "search_expenses",
28
28
  "submit_receipt",
29
+ "get_last_receipt_result",
29
30
  "scan_gmail",
30
31
  "create_report",
31
32
  // v0.6.0
@@ -41,6 +42,7 @@ const REQUIRED_TOOLS = [
41
42
  // v0.7.0
42
43
  "get_expense_by_id",
43
44
  "export_report",
45
+ "get_spreadsheet_url",
44
46
  "get_pricing",
45
47
  "check_feature",
46
48
  "start_trial_link",
@@ -166,6 +168,15 @@ function check(label, ok, details = "") {
166
168
  responses.filter((r) => r.id != null).map((r) => [r.id, r])
167
169
  );
168
170
 
171
+ const instructions = byId.get(1)?.result?.instructions || "";
172
+ check(
173
+ "initialize instructions cover scan status, result links, and KB retrieval",
174
+ /get_scan_status/.test(instructions) &&
175
+ /reviewExpensesUrl/.test(instructions) &&
176
+ /search_knowledge/.test(instructions) &&
177
+ /fullAnswer:true/.test(instructions)
178
+ );
179
+
169
180
  // 1. tools/list shape
170
181
  const listResp = byId.get(2);
171
182
  const tools = listResp?.result?.tools;
@@ -198,6 +209,9 @@ function check(label, ok, details = "") {
198
209
  check(
199
210
  "update_expense requires exact Column-Q expenseId and exposes no rowNumber",
200
211
  updateExpense?.inputSchema?.required?.includes("expenseId") &&
212
+ updateExpense?.inputSchema?.properties?.fields?.minProperties === 1 &&
213
+ updateExpense?.inputSchema?.properties?.fields?.additionalProperties ===
214
+ false &&
201
215
  !Object.prototype.hasOwnProperty.call(
202
216
  updateExpense?.inputSchema?.properties || {},
203
217
  "rowNumber"
@@ -213,6 +227,28 @@ function check(label, ok, details = "") {
213
227
  searchExpenses?.inputSchema?.properties?.limit?.maximum === 50 &&
214
228
  /nextCursor/.test(searchExpenses?.description || "")
215
229
  );
230
+ const searchKnowledge = tools.find((tool) => tool.name === "search_knowledge");
231
+ check(
232
+ "search_knowledge exposes bounded full-answer retrieval",
233
+ searchKnowledge?.inputSchema?.properties?.fullAnswer?.type === "boolean" &&
234
+ searchKnowledge?.inputSchema?.properties?.limit?.maximum === 10
235
+ );
236
+ const scanStatus = tools.find((tool) => tool.name === "get_scan_status");
237
+ check(
238
+ "get_scan_status describes authoritative live progress and result links",
239
+ /authoritative/.test(scanStatus?.description || "") &&
240
+ /live phase/.test(scanStatus?.description || "") &&
241
+ /reviewExpensesUrl/.test(scanStatus?.description || "")
242
+ );
243
+ const receiptResult = tools.find(
244
+ (tool) => tool.name === "get_last_receipt_result"
245
+ );
246
+ check(
247
+ "get_last_receipt_result binds completion to submit_receipt submissionId",
248
+ receiptResult?.inputSchema?.properties?.submissionId?.type === "string" &&
249
+ /exact ID/.test(receiptResult?.description || "") &&
250
+ /get_scan_status/.test(receiptResult?.description || "")
251
+ );
216
252
  }
217
253
 
218
254
  // 2. get_pricing (id=3) — should succeed in onboarding mode