@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 +2 -2
- package/package.json +1 -1
- package/src/client.js +1 -1
- package/src/index.js +142 -20
- package/src/test.js +27 -1
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
|
-
**
|
|
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.
|
|
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.
|
|
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
|
|
362
|
-
"
|
|
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: {
|
|
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
|
|
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).
|
|
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:
|
|
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
|
|
1080
|
-
"
|
|
1081
|
-
"
|
|
1082
|
-
"
|
|
1083
|
-
"
|
|
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:
|
|
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.
|
|
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 =
|
|
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
|