@expensebot/mcp-server-auth 0.6.9 → 0.6.10

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
- **46 tools** across:
5
+ **47 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`, `get_spreadsheet_url`
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`
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.9",
3
+ "version": "0.6.10",
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.9",
49
+ "User-Agent": "expensebot-mcp-auth/0.6.10",
50
50
  "X-ExpenseBot-MCP-Transport": "stdio",
51
51
  ...options.headers,
52
52
  },
package/src/index.js CHANGED
@@ -165,14 +165,33 @@ const TOOLS = [
165
165
  description:
166
166
  "Search and filter the user's expenses. Returns matching expense rows " +
167
167
  "from their spreadsheet. Filter by category, merchant, date range, " +
168
- "amount, or tags. Each result includes expenseId, the exact durable " +
169
- "Receipt ID required by update_expense. Results are paginated: when " +
170
- "hasMore is true, call again with nextCursor and the same filters. Do " +
171
- "not split a date range into repeated overlapping searches.",
168
+ "amount, or tags. Results are paginated: when hasMore is true, call " +
169
+ "again with nextCursor and the same filters. Do not split a date " +
170
+ "range into repeated overlapping searches.\n\n" +
171
+ "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 " +
174
+ "matchedFields and a short matchReason so you can explain why it " +
175
+ "was selected. When several rows plausibly match, a disambiguation " +
176
+ "list is returned; each option carries the exact expenseId. " +
177
+ "Structured filters (categories, merchants, dateRange, tags, " +
178
+ "minAmount, maxAmount) combine with the query using AND semantics. " +
179
+ "Each result includes expenseId, the exact durable Receipt ID " +
180
+ "required by update_expense.",
172
181
  inputSchema: {
173
182
  type: "object",
174
183
  properties: {
175
184
  clientEmail: CLIENT_EMAIL_SCHEMA,
185
+ query: {
186
+ type: "string",
187
+ description:
188
+ "Optional natural-language recall over the user's existing expense " +
189
+ "fields (merchant, city/location, Notes including Business purpose, " +
190
+ "Tag, category). Deterministic case-insensitive matching — no " +
191
+ "embeddings or model classifiers. Combine with structured filters " +
192
+ "using AND semantics. Examples: 'Tribeca restaurant', 'Bodewell " +
193
+ "project hardware store', 'client dinner note'.",
194
+ },
176
195
  categories: {
177
196
  type: "array",
178
197
  items: { type: "string" },
@@ -244,22 +263,49 @@ const TOOLS = [
244
263
  {
245
264
  name: "create_report",
246
265
  description:
247
- "Create an expense report from filtered expenses. Returns the report " +
248
- "ID and summary. Can optionally share with recipients.",
266
+ "Create an expense report from a clear date, client, project, trip, " +
267
+ "category, or merchant request. Tags are ExpenseBot's grouping layer " +
268
+ "for clients, projects, project codes, and trips; call list_tags when " +
269
+ "the user's intended group is unclear. For requests such as 'all " +
270
+ "expenses in August except personal', set excludePersonal=true; this " +
271
+ "excludes both the Personal tag and Personal expense category, matching " +
272
+ "ExpenseBot's Report Wizard. Returns the report summary, exact report " +
273
+ "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.",
249
276
  inputSchema: {
250
277
  type: "object",
251
278
  properties: {
252
279
  dateRange: DATE_RANGE_SCHEMA,
253
280
  title: { type: "string", description: "Custom report title" },
254
281
  categories: { type: "array", items: { type: "string" } },
255
- tags: { type: "array", items: { type: "string" } },
282
+ tags: {
283
+ type: "array",
284
+ items: { type: "string" },
285
+ description:
286
+ "Existing ExpenseBot groups to include, such as a client, project, project code, property, or trip. Use list_tags first when uncertain.",
287
+ },
288
+ excludePersonal: {
289
+ type: "boolean",
290
+ description:
291
+ "Exclude expenses whose Tag is Personal or whose Expense Category is Personal.",
292
+ },
293
+ excludedTags: {
294
+ type: "array",
295
+ items: { type: "string" },
296
+ description: "Existing ExpenseBot groups to exclude from the report.",
297
+ },
298
+ excludedCategories: {
299
+ type: "array",
300
+ items: { type: "string" },
301
+ description: "Expense categories to exclude from the report.",
302
+ },
256
303
  shareWith: {
257
304
  type: "array",
258
305
  items: { type: "string", format: "email" },
259
306
  description: "Email addresses to share the report with",
260
307
  },
261
308
  },
262
- required: ["dateRange"],
263
309
  },
264
310
  },
265
311
  {
@@ -414,7 +460,12 @@ const TOOLS = [
414
460
  "call this tool once per file.\n\n" +
415
461
  "Only use the photo parameter for a single small image whose base64 you " +
416
462
  "can reliably include in full — large base64 payloads are frequently " +
417
- "dropped in transit, which silently loses the receipt.",
463
+ "dropped in transit, which silently loses the receipt.\n\n" +
464
+ "Optional note and tag values use the same receipt metadata path as " +
465
+ "ExpenseBot's camera, file uploader, and forwarded-email intake. The " +
466
+ "note is stored in the Notes column (L); the tag is stored in the Tag " +
467
+ "column (K). Batch defaults apply to every file, and each uploadRefs " +
468
+ "item may override either value for that file.",
418
469
  inputSchema: {
419
470
  type: "object",
420
471
  properties: {
@@ -467,6 +518,19 @@ const TOOLS = [
467
518
  properties: {
468
519
  id: { type: "string", description: "The id you supplied in filesToUpload." },
469
520
  uploadRef: { type: "string", description: "uploadRef returned for that file." },
521
+ note: {
522
+ type: "string",
523
+ description:
524
+ "Context note for this specific file. Overrides the batch-level " +
525
+ "note if both are provided. Uses the existing receipt-note " +
526
+ "pipeline and is stored in the Notes column (L).",
527
+ },
528
+ tag: {
529
+ type: "string",
530
+ description:
531
+ "Project or client tag for this specific file. Overrides the " +
532
+ "batch-level tag and is stored in the Tag column (K).",
533
+ },
470
534
  },
471
535
  required: ["uploadRef"],
472
536
  },
@@ -499,6 +563,20 @@ const TOOLS = [
499
563
  ],
500
564
  description: "MIME type of the file (default: image/jpeg)",
501
565
  },
566
+ note: {
567
+ type: "string",
568
+ description:
569
+ "Batch-level context note applied to every file in the upload. " +
570
+ "Individual files may override this with their own note. Stored " +
571
+ "through the existing receipt-note pipeline in the Notes column (L).",
572
+ },
573
+ tag: {
574
+ type: "string",
575
+ description:
576
+ "Batch-level project or client tag applied to every expense row. " +
577
+ "Individual files may override it. Stored in the Tag column (K) " +
578
+ "through the same path as the web receipt uploader.",
579
+ },
502
580
  },
503
581
  // Neither is individually required: the server accepts uploadRef OR
504
582
  // photo and returns a clear 400 naming both when it gets neither.
@@ -765,10 +843,11 @@ const TOOLS = [
765
843
  {
766
844
  name: "list_tags",
767
845
  description:
768
- "List the user's configured tags. Tags are used for client/project " +
769
- "attribution (e.g., 'Client: Acme', 'Q1 Trip', 'Property: 123 Main'). " +
770
- "Use this BEFORE calling tools that filter or assign tags so you pass " +
771
- "valid tag names, not guesses.",
846
+ "List the user's configured groups. ExpenseBot stores clients, projects, " +
847
+ "project codes, properties, and trips as tags (for example 'Client: " +
848
+ "Acme', 'Vegas Trip', or 'Property: 123 Main'). Use this when the user " +
849
+ "asks 'what groups/projects/clients do I have?' and before filtering, " +
850
+ "grouping, or reporting when the intended existing name is unclear.",
772
851
  inputSchema: { type: "object", properties: {} },
773
852
  },
774
853
 
@@ -1065,12 +1144,16 @@ const TOOLS = [
1065
1144
  "ExpenseBot workspace links, each with a label and a description of when " +
1066
1145
  "to use it. Use this when the user asks to open, view, check, or edit their " +
1067
1146
  "spreadsheet; review expenses or income; manually scan Gmail; reconcile; " +
1068
- "open reports; or asks where a submitted receipt went. Choose and show the " +
1147
+ "connect or manage a bank/credit card; open Automation Hub or General " +
1148
+ "Settings; create or open reports; or asks where a submitted receipt went. Choose and show the " +
1069
1149
  "one or two links relevant to the request instead of listing the entire " +
1070
1150
  "catalog. After a receipt submission, prefer Review expenses plus the " +
1071
1151
  "Google Sheet. After an income write, prefer Review income plus the Sheet. " +
1072
1152
  "For a Gmail scan or connection request, use the Scan Gmail link, which " +
1073
- "opens the existing Gmail scanning interface. Read-only; this tool does " +
1153
+ "opens the existing Gmail scanning interface. Bank/card requests use the " +
1154
+ "Reconcile link; configuration requests use the returned Automation Hub " +
1155
+ "or General Settings link. Complex or visually reviewed report requests " +
1156
+ "use the returned Create report link. Read-only; this tool does " +
1074
1157
  "not create or modify spreadsheet rows.",
1075
1158
  inputSchema: { type: "object", properties: {} },
1076
1159
  },
@@ -1365,6 +1448,70 @@ const TOOLS = [
1365
1448
  },
1366
1449
  },
1367
1450
  },
1451
+ {
1452
+ name: "group_expenses",
1453
+ description:
1454
+ "Group an exact set of recorded expenses for a client, project, trip, job, or other user-named purpose. " +
1455
+ "Examples: 'group my Mexico meals for client Rob', 'put these Vegas expenses under the Vegas project', " +
1456
+ "or 'group these for client Rob and create a report'. The user does not need to know about tags: " +
1457
+ "ExpenseBot resolves the requested name against existing groups and proposes creating one only when needed. " +
1458
+ "Use exact expenseId values returned by search_expenses. First call with confirm omitted/false for a grounded " +
1459
+ "preview; after explicit user approval, repeat the same operationId and selection with confirm:true. " +
1460
+ "The confirmed operation can create a report and returns exact report and Bill Client links. " +
1461
+ "Sharing remains a separate share_report action with recipient confirmation.",
1462
+ inputSchema: {
1463
+ type: "object",
1464
+ additionalProperties: false,
1465
+ properties: {
1466
+ group: {
1467
+ type: "object",
1468
+ additionalProperties: false,
1469
+ properties: {
1470
+ kind: { type: "string", enum: ["client", "project", "trip", "job", "group"] },
1471
+ name: { type: "string", description: "The group name in the user's own words." },
1472
+ },
1473
+ required: ["kind", "name"],
1474
+ },
1475
+ selection: {
1476
+ type: "object",
1477
+ additionalProperties: false,
1478
+ properties: {
1479
+ items: {
1480
+ type: "array",
1481
+ minItems: 1,
1482
+ maxItems: 500,
1483
+ items: {
1484
+ type: "object",
1485
+ additionalProperties: false,
1486
+ properties: {
1487
+ receiptId: { type: "string", description: "Exact full expenseId/Column-Q receipt identity." },
1488
+ expected: {
1489
+ type: "object",
1490
+ additionalProperties: false,
1491
+ properties: { tag: { type: "string" } },
1492
+ },
1493
+ },
1494
+ required: ["receiptId"],
1495
+ },
1496
+ },
1497
+ },
1498
+ required: ["items"],
1499
+ },
1500
+ operationId: {
1501
+ type: "string",
1502
+ pattern: "^expense-bulk:[a-zA-Z0-9_-]{8,100}$",
1503
+ description: "Stable idempotency key generated once for the preview and reused unchanged.",
1504
+ },
1505
+ confirm: { type: "boolean", description: "Omit/false for preview; true only after explicit approval." },
1506
+ approveNewGroup: { type: "boolean", description: "True only when the preview says a new group is required." },
1507
+ createReport: { type: "boolean", description: "Create a report from the exact eligible grouped expenses." },
1508
+ reportTitle: { type: "string" },
1509
+ status: { type: "boolean", description: "Read operation status using operationId." },
1510
+ undo: { type: "boolean", description: "Undo a completed grouping within its undo window." },
1511
+ },
1512
+ required: ["operationId"],
1513
+ },
1514
+ },
1368
1515
  {
1369
1516
  name: "update_expense",
1370
1517
  description:
@@ -1832,6 +1979,21 @@ async function handleTool(name, args) {
1832
1979
  })
1833
1980
  );
1834
1981
 
1982
+ case "group_expenses":
1983
+ return formatResult(
1984
+ await client.execute("group_expenses", {
1985
+ group: args.group,
1986
+ selection: args.selection,
1987
+ operationId: args.operationId,
1988
+ confirm: args.confirm,
1989
+ approveNewGroup: args.approveNewGroup,
1990
+ createReport: args.createReport,
1991
+ reportTitle: args.reportTitle,
1992
+ status: args.status,
1993
+ undo: args.undo,
1994
+ })
1995
+ );
1996
+
1835
1997
  case "update_expense":
1836
1998
  return formatResult(
1837
1999
  await client.execute("update_expense", {
@@ -1895,9 +2057,28 @@ function formatResult(result) {
1895
2057
  text = `${banner}\n\n${text}`;
1896
2058
  }
1897
2059
 
1898
- // Append structured data if present
2060
+ // Append structured data if present.
2061
+ // When the backend wraps useful fields under `data` we render that block
2062
+ // (existing contract for {message, data} responses). When structured fields
2063
+ // sit at the top level alongside message — as search_expenses does with
2064
+ // expenses, total, count, pageInfo, hasMore, and nextCursor — we collect
2065
+ // the remaining useful fields (excluding transport/envelope keys) and
2066
+ // render them so exact expense IDs, pagination cursors, and totals are
2067
+ // reachable to downstream tools like get_expense_by_id and update_expense.
1899
2068
  if (result?.data && result?.message) {
1900
2069
  text += "\n\n---\nRaw data:\n" + JSON.stringify(result.data, null, 2);
2070
+ } else if (result?.message && typeof result === "object") {
2071
+ const transportKeys = new Set(["success", "status", "error", "errorCode", "message"]);
2072
+ const rawFields = {};
2073
+ for (const [k, v] of Object.entries(result)) {
2074
+ if (transportKeys.has(k)) continue;
2075
+ // Exclude private/internal prefixed keys.
2076
+ if (typeof k === "string" && k.startsWith("_")) continue;
2077
+ rawFields[k] = v;
2078
+ }
2079
+ if (Object.keys(rawFields).length > 0) {
2080
+ text += "\n\n---\nRaw data:\n" + JSON.stringify(rawFields, null, 2);
2081
+ }
1901
2082
  }
1902
2083
 
1903
2084
  return {
@@ -1910,7 +2091,7 @@ function formatResult(result) {
1910
2091
 
1911
2092
  async function main() {
1912
2093
  const server = new Server(
1913
- { name: "expensebot-auth", version: "0.6.9" },
2094
+ { name: "expensebot-auth", version: "0.6.10" },
1914
2095
  { capabilities: { tools: {} }, instructions: SERVER_INSTRUCTIONS }
1915
2096
  );
1916
2097
 
package/src/test.js CHANGED
@@ -22,7 +22,7 @@ import { readStructuredHttpError } from "./client.js";
22
22
  const __dirname = path.dirname(fileURLToPath(import.meta.url));
23
23
  const SERVER_PATH = path.join(__dirname, "index.js");
24
24
 
25
- const EXPECTED_TOOL_COUNT = 46; // + receipt completion + direct workspace links
25
+ const EXPECTED_TOOL_COUNT = 47; // + conversational client/project grouping
26
26
  const REQUIRED_TOOLS = [
27
27
  // v0.5.x
28
28
  "search_expenses",
@@ -51,6 +51,7 @@ const REQUIRED_TOOLS = [
51
51
  "scan_gmail_years",
52
52
  "get_scan_status",
53
53
  "update_expense",
54
+ "group_expenses",
54
55
  // Phase 4B — read-only surfaces for shipped product data
55
56
  "list_client_invoices",
56
57
  "get_expense_splits",
@@ -244,6 +245,20 @@ function check(label, ok, details = "") {
244
245
  searchExpenses?.inputSchema?.properties?.limit?.maximum === 50 &&
245
246
  /nextCursor/.test(searchExpenses?.description || "")
246
247
  );
248
+ const createReport = tools.find((tool) => tool.name === "create_report");
249
+ check(
250
+ "create_report exposes Report Wizard-compatible exclusions",
251
+ createReport?.inputSchema?.properties?.excludePersonal?.type ===
252
+ "boolean" &&
253
+ !createReport?.inputSchema?.required?.includes("dateRange") &&
254
+ createReport?.inputSchema?.properties?.excludedTags?.items?.type ===
255
+ "string" &&
256
+ createReport?.inputSchema?.properties?.excludedCategories?.items
257
+ ?.type === "string" &&
258
+ /Personal tag and Personal expense category/.test(
259
+ createReport?.description || ""
260
+ )
261
+ );
247
262
  const searchKnowledge = tools.find((tool) => tool.name === "search_knowledge");
248
263
  check(
249
264
  "search_knowledge exposes bounded full-answer retrieval",