@expensebot/mcp-server-auth 0.5.0 → 0.6.0

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 ADDED
@@ -0,0 +1,114 @@
1
+ # @expensebot/mcp-server-auth
2
+
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
+
5
+ **31 tools** across:
6
+ - **Search & analytics** — `search_expenses`, `get_spending_summary`, `get_deep_analytics`, `list_categories`, `list_tags`, `list_income_categories`, `search_knowledge`
7
+ - **Income & P&L** *(v0.6.0)* — `get_income_summary`, `get_pnl`, `get_per_tag_pnl`
8
+ - **Receipt capture** — `submit_receipt` (photo/PDF), `add_cash_expense`, `add_mileage_entry`, `add_income`, `parse_expense`, `get_expense_by_id`
9
+ - **Gmail** — `scan_gmail`, `process_gmail_receipts`
10
+ - **Reports** — `create_report`, `list_reports`, `get_report_details`, `share_report`, `export_report`
11
+ - **Compliance & tax** — `check_compliance`, `fix_compliance`, `check_tax_deductibility`
12
+ - **Activity & onboarding** — `get_recent_activity`, `get_signup_link`, `get_pricing`, `check_feature`, `start_trial_link`
13
+
14
+ ## Setup
15
+
16
+ **Full step-by-step instructions for every supported client live at:**
17
+
18
+ → **<https://www.expensebot.ai/mcp>**
19
+
20
+ ### Quick start (Claude Desktop)
21
+
22
+ 1. Sign in at [expensebot.ai](https://www.expensebot.ai) → Settings → AI Assistant Tokens → Generate
23
+ 2. Copy the token (shown once)
24
+ 3. Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (Mac) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
25
+
26
+ ```json
27
+ {
28
+ "mcpServers": {
29
+ "expensebot": {
30
+ "command": "npx",
31
+ "args": ["-y", "@expensebot/mcp-server-auth", "--token=YOUR_TOKEN_HERE"]
32
+ }
33
+ }
34
+ }
35
+ ```
36
+
37
+ 4. Restart Claude Desktop
38
+
39
+ ### Quick start (Claude Code CLI)
40
+
41
+ ```bash
42
+ claude mcp add expensebot -- npx -y @expensebot/mcp-server-auth --token=YOUR_TOKEN_HERE
43
+ ```
44
+
45
+ ### Quick start (Cursor)
46
+
47
+ Edit `~/.cursor/mcp.json`:
48
+
49
+ ```json
50
+ {
51
+ "mcpServers": {
52
+ "expensebot": {
53
+ "command": "npx",
54
+ "args": ["-y", "@expensebot/mcp-server-auth", "--token=YOUR_TOKEN_HERE"]
55
+ }
56
+ }
57
+ }
58
+ ```
59
+
60
+ Then in Cursor: Settings → Tools & Integrations → confirm the green dot next to **expensebot**.
61
+
62
+ ### Continue, Cline, Windsurf, custom clients
63
+
64
+ Same `npx -y @expensebot/mcp-server-auth --token=...` command in your client's MCP config.
65
+
66
+ ## Token model
67
+
68
+ - **Personal Access Tokens (PAT)** scoped to your ExpenseBot account
69
+ - **Configurable expiry**, revokable instantly from Settings → AI Assistant Tokens
70
+ - **Max 5 active tokens per user** — generate one per device/AI client
71
+ - All actions audit-logged server-side
72
+ - Tokens stored as SHA-256 hashes; CASA Tier 2 certified
73
+
74
+ ## Listed on
75
+
76
+ - **Official MCP Registry** — `io.github.TotesMagotes/mcp-server-auth`
77
+ - **awesome-mcp-servers** — Finance & Fintech section
78
+ - **Glama** — <https://glama.ai/mcp/servers/TotesMagotes/expensebot>
79
+
80
+ ## Onboarding mode (no token)
81
+
82
+ Running without a token exposes 5 read-only tools that help new users discover ExpenseBot and sign up:
83
+ - `get_signup_link` — returns ExpenseBot signup URL
84
+ - `search_knowledge` — searches the public ExpenseBot knowledge base
85
+ - `get_pricing` — returns current pricing for all plans *(v0.7.0)*
86
+ - `check_feature` — answers "does ExpenseBot support X?" *(v0.7.0)*
87
+ - `start_trial_link` — UTM-tagged signup URL *(v0.7.0)*
88
+
89
+ ```bash
90
+ npx @expensebot/mcp-server-auth
91
+ # (no --token argument)
92
+ ```
93
+
94
+ Useful for AI agents evaluating ExpenseBot before a user has an account.
95
+
96
+ ## Read-only docs server
97
+
98
+ For pure pre-sales discovery (no account, no token):
99
+
100
+ ```bash
101
+ npx @expensebot/mcp-server
102
+ ```
103
+
104
+ Exposes the ExpenseBot knowledge base, FAQ, and feature docs as MCP resources. Useful for AI agents answering "does ExpenseBot support X?" type questions.
105
+
106
+ ## Source / issues / support
107
+
108
+ - Source: <https://github.com/TotesMagotes/expensebot/tree/master/mcp-server-auth>
109
+ - Issues: email `support@expensebot.ai`
110
+ - Roadmap (remote HTTPS MCP for ChatGPT + Claude.ai web): <https://www.expensebot.ai/mcp>
111
+
112
+ ## License
113
+
114
+ MIT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@expensebot/mcp-server-auth",
3
- "version": "0.5.0",
3
+ "version": "0.6.0",
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": {
@@ -10,6 +10,7 @@
10
10
  "main": "./src/index.js",
11
11
  "files": [
12
12
  "src",
13
+ "scripts",
13
14
  "README.md"
14
15
  ],
15
16
  "keywords": [
@@ -30,7 +31,10 @@
30
31
  },
31
32
  "scripts": {
32
33
  "start": "node src/index.js",
33
- "test": "node src/test.js"
34
+ "test": "node src/test.js",
35
+ "sync-check": "node scripts/sync-check.js",
36
+ "gen-descriptions": "node scripts/generate-descriptions-from-kb.js",
37
+ "prepublishOnly": "node scripts/sync-check.js && node src/test.js"
34
38
  },
35
39
  "author": "ExpenseBot",
36
40
  "license": "MIT"
@@ -0,0 +1,10 @@
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
+ }
@@ -0,0 +1,113 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * KB-derived tool descriptions (PROOF-OF-CONCEPT, opt-in)
4
+ *
5
+ * The drift problem: an analytics capability has its description live in
6
+ * 4 places — KB markdown, server enum, MCP TOOLS[], README. When we add
7
+ * a feature to the income tab, all four need to update or AI clients
8
+ * advertise stale capabilities. (See `reference_income_categories_drift.md`.)
9
+ *
10
+ * Long-term fix: derive the descriptive prose for income/P&L/per-tag tools
11
+ * from the canonical KB entry. This script scans the KB for tagged
12
+ * sections and emits a `descriptions.generated.json` that index.js can
13
+ * import. If the KB changes, re-run this script and the tool descriptions
14
+ * update automatically.
15
+ *
16
+ * STATUS: scaffold only. Actually wiring index.js to import the generated
17
+ * file is gated on a v0.8.0 cleanup. Today's v0.6.0 still hand-writes the
18
+ * descriptions in src/index.js to avoid a bigger refactor.
19
+ *
20
+ * Usage:
21
+ * npm run gen-descriptions # writes scripts/descriptions.generated.json
22
+ *
23
+ * Wire-in TODO (when ready):
24
+ * 1. Replace inline descriptions in src/index.js with `import desc from
25
+ * "../scripts/descriptions.generated.json" assert { type: "json" }`
26
+ * 2. Reference desc.get_income_summary etc. in TOOLS[]
27
+ * 3. Add a CI step that re-runs this script + diffs the generated file
28
+ * against the committed copy (drift check)
29
+ */
30
+
31
+ import fs from "node:fs";
32
+ import path from "node:path";
33
+ import { fileURLToPath } from "node:url";
34
+
35
+ const __dirname = path.dirname(fileURLToPath(import.meta.url));
36
+ const ROOT = path.resolve(__dirname, "..");
37
+
38
+ // Adjust if the repo layout changes
39
+ const KB_ENTRY = path.resolve(
40
+ ROOT,
41
+ "../server/config/kb/entries/income-and-pnl-analytics.md"
42
+ );
43
+
44
+ const OUT = path.join(__dirname, "descriptions.generated.json");
45
+
46
+ function loadKb() {
47
+ if (!fs.existsSync(KB_ENTRY)) {
48
+ console.error(`KB entry not found: ${KB_ENTRY}`);
49
+ process.exit(1);
50
+ }
51
+ return fs.readFileSync(KB_ENTRY, "utf8");
52
+ }
53
+
54
+ // Strip frontmatter, return body
55
+ function body(md) {
56
+ return md.replace(/^---[\s\S]*?---\s*/m, "").trim();
57
+ }
58
+
59
+ // Pull bullet lists under a bolded heading like "**Income (Schedule C / T2125 basis)**"
60
+ function extractSection(md, headingRe) {
61
+ const m = md.match(headingRe);
62
+ if (!m) return null;
63
+ // Read until next bolded line or end
64
+ const start = m.index + m[0].length;
65
+ const rest = md.slice(start);
66
+ const stop = rest.search(/\n\*\*[^*]+\*\*/);
67
+ return (stop === -1 ? rest : rest.slice(0, stop)).trim();
68
+ }
69
+
70
+ const md = body(loadKb());
71
+
72
+ const incomeSection =
73
+ extractSection(md, /\*\*Income \(Schedule C[^*]+\*\*/) || "";
74
+ const pnlSection = extractSection(md, /\*\*Profit & Loss\*\*/) || "";
75
+ const perTagSection = extractSection(md, /\*\*Per-Tag P&L[^*]+\*\*/) || "";
76
+
77
+ function summarize(s, header) {
78
+ const examples = (s.match(/"([^"]+)"/g) || []).slice(0, 4).join(", ");
79
+ return `${header} Examples: ${examples}.`;
80
+ }
81
+
82
+ const out = {
83
+ _meta: {
84
+ generatedAt: new Date().toISOString(),
85
+ sourceKb: path.relative(ROOT, KB_ENTRY),
86
+ note:
87
+ "Auto-generated from KB. Do NOT edit by hand — re-run " +
88
+ "`npm run gen-descriptions` after the KB changes.",
89
+ },
90
+ get_income_summary: summarize(
91
+ incomeSection,
92
+ "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)."
93
+ ),
94
+ get_pnl: summarize(
95
+ pnlSection,
96
+ "Compute Profit & Loss across the Income tab and expenses."
97
+ ),
98
+ get_per_tag_pnl: summarize(
99
+ perTagSection,
100
+ "Per-tag P&L — revenue, cost, profit, and margin grouped by tag. Requires both income AND expense rows to be tagged consistently."
101
+ ),
102
+ };
103
+
104
+ fs.writeFileSync(OUT, JSON.stringify(out, null, 2) + "\n");
105
+ console.log(`✓ Wrote ${path.relative(ROOT, OUT)}`);
106
+ console.log(
107
+ ` Tools generated: ${Object.keys(out).filter((k) => k !== "_meta").length}`
108
+ );
109
+ console.log(` Source KB: ${path.relative(ROOT, KB_ENTRY)}`);
110
+ console.log(
111
+ "\nNote: this is a scaffold. index.js still uses inline descriptions in v0.6.0."
112
+ );
113
+ console.log("Wire-in plan documented in this file's header comment.");
@@ -0,0 +1,177 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Sync-check — verifies the MCP tool list is consistent across the files
4
+ * that need to agree. Runs as `npm run sync-check` and exits non-zero
5
+ * if drift is detected.
6
+ *
7
+ * Files validated:
8
+ * 1. src/index.js — TOOLS[] array + handleTool() switch (source of truth)
9
+ * 2. README.md — bullet-list tool inventory + total tool count
10
+ * 3. package.json — version
11
+ * 4. server.json — version (top-level + packages[].version)
12
+ * 5. src/client.js — User-Agent string version match
13
+ *
14
+ * Source of truth = src/index.js. README/package.json/server.json must
15
+ * agree with it. Add this to CI before publish to prevent the kind of
16
+ * silent drift that bit the income-categories enum across windows.
17
+ *
18
+ * Background: see reference_income_categories_drift.md
19
+ */
20
+
21
+ import fs from "node:fs";
22
+ import path from "node:path";
23
+ import { fileURLToPath } from "node:url";
24
+
25
+ const __dirname = path.dirname(fileURLToPath(import.meta.url));
26
+ const ROOT = path.resolve(__dirname, "..");
27
+
28
+ const errors = [];
29
+ const warnings = [];
30
+
31
+ function fail(msg) {
32
+ errors.push(msg);
33
+ }
34
+ function warn(msg) {
35
+ warnings.push(msg);
36
+ }
37
+
38
+ // ── 1. Parse src/index.js ────────────────────────────────────────────
39
+ const indexSrc = fs.readFileSync(path.join(ROOT, "src/index.js"), "utf8");
40
+
41
+ // Extract tool names from TOOLS = [ ... { name: "...", ... }, ... ]
42
+ const toolNameRe = /\bname:\s*"([a-z_][a-z0-9_]*)"/gi;
43
+ const tools = [];
44
+ let match;
45
+ const toolBlock = indexSrc.match(/const TOOLS = \[([\s\S]*?)\n\];\n/);
46
+ if (!toolBlock) {
47
+ fail("Could not find `const TOOLS = [ ... ];` in src/index.js");
48
+ } else {
49
+ while ((match = toolNameRe.exec(toolBlock[1])) !== null) {
50
+ tools.push(match[1]);
51
+ }
52
+ }
53
+
54
+ // Extract case-branch handlers from handleTool()
55
+ const caseRe = /\bcase\s+"([a-z_][a-z0-9_]*)":/g;
56
+ const cases = new Set();
57
+ while ((match = caseRe.exec(indexSrc)) !== null) {
58
+ cases.add(match[1]);
59
+ }
60
+
61
+ // Extract Server version (the MCP protocol-level version string)
62
+ const serverVersionMatch = indexSrc.match(
63
+ /name:\s*"expensebot-auth",\s*version:\s*"([^"]+)"/
64
+ );
65
+ const serverVersion = serverVersionMatch?.[1];
66
+
67
+ // Extract advertised tool count from get_signup_link message
68
+ const advertisedCountMatch = indexSrc.match(
69
+ /unlock all (\d+) tools/i
70
+ );
71
+ const advertisedCount = advertisedCountMatch?.[1]
72
+ ? parseInt(advertisedCountMatch[1], 10)
73
+ : null;
74
+
75
+ // ── 2. Cross-check: every tool has a case branch ────────────────────
76
+ const missingCases = tools.filter((t) => !cases.has(t));
77
+ if (missingCases.length) {
78
+ fail(
79
+ `${missingCases.length} tool(s) declared in TOOLS[] but missing a ` +
80
+ `handleTool() case branch: ${missingCases.join(", ")}`
81
+ );
82
+ }
83
+
84
+ // ── 3. README.md ────────────────────────────────────────────────────
85
+ const readme = fs.readFileSync(path.join(ROOT, "README.md"), "utf8");
86
+ const readmeCountMatch = readme.match(/\*\*(\d+)\s+tools\*\*/);
87
+ const readmeCount = readmeCountMatch ? parseInt(readmeCountMatch[1], 10) : null;
88
+ if (readmeCount === null) {
89
+ warn("README.md does not declare a tool count (looking for `**N tools**`)");
90
+ } else if (readmeCount !== tools.length) {
91
+ fail(
92
+ `README.md declares **${readmeCount} tools** but src/index.js has ${tools.length}`
93
+ );
94
+ }
95
+
96
+ // Check that every public tool name appears in the README inventory
97
+ const missingFromReadme = tools.filter(
98
+ (t) => !readme.includes("`" + t + "`")
99
+ );
100
+ if (missingFromReadme.length) {
101
+ fail(
102
+ `${missingFromReadme.length} tool(s) missing from README.md inventory: ` +
103
+ missingFromReadme.join(", ")
104
+ );
105
+ }
106
+
107
+ // ── 4. package.json ─────────────────────────────────────────────────
108
+ const pkg = JSON.parse(fs.readFileSync(path.join(ROOT, "package.json"), "utf8"));
109
+ if (serverVersion && pkg.version !== serverVersion) {
110
+ fail(
111
+ `Version drift: package.json=${pkg.version} vs src/index.js Server=${serverVersion}`
112
+ );
113
+ }
114
+
115
+ // ── 5. server.json ──────────────────────────────────────────────────
116
+ const serverJson = JSON.parse(
117
+ fs.readFileSync(path.join(ROOT, "server.json"), "utf8")
118
+ );
119
+ if (serverJson.version !== pkg.version) {
120
+ fail(`Version drift: server.json=${serverJson.version} vs package.json=${pkg.version}`);
121
+ }
122
+ const pkgEntry = serverJson.packages?.find(
123
+ (p) => p.identifier === pkg.name
124
+ );
125
+ if (!pkgEntry) {
126
+ warn(
127
+ `server.json packages[] does not include identifier '${pkg.name}'`
128
+ );
129
+ } else if (pkgEntry.version !== pkg.version) {
130
+ fail(
131
+ `Version drift: server.json packages[].version=${pkgEntry.version} vs package.json=${pkg.version}`
132
+ );
133
+ }
134
+
135
+ // ── 6. client.js User-Agent ─────────────────────────────────────────
136
+ const clientSrc = fs.readFileSync(path.join(ROOT, "src/client.js"), "utf8");
137
+ const uaMatch = clientSrc.match(/expensebot-mcp-auth\/([^"]+)"/);
138
+ const uaVersion = uaMatch?.[1];
139
+ if (uaVersion && uaVersion !== pkg.version) {
140
+ fail(
141
+ `User-Agent drift: client.js says expensebot-mcp-auth/${uaVersion} ` +
142
+ `but package.json is ${pkg.version}`
143
+ );
144
+ }
145
+
146
+ // ── 7. Advertised tool count in get_signup_link message ─────────────
147
+ if (advertisedCount !== null && advertisedCount !== tools.length) {
148
+ fail(
149
+ `get_signup_link advertises ${advertisedCount} tools but src/index.js ` +
150
+ `actually declares ${tools.length}`
151
+ );
152
+ }
153
+
154
+ // ── Report ──────────────────────────────────────────────────────────
155
+ console.log(`\n=== MCP server-auth sync-check ===`);
156
+ console.log(`Tools declared: ${tools.length}`);
157
+ console.log(`Handler cases: ${cases.size} (filtered to tool names)`);
158
+ console.log(`README.md tool count: ${readmeCount ?? "n/a"}`);
159
+ console.log(`package.json version: ${pkg.version}`);
160
+ console.log(`server.json version: ${serverJson.version}`);
161
+ console.log(`Server version: ${serverVersion ?? "n/a"}`);
162
+ console.log(`User-Agent version: ${uaVersion ?? "n/a"}`);
163
+ console.log(`Advertised tool count: ${advertisedCount ?? "n/a"}`);
164
+ console.log("");
165
+
166
+ if (warnings.length) {
167
+ console.log("Warnings:");
168
+ warnings.forEach((w) => console.log(" ⚠ " + w));
169
+ console.log("");
170
+ }
171
+ if (errors.length) {
172
+ console.error("✘ Sync-check FAILED:");
173
+ errors.forEach((e) => console.error(" ✘ " + e));
174
+ console.error("");
175
+ process.exit(1);
176
+ }
177
+ console.log("✓ Sync-check PASSED — all manifests agree.\n");
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.1.0",
23
+ "User-Agent": "expensebot-mcp-auth/0.6.0",
24
24
  ...options.headers,
25
25
  },
26
26
  body: options.body ? JSON.stringify(options.body) : undefined,
package/src/index.js CHANGED
@@ -94,15 +94,19 @@ const TOOLS = [
94
94
  {
95
95
  name: "get_spending_summary",
96
96
  description:
97
- "Get spending totals, breakdowns by category or merchant, and basic " +
98
- "expense analytics. For simple questions like 'how much did I spend " +
99
- "last month' or 'top merchants'.",
97
+ "Get totals, breakdowns, and analytics across BOTH expenses and " +
98
+ "income for fast questions. Examples: 'how much did I spend last " +
99
+ "month', 'income YTD', 'rental income by property', 'P&L for Q1', " +
100
+ "'profit by client'. Covers expenses, income (Schedule C / T2125), " +
101
+ "Schedule B (interest/dividends), tax refunds, P&L, and per-tag P&L. " +
102
+ "Returns: { message, data: { total, breakdown, sampleMeta? } }.",
100
103
  inputSchema: {
101
104
  type: "object",
102
105
  properties: {
103
106
  query: {
104
107
  type: "string",
105
- description: "Natural language analytics question (e.g., 'how much did I spend in March')",
108
+ description:
109
+ "Natural language question (e.g., 'how much did I spend in March', 'rental income by property')",
106
110
  },
107
111
  categories: { type: "array", items: { type: "string" } },
108
112
  dateRange: {
@@ -115,7 +119,7 @@ const TOOLS = [
115
119
  value: { type: "string" },
116
120
  },
117
121
  },
118
- groupBy: { type: "string", enum: ["category", "merchant", "month"] },
122
+ groupBy: { type: "string", enum: ["category", "merchant", "month", "tag", "source", "paymentMethod"] },
119
123
  metric: { type: "string", enum: ["total", "count", "average"] },
120
124
  },
121
125
  },
@@ -123,9 +127,12 @@ const TOOLS = [
123
127
  {
124
128
  name: "get_deep_analytics",
125
129
  description:
126
- "Run deep analytics on the user's expenses. Use for complex questions " +
127
- "like 'why did my spending increase', 'compare Q1 vs Q2', or 'find " +
128
- "unusual patterns'. Takes 10-30 seconds (runs in background).",
130
+ "Run deeper, multi-step analytics on the user's expenses. Use for " +
131
+ "explanatory questions like 'why did my spending increase' or " +
132
+ "'compare Q1 vs Q2'. Takes 10-30 seconds (runs as a background job, " +
133
+ "polled automatically). Returns: { message, data: { ..., sampleMeta? } } " +
134
+ "where sampleMeta.isTruncated indicates whether the agent saw the " +
135
+ "full dataset.",
129
136
  inputSchema: {
130
137
  type: "object",
131
138
  properties: {
@@ -256,14 +263,21 @@ const TOOLS = [
256
263
  {
257
264
  name: "check_tax_deductibility",
258
265
  description:
259
- "Check if a specific expense type or purchase is tax deductible. " +
260
- "Provides guidance based on the user's country/tax jurisdiction.",
266
+ "Look up whether a specific expense type or purchase is tax-DEDUCTIBLE " +
267
+ "(business write-off rules) based on the user's country/jurisdiction. " +
268
+ "This is a deductibility *advice* tool — use it for questions like " +
269
+ "'is Uber deductible', 'can I write off home office', 'are client " +
270
+ "dinners 50% or 100%'. Do NOT use it for questions about tax REFUNDS " +
271
+ "received as income (use get_spending_summary with a 'tax refunds' " +
272
+ "query for those — they're routed to the Income tab, not deduction " +
273
+ "rules).",
261
274
  inputSchema: {
262
275
  type: "object",
263
276
  properties: {
264
277
  query: {
265
278
  type: "string",
266
- description: "The tax question (e.g., 'is Uber tax deductible?')",
279
+ description:
280
+ "Deductibility question (e.g., 'is Uber tax deductible', 'home office write-off rules')",
267
281
  },
268
282
  category: { type: "string" },
269
283
  merchant: { type: "string" },
@@ -540,10 +554,257 @@ const TOOLS = [
540
554
  "valid tag names, not guesses.",
541
555
  inputSchema: { type: "object", properties: {} },
542
556
  },
557
+
558
+ // ── Income & P&L analytics (v0.6.0) ───────────────────────────────────
559
+ // These are first-class entry points for income / P&L / per-tag P&L
560
+ // questions. They proxy to the same query_analytics handler that powers
561
+ // get_spending_summary, but advertise themselves separately so AI clients
562
+ // surface them in completions when users ask income/profit questions.
563
+ {
564
+ name: "get_income_summary",
565
+ description:
566
+ "Get income totals, breakdowns, and analytics from the Income tab. " +
567
+ "Covers Schedule C / T2125 income, Schedule B (interest, dividends), " +
568
+ "tax refunds, rental income, and per-source/per-payment-method/per-" +
569
+ "category/per-month breakdowns. Excludes security deposits (tenant " +
570
+ "funds, not taxable). Examples: 'income YTD', 'income by source', " +
571
+ "'rental income by property', 'interest income this year', " +
572
+ "'dividends YTD', 'tax refunds 2024'. Returns: { message, data: " +
573
+ "{ total, breakdown?, sampleMeta? } }.",
574
+ inputSchema: {
575
+ type: "object",
576
+ properties: {
577
+ query: {
578
+ type: "string",
579
+ description:
580
+ "Natural language income question (e.g., 'income YTD by source', 'rental income last month')",
581
+ },
582
+ groupBy: {
583
+ type: "string",
584
+ enum: ["source", "category", "month", "paymentMethod", "tag"],
585
+ description: "How to group the breakdown",
586
+ },
587
+ dateRange: {
588
+ type: "object",
589
+ properties: {
590
+ type: { type: "string" },
591
+ month: { type: "string" },
592
+ year: { type: "integer" },
593
+ quarter: { type: "integer" },
594
+ value: { type: "string", description: "Relative date like 'YTD', 'last quarter'" },
595
+ },
596
+ },
597
+ incomeTagPrefix: {
598
+ type: "string",
599
+ description:
600
+ "Optional tag-prefix shortcut (e.g., 'Prop –' for rental income, 'Client –' for client billings, 'Wedding –' for events). When set, the tool filters to income rows tagged with this prefix.",
601
+ },
602
+ },
603
+ },
604
+ },
605
+ {
606
+ name: "get_pnl",
607
+ description:
608
+ "Compute Profit & Loss (P&L / net income / margin) by combining the " +
609
+ "Income tab with expense tabs. Examples: 'am I profitable this " +
610
+ "year', 'P&L for Q1', 'net income last quarter', 'what's my margin'. " +
611
+ "Returns: { message, data: { revenue, expenses, netIncome, margin, " +
612
+ "sampleMeta? } }.",
613
+ inputSchema: {
614
+ type: "object",
615
+ properties: {
616
+ query: {
617
+ type: "string",
618
+ description: "Natural language P&L question (e.g., 'P&L for Q1 2025', 'am I profitable')",
619
+ },
620
+ dateRange: {
621
+ type: "object",
622
+ properties: {
623
+ type: { type: "string" },
624
+ month: { type: "string" },
625
+ year: { type: "integer" },
626
+ quarter: { type: "integer" },
627
+ value: { type: "string" },
628
+ },
629
+ },
630
+ },
631
+ },
632
+ },
633
+ {
634
+ name: "get_per_tag_pnl",
635
+ description:
636
+ "Per-tag P&L — revenue, cost, profit, and margin grouped by tag " +
637
+ "(per-client, per-property, per-event). Requires both income AND " +
638
+ "expense rows to be tagged with matching labels (e.g., 'Smith " +
639
+ "Wedding', 'Prop – Brooklyn'). Examples: 'per-tag P&L this year', " +
640
+ "'profit by client', 'profit by property', 'profit on the Smith " +
641
+ "wedding'. Defaults to year-to-date if no date range given.",
642
+ inputSchema: {
643
+ type: "object",
644
+ properties: {
645
+ query: {
646
+ type: "string",
647
+ description: "Natural language per-tag P&L question",
648
+ },
649
+ tagPrefix: {
650
+ type: "string",
651
+ description:
652
+ "Optional prefix to limit which tags are bucketed (e.g., 'Prop –' for properties only, 'Client –' for clients only). When omitted, all tags are included.",
653
+ },
654
+ dateRange: {
655
+ type: "object",
656
+ properties: {
657
+ type: { type: "string" },
658
+ month: { type: "string" },
659
+ year: { type: "integer" },
660
+ quarter: { type: "integer" },
661
+ value: { type: "string" },
662
+ },
663
+ },
664
+ },
665
+ },
666
+ },
667
+ {
668
+ name: "list_income_categories",
669
+ description:
670
+ "List the user's configured income categories (mirrors " +
671
+ "list_categories for the Income tab). Use this BEFORE calling " +
672
+ "add_income with a category so you pass the user's actual income " +
673
+ "category names, not guesses. Returns the canonical INCOME_CATEGORIES " +
674
+ "enum (Service Revenue, Product Sales, Rental Income, Interest " +
675
+ "Income, Dividend Income, Tax Refund, Other Income, etc.).",
676
+ inputSchema: { type: "object", properties: {} },
677
+ },
678
+ {
679
+ name: "get_recent_activity",
680
+ description:
681
+ "Show what the user (or their AI assistants) has recently done in " +
682
+ "ExpenseBot via this MCP server: which tools were called, when, with " +
683
+ "what arguments, and whether they succeeded. Useful for ambient " +
684
+ "questions like 'what did I do this week', 'did my last receipt " +
685
+ "submission work', or to give the user transparency into AI-assisted " +
686
+ "actions. Returns the most recent N entries from the audit log " +
687
+ "(default 20, max 100).",
688
+ inputSchema: {
689
+ type: "object",
690
+ properties: {
691
+ limit: {
692
+ type: "integer",
693
+ minimum: 1,
694
+ maximum: 100,
695
+ default: 20,
696
+ },
697
+ sinceDays: {
698
+ type: "integer",
699
+ description: "Only show actions from the last N days (default 7)",
700
+ default: 7,
701
+ },
702
+ actionId: {
703
+ type: "string",
704
+ description: "Optional: filter to a single tool/action name",
705
+ },
706
+ },
707
+ },
708
+ },
709
+
710
+ // ── Read-only mutation helpers + onboarding (v0.7.0) ─────────────────
711
+ {
712
+ name: "get_expense_by_id",
713
+ description:
714
+ "Fetch a single expense row by its sheet row number or by its " +
715
+ "ExpenseBot expenseId (the value in column J). Returns the row's " +
716
+ "headers + values + a labeled {header → value} map so you can refer " +
717
+ "to a specific expense the user mentioned. Read-only.",
718
+ inputSchema: {
719
+ type: "object",
720
+ properties: {
721
+ rowNumber: {
722
+ type: "integer",
723
+ minimum: 2,
724
+ description: "1-indexed sheet row (row 1 is headers, so ≥ 2)",
725
+ },
726
+ expenseId: {
727
+ type: "string",
728
+ description: "ExpenseBot expense ID (column J)",
729
+ },
730
+ },
731
+ },
732
+ },
733
+ {
734
+ name: "export_report",
735
+ description:
736
+ "Get download URLs for an expense report. Returns the Google Sheets " +
737
+ "view URL plus direct PDF / CSV / XLSX export URLs. The user needs to " +
738
+ "be signed into the Google account that owns the report to download " +
739
+ "(no separate auth from the AI client). Use list_reports first to find " +
740
+ "the reportId.",
741
+ inputSchema: {
742
+ type: "object",
743
+ properties: {
744
+ reportId: { type: "string", description: "Report ID from list_reports" },
745
+ },
746
+ required: ["reportId"],
747
+ },
748
+ },
749
+ {
750
+ name: "get_pricing",
751
+ description:
752
+ "Get current ExpenseBot pricing for all plans (Free Trial, Standard, " +
753
+ "Pro Add-On, Deep Scan, Accountants). Useful when the user asks 'how " +
754
+ "much does this cost' or 'what's the difference between plans'. Works " +
755
+ "with or without authentication.",
756
+ inputSchema: { type: "object", properties: {} },
757
+ },
758
+ {
759
+ name: "check_feature",
760
+ description:
761
+ "Check whether ExpenseBot supports a specific feature ('does ExpenseBot " +
762
+ "support X', 'can it integrate with Y'). Searches the public knowledge " +
763
+ "base and returns a confidence-scored answer + related questions. Works " +
764
+ "with or without authentication.",
765
+ inputSchema: {
766
+ type: "object",
767
+ properties: {
768
+ feature: {
769
+ type: "string",
770
+ description: "Feature or integration to check (e.g., 'Xero', 'mileage tracking', 'Plaid')",
771
+ },
772
+ },
773
+ required: ["feature"],
774
+ },
775
+ },
776
+ {
777
+ name: "start_trial_link",
778
+ description:
779
+ "Get a UTM-tagged signup URL for the 60-day free trial (no credit " +
780
+ "card required). Use this when an unauthenticated AI conversation " +
781
+ "wants to send the user to sign up. Returns a URL with attribution " +
782
+ "tags so we can track AI-assistant referrals.",
783
+ inputSchema: {
784
+ type: "object",
785
+ properties: {
786
+ utmSource: {
787
+ type: "string",
788
+ description: "UTM source override (default: 'mcp')",
789
+ },
790
+ utmCampaign: {
791
+ type: "string",
792
+ description: "UTM campaign override (default: 'ai-assistant')",
793
+ },
794
+ },
795
+ },
796
+ },
543
797
  ];
544
798
 
545
799
  // Tools available without authentication (onboarding mode)
546
- const PUBLIC_TOOLS = ["get_signup_link", "search_knowledge"];
800
+ const PUBLIC_TOOLS = [
801
+ "get_signup_link",
802
+ "search_knowledge",
803
+ // v0.7.0 — pre-sales discovery for unauthenticated AI agents
804
+ "get_pricing",
805
+ "check_feature",
806
+ "start_trial_link",
807
+ ];
547
808
 
548
809
  // ── Tool Handlers ──────────────────────────────────────────────────────
549
810
 
@@ -578,8 +839,8 @@ async function handleTool(name, args) {
578
839
  text:
579
840
  "**ExpenseBot — 60-day free trial, no credit card required**\n\n" +
580
841
  `Sign up: https://www.expensebot.ai?utm_source=${args?.utmSource || "mcp"}&utm_medium=ai-assistant\n\n` +
581
- "After signing up, generate an AI Assistant Token from Settings to unlock all 16 tools " +
582
- "(search expenses, submit receipts, scan Gmail, create reports, run analytics).\n\n" +
842
+ "After signing up, generate an AI Assistant Token from Settings to unlock all 31 tools " +
843
+ "(submit receipts, scan Gmail, search expenses, run income / P&L / per-tag P&L analytics, create reports).\n\n" +
583
844
  "Free for accountants forever. $10/month for everyone else.",
584
845
  },
585
846
  ],
@@ -710,6 +971,143 @@ async function handleTool(name, args) {
710
971
  case "list_tags":
711
972
  return formatResult(await client.execute("list_tags", {}));
712
973
 
974
+ // ── Income & P&L analytics (v0.6.0) — proxy to query_analytics ──
975
+ case "get_income_summary": {
976
+ // Build a query that hints at income intent + optional tag filter
977
+ let q = args.query || "income summary";
978
+ if (args.incomeTagPrefix) {
979
+ q = `${q} (filter to tag prefix '${args.incomeTagPrefix}')`;
980
+ }
981
+ if (args.groupBy) {
982
+ q = `${q} grouped by ${args.groupBy}`;
983
+ }
984
+ return formatResult(
985
+ await client.execute("query_analytics", {
986
+ ...args,
987
+ message: q,
988
+ intent: "income",
989
+ })
990
+ );
991
+ }
992
+
993
+ case "get_pnl":
994
+ return formatResult(
995
+ await client.execute("query_analytics", {
996
+ ...args,
997
+ message: args.query || "P&L summary",
998
+ intent: "pnl",
999
+ })
1000
+ );
1001
+
1002
+ case "get_per_tag_pnl": {
1003
+ let q = args.query || "per-tag P&L";
1004
+ if (args.tagPrefix) {
1005
+ q = `${q} (limit to tag prefix '${args.tagPrefix}')`;
1006
+ }
1007
+ return formatResult(
1008
+ await client.execute("query_analytics", {
1009
+ ...args,
1010
+ message: q,
1011
+ intent: "per_tag_pnl",
1012
+ })
1013
+ );
1014
+ }
1015
+
1016
+ case "list_income_categories":
1017
+ return formatResult(
1018
+ await client.execute("list_income_categories", {})
1019
+ );
1020
+
1021
+ case "get_recent_activity":
1022
+ return formatResult(
1023
+ await client.execute("get_recent_activity", {
1024
+ limit: args.limit || 20,
1025
+ sinceDays: args.sinceDays || 7,
1026
+ actionId: args.actionId,
1027
+ })
1028
+ );
1029
+
1030
+ // ── Read-only mutation helpers (v0.7.0) ──
1031
+ case "get_expense_by_id":
1032
+ return formatResult(
1033
+ await client.execute("get_expense_by_id", {
1034
+ rowNumber: args.rowNumber,
1035
+ expenseId: args.expenseId,
1036
+ })
1037
+ );
1038
+
1039
+ case "export_report":
1040
+ return formatResult(
1041
+ await client.execute("export_report", { reportId: args.reportId })
1042
+ );
1043
+
1044
+ // ── Onboarding-mode tools (v0.7.0) — work with or without token ──
1045
+ case "get_pricing": {
1046
+ // Onboarding fallback: hardcoded snapshot so it works with no token
1047
+ if (onboardingMode) {
1048
+ return {
1049
+ content: [
1050
+ {
1051
+ type: "text",
1052
+ text:
1053
+ "**ExpenseBot pricing**\n\n" +
1054
+ "- **Free Trial** — 60 days, no credit card. Current year only.\n" +
1055
+ "- **Standard** — $10/month. Current + 1 year back.\n" +
1056
+ "- **Pro Add-On** — $20 one-time. Multi-inbox + alias forwarding.\n" +
1057
+ "- **Deep Scan Add-On** — $40 one-time. 5-year historical Gmail scan.\n" +
1058
+ "- **Accountants** — Free forever. Multi-client.\n\n" +
1059
+ "Sign up: https://www.expensebot.ai?utm_source=mcp&utm_medium=ai-assistant",
1060
+ },
1061
+ ],
1062
+ };
1063
+ }
1064
+ return formatResult(await client.execute("get_pricing", {}));
1065
+ }
1066
+
1067
+ case "check_feature": {
1068
+ if (onboardingMode) {
1069
+ // Use public /api/discover with feature query
1070
+ try {
1071
+ const url = new URL("/api/discover", "https://www.expensebot.ai");
1072
+ url.searchParams.set("query", args?.feature || "");
1073
+ url.searchParams.set("utm_source", "mcp-onboarding");
1074
+ const res = await fetch(url.toString(), {
1075
+ headers: { "User-Agent": "expensebot-mcp-auth/0.6.0" },
1076
+ });
1077
+ const data = await res.json();
1078
+ return formatResult(data);
1079
+ } catch (err) {
1080
+ return {
1081
+ content: [{ type: "text", text: `Feature check failed: ${err.message}` }],
1082
+ isError: true,
1083
+ };
1084
+ }
1085
+ }
1086
+ return formatResult(
1087
+ await client.execute("check_feature", { feature: args.feature })
1088
+ );
1089
+ }
1090
+
1091
+ case "start_trial_link": {
1092
+ const utmSource = args?.utmSource || "mcp";
1093
+ const utmCampaign = args?.utmCampaign || "ai-assistant";
1094
+ const url =
1095
+ `https://www.expensebot.ai?utm_source=${encodeURIComponent(utmSource)}` +
1096
+ `&utm_medium=ai-assistant&utm_campaign=${encodeURIComponent(utmCampaign)}`;
1097
+ return {
1098
+ content: [
1099
+ {
1100
+ type: "text",
1101
+ text:
1102
+ `**Start your 60-day free trial** (no credit card required)\n\n` +
1103
+ `${url}\n\n` +
1104
+ `After signup: Settings → AI Assistant Tokens → Generate to ` +
1105
+ `unlock all ${TOOLS.length} MCP tools.`,
1106
+ },
1107
+ ],
1108
+ };
1109
+ }
1110
+
713
1111
  default:
714
1112
  return {
715
1113
  content: [{ type: "text", text: `Unknown tool: ${name}` }],
@@ -719,24 +1117,56 @@ async function handleTool(name, args) {
719
1117
  }
720
1118
 
721
1119
  function formatResult(result) {
1120
+ // Structured error path (v0.7.0): backend may return { success: false,
1121
+ // error: { code, message, hint } }. Surface clean human text without
1122
+ // burying the AI in a raw stack trace.
1123
+ if (result?.success === false) {
1124
+ const err = result.error;
1125
+ let errText;
1126
+ if (err && typeof err === "object" && err.message) {
1127
+ errText = `Error (${err.code || "unknown"}): ${err.message}`;
1128
+ if (err.hint) errText += `\n\nHint: ${err.hint}`;
1129
+ } else if (typeof err === "string") {
1130
+ errText = `Error: ${err}`;
1131
+ } else {
1132
+ errText = `Error: ${result.message || "request failed"}`;
1133
+ }
1134
+ return { content: [{ type: "text", text: errText }], isError: true };
1135
+ }
1136
+
722
1137
  // Extract the meaningful content
723
1138
  let text;
724
- if (result.message && typeof result.message === "string") {
1139
+ if (result?.message && typeof result.message === "string") {
725
1140
  text = result.message;
726
- } else if (result.data) {
1141
+ } else if (result?.data) {
727
1142
  text = JSON.stringify(result.data, null, 2);
728
1143
  } else {
729
1144
  text = JSON.stringify(result, null, 2);
730
1145
  }
731
1146
 
1147
+ // Truncation banner (v0.6.0): when the analytics agent saw only a sample
1148
+ // of the user's expenses, prepend a clear note so the AI knows totals
1149
+ // remain accurate but row-level detail is partial. Looks at multiple
1150
+ // shapes since sampleMeta can sit at result.sampleMeta or result.data.sampleMeta.
1151
+ const sm = result?.sampleMeta || result?.data?.sampleMeta;
1152
+ if (sm?.isTruncated) {
1153
+ const seen = sm.sampleCount ?? "some";
1154
+ const total = sm.totalCount ?? "many";
1155
+ const banner =
1156
+ `⚠️ Truncated result: agent saw a sample of ${seen} of ${total} rows. ` +
1157
+ `Aggregate totals are accurate; row-level detail may be partial. ` +
1158
+ `Refine the date range or add filters to see all rows.`;
1159
+ text = `${banner}\n\n${text}`;
1160
+ }
1161
+
732
1162
  // Append structured data if present
733
- if (result.data && result.message) {
1163
+ if (result?.data && result?.message) {
734
1164
  text += "\n\n---\nRaw data:\n" + JSON.stringify(result.data, null, 2);
735
1165
  }
736
1166
 
737
1167
  return {
738
1168
  content: [{ type: "text", text }],
739
- isError: result.success === false,
1169
+ isError: false,
740
1170
  };
741
1171
  }
742
1172
 
@@ -744,7 +1174,7 @@ function formatResult(result) {
744
1174
 
745
1175
  async function main() {
746
1176
  const server = new Server(
747
- { name: "expensebot-auth", version: "0.1.0" },
1177
+ { name: "expensebot-auth", version: "0.6.0" },
748
1178
  { capabilities: { tools: {} } }
749
1179
  );
750
1180
 
@@ -772,7 +1202,9 @@ async function main() {
772
1202
  const transport = new StdioServerTransport();
773
1203
  await server.connect(transport);
774
1204
  console.error(
775
- `[expensebot-auth] MCP server ready. tools=${TOOLS.length}, base=${client.baseUrl}`
1205
+ `[expensebot-auth] MCP server ready. tools=${TOOLS.length}, ` +
1206
+ `mode=${onboardingMode ? "onboarding" : "authenticated"}, ` +
1207
+ `base=${client?.baseUrl || "https://www.expensebot.ai"}`
776
1208
  );
777
1209
  }
778
1210
 
package/src/test.js ADDED
@@ -0,0 +1,242 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * Smoke test — boots the MCP server in onboarding mode (no token) and
4
+ * verifies via stdio that:
5
+ * 1. Server starts cleanly without throwing
6
+ * 2. tools/list returns the expected number of tools
7
+ * 3. All locally-handled tools (PUBLIC_TOOLS that don't need backend)
8
+ * respond without error
9
+ * 4. A token-gated tool returns the expected "requires account" error
10
+ *
11
+ * Run: npm test
12
+ *
13
+ * Does NOT hit the production backend. For that, see
14
+ * scripts/_test_mcp_e2e.js (uses a real PAT).
15
+ */
16
+
17
+ import { spawn } from "node:child_process";
18
+ import { fileURLToPath } from "node:url";
19
+ import path from "node:path";
20
+
21
+ const __dirname = path.dirname(fileURLToPath(import.meta.url));
22
+ const SERVER_PATH = path.join(__dirname, "index.js");
23
+
24
+ const EXPECTED_TOOL_COUNT = 31;
25
+ const REQUIRED_TOOLS = [
26
+ // v0.5.x
27
+ "search_expenses",
28
+ "submit_receipt",
29
+ "scan_gmail",
30
+ "create_report",
31
+ // v0.6.0
32
+ "get_income_summary",
33
+ "get_pnl",
34
+ "get_per_tag_pnl",
35
+ "list_income_categories",
36
+ "get_recent_activity",
37
+ // v0.7.0
38
+ "get_expense_by_id",
39
+ "export_report",
40
+ "get_pricing",
41
+ "check_feature",
42
+ "start_trial_link",
43
+ ];
44
+
45
+ const REQUESTS = [
46
+ {
47
+ jsonrpc: "2.0",
48
+ id: 1,
49
+ method: "initialize",
50
+ params: {
51
+ protocolVersion: "2024-11-05",
52
+ capabilities: {},
53
+ clientInfo: { name: "smoke-test", version: "1.0" },
54
+ },
55
+ },
56
+ { jsonrpc: "2.0", method: "notifications/initialized" },
57
+ { jsonrpc: "2.0", id: 2, method: "tools/list", params: {} },
58
+ {
59
+ jsonrpc: "2.0",
60
+ id: 3,
61
+ method: "tools/call",
62
+ params: { name: "get_pricing", arguments: {} },
63
+ },
64
+ {
65
+ jsonrpc: "2.0",
66
+ id: 4,
67
+ method: "tools/call",
68
+ params: { name: "start_trial_link", arguments: {} },
69
+ },
70
+ {
71
+ jsonrpc: "2.0",
72
+ id: 5,
73
+ method: "tools/call",
74
+ params: { name: "get_signup_link", arguments: {} },
75
+ },
76
+ {
77
+ // Token-gated tool — must return isError:true with onboarding message
78
+ jsonrpc: "2.0",
79
+ id: 6,
80
+ method: "tools/call",
81
+ params: { name: "search_expenses", arguments: {} },
82
+ },
83
+ ];
84
+
85
+ function runServer() {
86
+ return new Promise((resolve, reject) => {
87
+ const child = spawn("node", [SERVER_PATH], {
88
+ stdio: ["pipe", "pipe", "pipe"],
89
+ env: { ...process.env, EXPENSEBOT_TOKEN: "" },
90
+ });
91
+
92
+ const responses = [];
93
+ let stdoutBuf = "";
94
+
95
+ child.stdout.on("data", (chunk) => {
96
+ stdoutBuf += chunk.toString();
97
+ let nl;
98
+ while ((nl = stdoutBuf.indexOf("\n")) !== -1) {
99
+ const line = stdoutBuf.slice(0, nl).trim();
100
+ stdoutBuf = stdoutBuf.slice(nl + 1);
101
+ if (!line) continue;
102
+ try {
103
+ responses.push(JSON.parse(line));
104
+ } catch {
105
+ /* non-JSON stderr-ish line */
106
+ }
107
+ }
108
+ });
109
+
110
+ child.stderr.on("data", (d) => {
111
+ // Pass through banners only when running in verbose mode
112
+ if (process.env.MCP_TEST_VERBOSE) {
113
+ process.stderr.write(`[server] ${d}`);
114
+ }
115
+ });
116
+
117
+ child.on("error", reject);
118
+ child.on("exit", (code) => {
119
+ if (code !== 0 && code !== null) {
120
+ reject(new Error(`Server exited with code ${code}`));
121
+ return;
122
+ }
123
+ resolve(responses);
124
+ });
125
+
126
+ // Send all requests with small delays (server needs to ack between)
127
+ (async () => {
128
+ for (const req of REQUESTS) {
129
+ child.stdin.write(JSON.stringify(req) + "\n");
130
+ await new Promise((r) => setTimeout(r, 200));
131
+ }
132
+ // Wait for last responses, then close
133
+ await new Promise((r) => setTimeout(r, 500));
134
+ child.stdin.end();
135
+ // Server exits cleanly when stdin closes
136
+ setTimeout(() => child.kill("SIGTERM"), 1500);
137
+ })();
138
+ });
139
+ }
140
+
141
+ const failures = [];
142
+
143
+ function check(label, ok, details = "") {
144
+ const symbol = ok ? "✓" : "✘";
145
+ console.log(`${symbol} ${label}${details ? " — " + details : ""}`);
146
+ if (!ok) failures.push(label);
147
+ }
148
+
149
+ (async () => {
150
+ console.log("=== mcp-server-auth smoke test ===\n");
151
+ const responses = await runServer();
152
+ const byId = new Map(
153
+ responses.filter((r) => r.id != null).map((r) => [r.id, r])
154
+ );
155
+
156
+ // 1. tools/list shape
157
+ const listResp = byId.get(2);
158
+ const tools = listResp?.result?.tools;
159
+ check(
160
+ "tools/list returns an array",
161
+ Array.isArray(tools),
162
+ `(got ${typeof tools})`
163
+ );
164
+ if (Array.isArray(tools)) {
165
+ check(
166
+ `tools/list count = ${EXPECTED_TOOL_COUNT}`,
167
+ tools.length === EXPECTED_TOOL_COUNT,
168
+ `(got ${tools.length})`
169
+ );
170
+ const names = new Set(tools.map((t) => t.name));
171
+ const missing = REQUIRED_TOOLS.filter((n) => !names.has(n));
172
+ check(
173
+ `all ${REQUIRED_TOOLS.length} required tools present`,
174
+ missing.length === 0,
175
+ missing.length ? `missing: ${missing.join(", ")}` : ""
176
+ );
177
+ // Every tool must have a description
178
+ const noDesc = tools.filter((t) => !t.description);
179
+ check(
180
+ "every tool has a description",
181
+ noDesc.length === 0,
182
+ noDesc.length ? `missing on: ${noDesc.map((t) => t.name).join(", ")}` : ""
183
+ );
184
+ }
185
+
186
+ // 2. get_pricing (id=3) — should succeed in onboarding mode
187
+ const pricingResp = byId.get(3);
188
+ const pricingText = pricingResp?.result?.content?.[0]?.text || "";
189
+ check(
190
+ "get_pricing succeeds in onboarding mode",
191
+ pricingResp?.result && !pricingResp.result.isError,
192
+ pricingResp?.result?.isError ? "returned isError" : ""
193
+ );
194
+ check(
195
+ "get_pricing mentions Free Trial + Standard",
196
+ pricingText.includes("Free Trial") && pricingText.includes("Standard")
197
+ );
198
+
199
+ // 3. start_trial_link (id=4)
200
+ const trialResp = byId.get(4);
201
+ const trialText = trialResp?.result?.content?.[0]?.text || "";
202
+ check(
203
+ "start_trial_link succeeds in onboarding mode",
204
+ trialResp?.result && !trialResp.result.isError
205
+ );
206
+ check(
207
+ "start_trial_link includes UTM params",
208
+ trialText.includes("utm_source=mcp") && trialText.includes("utm_medium=ai-assistant")
209
+ );
210
+
211
+ // 4. get_signup_link (id=5)
212
+ const signupResp = byId.get(5);
213
+ const signupText = signupResp?.result?.content?.[0]?.text || "";
214
+ check(
215
+ "get_signup_link succeeds + advertises 31 tools",
216
+ !signupResp?.result?.isError && signupText.includes("31 tools")
217
+ );
218
+
219
+ // 5. Token-gated tool (id=6) returns isError with helpful message
220
+ const gatedResp = byId.get(6);
221
+ const gatedText = gatedResp?.result?.content?.[0]?.text || "";
222
+ check(
223
+ "search_expenses (token-gated) returns isError in onboarding",
224
+ gatedResp?.result?.isError === true
225
+ );
226
+ check(
227
+ "gated error message includes signup URL",
228
+ gatedText.includes("expensebot.ai") &&
229
+ gatedText.includes("AI Assistant Tokens")
230
+ );
231
+
232
+ console.log("");
233
+ if (failures.length) {
234
+ console.error(`✘ ${failures.length} check(s) failed:`);
235
+ failures.forEach((f) => console.error(" - " + f));
236
+ process.exit(1);
237
+ }
238
+ console.log("✓ All smoke tests passed.\n");
239
+ })().catch((err) => {
240
+ console.error("Test runner error:", err);
241
+ process.exit(2);
242
+ });