@expensebot/mcp-server-auth 0.6.5 → 0.6.6

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
+ **45 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), `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.6",
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.6",
24
24
  "X-ExpenseBot-MCP-Transport": "stdio",
25
25
  ...options.headers,
26
26
  },
package/src/index.js CHANGED
@@ -41,6 +41,14 @@ 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 a receipt or expense submission, show the returned spreadsheetUrl and reviewExpensesUrl.",
47
+ "For income writes, show spreadsheetUrl and reviewIncomeUrl.",
48
+ "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.",
49
+ "For product, setup, billing, Gmail, report, workflow, or troubleshooting questions, call search_knowledge instead of guessing. Use fullAnswer:true when complete instructions are needed.",
50
+ ].join("\n");
51
+
44
52
  if (onboardingMode) {
45
53
  console.error(
46
54
  "[expensebot-auth] No token provided — running in ONBOARDING MODE.\n" +
@@ -358,13 +366,28 @@ const TOOLS = [
358
366
  {
359
367
  name: "search_knowledge",
360
368
  description:
361
- "Search the ExpenseBot knowledge base for help articles and " +
362
- "how-to guides. Use when the user asks about ExpenseBot features.",
369
+ "Search ExpenseBot's complete product and help knowledge base. Use this " +
370
+ "before guessing when the user asks how a feature works, what ExpenseBot " +
371
+ "supports, or needs setup, billing, Gmail, scan, report, workflow, or " +
372
+ "troubleshooting instructions. Results are query-ranked; request the full " +
373
+ "answer after identifying the relevant article.",
363
374
  inputSchema: {
364
375
  type: "object",
365
376
  properties: {
366
377
  query: { type: "string", description: "Search terms" },
367
- limit: { type: "integer", default: 5 },
378
+ limit: {
379
+ type: "integer",
380
+ minimum: 1,
381
+ maximum: 10,
382
+ default: 5,
383
+ description: "Number of ranked matching articles to return (1-10).",
384
+ },
385
+ fullAnswer: {
386
+ type: "boolean",
387
+ default: false,
388
+ description:
389
+ "Set true to return complete article answers instead of short excerpts.",
390
+ },
368
391
  },
369
392
  required: ["query"],
370
393
  },
@@ -376,16 +399,88 @@ const TOOLS = [
376
399
  "phrased as 'log this', 'log this receipt', 'save this receipt', " +
377
400
  "'expense this', or 'add this to my expenses', including when the user " +
378
401
  "simply shares a photo of a receipt or invoice. The receipt image " +
379
- "is sent as base64, validated, uploaded to cloud storage, and processed " +
402
+ "is validated, uploaded to cloud storage, and processed " +
380
403
  "by AI to extract vendor, amount, date, tax, and category. The expense " +
381
- "appears in the user's spreadsheet within 30 seconds.",
404
+ "appears in the user's spreadsheet within 30 seconds. Handles images and " +
405
+ "PDFs, mixed together in one batch.\n\n" +
406
+ "TO SEND FILES (preferred, and required for PDFs): call this tool with " +
407
+ "filesToUpload listing every file the user gave you. It returns one " +
408
+ "signed upload URL per file. Upload them ONE AT A TIME with an HTTP PUT, " +
409
+ "telling the user which file you just finished and how many remain, then " +
410
+ "call this tool ONCE with uploadRefs for all of them — that processes " +
411
+ "the whole set as a single batch, like the ExpenseBot web app. Do not " +
412
+ "call this tool once per file.\n\n" +
413
+ "Only use the photo parameter for a single small image whose base64 you " +
414
+ "can reliably include in full — large base64 payloads are frequently " +
415
+ "dropped in transit, which silently loses the receipt.",
382
416
  inputSchema: {
383
417
  type: "object",
384
418
  properties: {
419
+ filesToUpload: {
420
+ type: "array",
421
+ description:
422
+ "Request upload URLs for one or more files. Include EVERY file the " +
423
+ "user provided in a single call. Returns one signedUrl + uploadRef " +
424
+ "per file; upload each, then call this tool again with uploadRefs.",
425
+ items: {
426
+ type: "object",
427
+ properties: {
428
+ id: {
429
+ type: "string",
430
+ description:
431
+ "Your own identifier for this file, echoed back so you can " +
432
+ "match URLs to files. E.g. '1', '2'.",
433
+ },
434
+ filename: {
435
+ type: "string",
436
+ description: "Original filename, e.g. 'lunch.jpg' or 'invoice.pdf'.",
437
+ },
438
+ mimeType: {
439
+ type: "string",
440
+ enum: [
441
+ "image/jpeg",
442
+ "image/png",
443
+ "image/heic",
444
+ "image/heif",
445
+ "image/webp",
446
+ "application/pdf",
447
+ ],
448
+ description:
449
+ "MIME type. Must match the Content-Type header used in the " +
450
+ "PUT exactly. The real format is re-detected from the file's " +
451
+ "contents on submit, so a close guess still works.",
452
+ },
453
+ },
454
+ required: ["filename"],
455
+ },
456
+ },
457
+ uploadRefs: {
458
+ type: "array",
459
+ description:
460
+ "Submit previously uploaded files as ONE batch. Include every " +
461
+ "uploadRef from the filesToUpload step. If any file fails " +
462
+ "validation the whole batch is rejected and nothing is processed.",
463
+ items: {
464
+ type: "object",
465
+ properties: {
466
+ id: { type: "string", description: "The id you supplied in filesToUpload." },
467
+ uploadRef: { type: "string", description: "uploadRef returned for that file." },
468
+ },
469
+ required: ["uploadRef"],
470
+ },
471
+ },
472
+ uploadRef: {
473
+ type: "string",
474
+ description:
475
+ "Single-file shorthand for uploadRefs. Use uploadRefs when there " +
476
+ "is more than one file.",
477
+ },
385
478
  photo: {
386
479
  type: "string",
387
480
  description:
388
- "Base64-encoded image or PDF data (JPEG, PNG, HEIC, WebP, or PDF). Max 15MB.",
481
+ "Base64-encoded image or PDF data (JPEG, PNG, HEIC, WebP, or PDF). " +
482
+ "Max 15MB. Only for small images — large payloads get truncated or " +
483
+ "dropped in transit; use uploadRef instead.",
389
484
  },
390
485
  filename: {
391
486
  type: "string",
@@ -403,7 +498,12 @@ const TOOLS = [
403
498
  description: "MIME type of the file (default: image/jpeg)",
404
499
  },
405
500
  },
406
- required: ["photo"],
501
+ // Neither is individually required: the server accepts uploadRef OR
502
+ // photo and returns a clear 400 naming both when it gets neither.
503
+ // Keeping photo in `required` would reintroduce the original failure --
504
+ // the client rejecting the call locally when a model omits base64, so
505
+ // nothing ever reaches the server and no diagnostic is recorded.
506
+ required: [],
407
507
  },
408
508
  },
409
509
  {
@@ -924,6 +1024,22 @@ const TOOLS = [
924
1024
  required: ["reportId"],
925
1025
  },
926
1026
  },
1027
+ {
1028
+ name: "get_spreadsheet_url",
1029
+ description:
1030
+ "Return the user's master ExpenseBot Google Sheet plus authenticated " +
1031
+ "ExpenseBot workspace links, each with a label and a description of when " +
1032
+ "to use it. Use this when the user asks to open, view, check, or edit their " +
1033
+ "spreadsheet; review expenses or income; manually scan Gmail; reconcile; " +
1034
+ "open reports; or asks where a submitted receipt went. Choose and show the " +
1035
+ "one or two links relevant to the request instead of listing the entire " +
1036
+ "catalog. After a receipt submission, prefer Review expenses plus the " +
1037
+ "Google Sheet. After an income write, prefer Review income plus the Sheet. " +
1038
+ "For a Gmail scan or connection request, use the Scan Gmail link, which " +
1039
+ "opens the existing Gmail scanning interface. Read-only; this tool does " +
1040
+ "not create or modify spreadsheet rows.",
1041
+ inputSchema: { type: "object", properties: {} },
1042
+ },
927
1043
  {
928
1044
  name: "get_pricing",
929
1045
  description:
@@ -1076,11 +1192,13 @@ const TOOLS = [
1076
1192
  {
1077
1193
  name: "get_scan_status",
1078
1194
  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.",
1195
+ "Check the authoritative status of the user's Gmail receipt scans. " +
1196
+ "Returns the active scan lock, the same live phase and item progress " +
1197
+ "shown by ExpenseBot's in-app status pill, queued or attention-needed " +
1198
+ "years, and recent outcomes. Call when the user asks whether a scan is " +
1199
+ "running, finished, stuck, or what it is doing. When complete, show the " +
1200
+ "returned spreadsheetUrl or reviewExpensesUrl; when setup or reconnection " +
1201
+ "is needed, show gmailScanUrl. Read-only.",
1084
1202
  inputSchema: { type: "object", properties: {} },
1085
1203
  },
1086
1204
  {
@@ -1233,7 +1351,12 @@ const TOOLS = [
1233
1351
  expenseId: { type: "string", description: "Exact full Receipt ID from Column Q, returned as expenseId by search_expenses." },
1234
1352
  fields: {
1235
1353
  type: "object",
1236
- description: "The fields to change. Only these keys are honored.",
1354
+ description:
1355
+ "Partial update object. Include one or more of these optional keys; " +
1356
+ "omit every field that should remain unchanged.",
1357
+ minProperties: 1,
1358
+ maxProperties: 4,
1359
+ additionalProperties: false,
1237
1360
  properties: {
1238
1361
  category: { type: "string" },
1239
1362
  tag: { type: "string" },
@@ -1378,13 +1501,12 @@ async function handleTool(name, args) {
1378
1501
 
1379
1502
  case "submit_receipt":
1380
1503
  return formatResult(
1381
- await client.execute("submit_receipt", {
1382
- photo: args.photo,
1383
- filename: args.filename,
1384
- mimeType: args.mimeType,
1385
- })
1504
+ await client.execute("submit_receipt", args)
1386
1505
  );
1387
1506
 
1507
+ case "get_spreadsheet_url":
1508
+ return formatResult(await client.execute("get_spreadsheet_url", {}));
1509
+
1388
1510
  case "add_cash_expense":
1389
1511
  return formatResult(
1390
1512
  await client.execute("add_cash_expense", args)
@@ -1743,8 +1865,8 @@ function formatResult(result) {
1743
1865
 
1744
1866
  async function main() {
1745
1867
  const server = new Server(
1746
- { name: "expensebot-auth", version: "0.6.5" },
1747
- { capabilities: { tools: {} } }
1868
+ { name: "expensebot-auth", version: "0.6.6" },
1869
+ { capabilities: { tools: {} }, instructions: SERVER_INSTRUCTIONS }
1748
1870
  );
1749
1871
 
1750
1872
  server.setRequestHandler(ListToolsRequestSchema, async () => ({
package/src/test.js CHANGED
@@ -21,7 +21,7 @@ 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 = 45; // + direct spreadsheet/review workspace links
25
25
  const REQUIRED_TOOLS = [
26
26
  // v0.5.x
27
27
  "search_expenses",
@@ -41,6 +41,7 @@ const REQUIRED_TOOLS = [
41
41
  // v0.7.0
42
42
  "get_expense_by_id",
43
43
  "export_report",
44
+ "get_spreadsheet_url",
44
45
  "get_pricing",
45
46
  "check_feature",
46
47
  "start_trial_link",
@@ -166,6 +167,15 @@ function check(label, ok, details = "") {
166
167
  responses.filter((r) => r.id != null).map((r) => [r.id, r])
167
168
  );
168
169
 
170
+ const instructions = byId.get(1)?.result?.instructions || "";
171
+ check(
172
+ "initialize instructions cover scan status, result links, and KB retrieval",
173
+ /get_scan_status/.test(instructions) &&
174
+ /reviewExpensesUrl/.test(instructions) &&
175
+ /search_knowledge/.test(instructions) &&
176
+ /fullAnswer:true/.test(instructions)
177
+ );
178
+
169
179
  // 1. tools/list shape
170
180
  const listResp = byId.get(2);
171
181
  const tools = listResp?.result?.tools;
@@ -198,6 +208,9 @@ function check(label, ok, details = "") {
198
208
  check(
199
209
  "update_expense requires exact Column-Q expenseId and exposes no rowNumber",
200
210
  updateExpense?.inputSchema?.required?.includes("expenseId") &&
211
+ updateExpense?.inputSchema?.properties?.fields?.minProperties === 1 &&
212
+ updateExpense?.inputSchema?.properties?.fields?.additionalProperties ===
213
+ false &&
201
214
  !Object.prototype.hasOwnProperty.call(
202
215
  updateExpense?.inputSchema?.properties || {},
203
216
  "rowNumber"
@@ -213,6 +226,19 @@ function check(label, ok, details = "") {
213
226
  searchExpenses?.inputSchema?.properties?.limit?.maximum === 50 &&
214
227
  /nextCursor/.test(searchExpenses?.description || "")
215
228
  );
229
+ const searchKnowledge = tools.find((tool) => tool.name === "search_knowledge");
230
+ check(
231
+ "search_knowledge exposes bounded full-answer retrieval",
232
+ searchKnowledge?.inputSchema?.properties?.fullAnswer?.type === "boolean" &&
233
+ searchKnowledge?.inputSchema?.properties?.limit?.maximum === 10
234
+ );
235
+ const scanStatus = tools.find((tool) => tool.name === "get_scan_status");
236
+ check(
237
+ "get_scan_status describes authoritative live progress and result links",
238
+ /authoritative/.test(scanStatus?.description || "") &&
239
+ /live phase/.test(scanStatus?.description || "") &&
240
+ /reviewExpensesUrl/.test(scanStatus?.description || "")
241
+ );
216
242
  }
217
243
 
218
244
  // 2. get_pricing (id=3) — should succeed in onboarding mode