@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 +114 -0
- package/package.json +6 -2
- package/scripts/descriptions.generated.json +10 -0
- package/scripts/generate-descriptions-from-kb.js +113 -0
- package/scripts/sync-check.js +177 -0
- package/src/client.js +1 -1
- package/src/index.js +452 -20
- package/src/test.js +242 -0
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.
|
|
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.
|
|
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
|
|
98
|
-
"
|
|
99
|
-
"
|
|
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:
|
|
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
|
|
127
|
-
"like 'why did my spending increase'
|
|
128
|
-
"
|
|
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
|
-
"
|
|
260
|
-
"
|
|
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:
|
|
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 = [
|
|
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
|
|
582
|
-
"(
|
|
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
|
|
1139
|
+
if (result?.message && typeof result.message === "string") {
|
|
725
1140
|
text = result.message;
|
|
726
|
-
} else if (result
|
|
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
|
|
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:
|
|
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.
|
|
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},
|
|
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
|
+
});
|