@expensebot/mcp-server-auth 0.6.0 → 0.6.1
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 +4 -1
- package/package.json +1 -1
- package/src/client.js +1 -1
- package/src/index.js +150 -22
- package/src/test.js +6 -3
package/README.md
CHANGED
|
@@ -2,15 +2,18 @@
|
|
|
2
2
|
|
|
3
3
|
Authenticated MCP (Model Context Protocol) server for [ExpenseBot](https://www.expensebot.ai). Lets Claude Desktop, Cursor, Claude Code, Continue, Cline, Windsurf, and any MCP-compatible AI assistant search receipts, submit photos, scan Gmail, create reports, and analyze spending using your real ExpenseBot account.
|
|
4
4
|
|
|
5
|
-
**
|
|
5
|
+
**33 tools** across:
|
|
6
6
|
- **Search & analytics** — `search_expenses`, `get_spending_summary`, `get_deep_analytics`, `list_categories`, `list_tags`, `list_income_categories`, `search_knowledge`
|
|
7
7
|
- **Income & P&L** *(v0.6.0)* — `get_income_summary`, `get_pnl`, `get_per_tag_pnl`
|
|
8
|
+
- **Mileage & Subscriptions** *(v0.6.1)* — `get_mileage_summary`, `get_subscription_audit`
|
|
8
9
|
- **Receipt capture** — `submit_receipt` (photo/PDF), `add_cash_expense`, `add_mileage_entry`, `add_income`, `parse_expense`, `get_expense_by_id`
|
|
9
10
|
- **Gmail** — `scan_gmail`, `process_gmail_receipts`
|
|
10
11
|
- **Reports** — `create_report`, `list_reports`, `get_report_details`, `share_report`, `export_report`
|
|
11
12
|
- **Compliance & tax** — `check_compliance`, `fix_compliance`, `check_tax_deductibility`
|
|
12
13
|
- **Activity & onboarding** — `get_recent_activity`, `get_signup_link`, `get_pricing`, `check_feature`, `start_trial_link`
|
|
13
14
|
|
|
15
|
+
**Period comparison** — All analytics tools (spending, income, P&L, per-tag P&L, mileage) accept YoY / MoM / QoQ / same-month-prev-year phrasing in the `query` field. Margin is rendered loss-aware (multiplier when expenses exceed revenue) so AI clients see "expenses 5.4× revenue" instead of "-436.9% margin".
|
|
16
|
+
|
|
14
17
|
## Setup
|
|
15
18
|
|
|
16
19
|
**Full step-by-step instructions for every supported client live at:**
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@expensebot/mcp-server-auth",
|
|
3
|
-
"version": "0.6.
|
|
3
|
+
"version": "0.6.1",
|
|
4
4
|
"mcpName": "io.github.TotesMagotes/mcp-server-auth",
|
|
5
5
|
"description": "Authenticated MCP server for ExpenseBot — lets Claude Desktop, Cursor, and other AI assistants search your expenses, create reports, and analyze spending using your actual ExpenseBot data.",
|
|
6
6
|
"bin": {
|
package/src/client.js
CHANGED
|
@@ -20,7 +20,7 @@ export class ExpenseBotClient {
|
|
|
20
20
|
headers: {
|
|
21
21
|
Authorization: `Bearer ${this.token}`,
|
|
22
22
|
"Content-Type": "application/json",
|
|
23
|
-
"User-Agent": "expensebot-mcp-auth/0.6.
|
|
23
|
+
"User-Agent": "expensebot-mcp-auth/0.6.1",
|
|
24
24
|
...options.headers,
|
|
25
25
|
},
|
|
26
26
|
body: options.body ? JSON.stringify(options.body) : undefined,
|
package/src/index.js
CHANGED
|
@@ -94,12 +94,18 @@ const TOOLS = [
|
|
|
94
94
|
{
|
|
95
95
|
name: "get_spending_summary",
|
|
96
96
|
description:
|
|
97
|
-
"
|
|
98
|
-
"
|
|
99
|
-
"
|
|
100
|
-
"
|
|
101
|
-
"
|
|
102
|
-
"
|
|
97
|
+
"Unified analytics endpoint — handles expenses, income, P&L, " +
|
|
98
|
+
"per-tag P&L (per-client / per-property / per-event), Schedule B " +
|
|
99
|
+
"drill-in (interest, dividends, tax refunds, security deposits), " +
|
|
100
|
+
"mileage, and subscription audits in ONE tool. Examples: 'how much " +
|
|
101
|
+
"did I spend last month', 'income YTD', 'rental income by " +
|
|
102
|
+
"property', 'P&L for Q1', 'profit by client', 'mileage this year', " +
|
|
103
|
+
"'recurring subscriptions', 'price increases', 'duplicate " +
|
|
104
|
+
"subscriptions', 'trial conversions'. Supports period comparison " +
|
|
105
|
+
"phrasing — 'this year vs last' (YoY), 'vs last month' (MoM), 'Q1 " +
|
|
106
|
+
"vs Q2' (QoQ), same-month-prev-year. Margin renders as multiplier " +
|
|
107
|
+
"('expenses 5.4× revenue') when in loss territory. Returns: " +
|
|
108
|
+
"{ message, data: { total, breakdown?, comparison?, sampleMeta? } }.",
|
|
103
109
|
inputSchema: {
|
|
104
110
|
type: "object",
|
|
105
111
|
properties: {
|
|
@@ -564,13 +570,18 @@ const TOOLS = [
|
|
|
564
570
|
name: "get_income_summary",
|
|
565
571
|
description:
|
|
566
572
|
"Get income totals, breakdowns, and analytics from the Income tab. " +
|
|
567
|
-
"Covers Schedule C / T2125 income, Schedule B (interest,
|
|
568
|
-
"tax refunds, rental income, and
|
|
569
|
-
"
|
|
570
|
-
"
|
|
573
|
+
"Covers Schedule C / T2125 income, Schedule B drill-in (interest, " +
|
|
574
|
+
"dividends, tax refunds, security deposits), rental income, and " +
|
|
575
|
+
"per-source / per-payment-method / per-category / per-month / " +
|
|
576
|
+
"per-tag breakdowns. Schedule-C-style category exclusions match " +
|
|
577
|
+
"year-end T6 routing (security deposits, refunds excluded from " +
|
|
578
|
+
"taxable totals). Examples: 'income YTD', 'income by source', " +
|
|
571
579
|
"'rental income by property', 'interest income this year', " +
|
|
572
|
-
"'dividends YTD', 'tax refunds 2024'
|
|
573
|
-
"
|
|
580
|
+
"'dividends YTD', 'tax refunds 2024', 'income this year vs last' " +
|
|
581
|
+
"(YoY). Supports period comparison phrasing — YoY ('vs last year'), " +
|
|
582
|
+
"MoM ('vs last month'), QoQ ('Q1 vs Q2'), same-month-prev-year. " +
|
|
583
|
+
"Returns: { message, data: { total, breakdown?, comparison?, " +
|
|
584
|
+
"sampleMeta? } }.",
|
|
574
585
|
inputSchema: {
|
|
575
586
|
type: "object",
|
|
576
587
|
properties: {
|
|
@@ -607,9 +618,13 @@ const TOOLS = [
|
|
|
607
618
|
description:
|
|
608
619
|
"Compute Profit & Loss (P&L / net income / margin) by combining the " +
|
|
609
620
|
"Income tab with expense tabs. Examples: 'am I profitable this " +
|
|
610
|
-
"year', 'P&L for Q1', 'net income last quarter', 'what's my
|
|
611
|
-
"
|
|
612
|
-
"
|
|
621
|
+
"year', 'P&L for Q1', 'net income last quarter', 'what's my " +
|
|
622
|
+
"margin', 'P&L this year vs last' (YoY). Supports period comparison " +
|
|
623
|
+
"— YoY, MoM, QoQ, same-month-prev-year. Margin renders as " +
|
|
624
|
+
"multiplier in loss territory ('expenses 5.4× revenue') so the " +
|
|
625
|
+
"user gets a readable signal instead of '-436.9% margin'. Returns: " +
|
|
626
|
+
"{ message, data: { revenue, expenses, netIncome, margin, " +
|
|
627
|
+
"comparison?, sampleMeta? } }.",
|
|
613
628
|
inputSchema: {
|
|
614
629
|
type: "object",
|
|
615
630
|
properties: {
|
|
@@ -634,11 +649,15 @@ const TOOLS = [
|
|
|
634
649
|
name: "get_per_tag_pnl",
|
|
635
650
|
description:
|
|
636
651
|
"Per-tag P&L — revenue, cost, profit, and margin grouped by tag " +
|
|
637
|
-
"(per-client, per-property, per-event). Requires
|
|
638
|
-
"expense rows to be tagged with matching labels
|
|
639
|
-
"
|
|
640
|
-
"
|
|
641
|
-
"
|
|
652
|
+
"(per-client, per-property, per-event, per-realtor-deal). Requires " +
|
|
653
|
+
"both income AND expense rows to be tagged with matching labels. " +
|
|
654
|
+
"Common tag-prefix shortcuts: 'Prop –' (rentals), 'Client –' " +
|
|
655
|
+
"(client billings), 'Wedding –' (events), 'Realtor –' (real estate " +
|
|
656
|
+
"deals). Examples: 'per-tag P&L this year', 'profit by client', " +
|
|
657
|
+
"'profit by property', 'profit on the Smith wedding', 'per-client " +
|
|
658
|
+
"P&L this year vs last' (YoY). Supports YoY / MoM / QoQ comparison " +
|
|
659
|
+
"phrasing. Margin renders as multiplier in loss territory. " +
|
|
660
|
+
"Defaults to year-to-date if no date range given.",
|
|
642
661
|
inputSchema: {
|
|
643
662
|
type: "object",
|
|
644
663
|
properties: {
|
|
@@ -707,6 +726,86 @@ const TOOLS = [
|
|
|
707
726
|
},
|
|
708
727
|
},
|
|
709
728
|
|
|
729
|
+
// ── Mileage & Subscriptions (v0.6.1) ─────────────────────────────────
|
|
730
|
+
// Both proxy to the same query_analytics action that powers the chat
|
|
731
|
+
// widget — runtime is auto-routed via classifyMileageIntent /
|
|
732
|
+
// classifySubscriptionIntent. Registered as dedicated tools so AI
|
|
733
|
+
// clients pick them up in completions for "mileage" / "subscriptions"
|
|
734
|
+
// questions instead of the generic get_spending_summary.
|
|
735
|
+
{
|
|
736
|
+
name: "get_mileage_summary",
|
|
737
|
+
description:
|
|
738
|
+
"Mileage analytics — totals, breakdowns by month / client / " +
|
|
739
|
+
"purpose / category, plus deduction framing (cents-per-mile or " +
|
|
740
|
+
"cents-per-km × distance, country-aware IRS / CRA rates). " +
|
|
741
|
+
"Examples: 'mileage this year', 'miles driven for Acme', 'mileage " +
|
|
742
|
+
"by month', 'mileage deduction estimate', 'business miles last " +
|
|
743
|
+
"quarter'. Supports YoY / MoM / QoQ comparison phrasing. Returns: " +
|
|
744
|
+
"{ message, data: { totalDistance, deductionEstimate?, breakdown?, " +
|
|
745
|
+
"comparison?, sampleMeta? } }.",
|
|
746
|
+
inputSchema: {
|
|
747
|
+
type: "object",
|
|
748
|
+
properties: {
|
|
749
|
+
query: {
|
|
750
|
+
type: "string",
|
|
751
|
+
description:
|
|
752
|
+
"Natural language mileage question (e.g., 'mileage this year', 'miles driven for Acme client')",
|
|
753
|
+
},
|
|
754
|
+
groupBy: {
|
|
755
|
+
type: "string",
|
|
756
|
+
enum: ["month", "tag", "purpose", "category"],
|
|
757
|
+
description: "How to group the breakdown",
|
|
758
|
+
},
|
|
759
|
+
dateRange: {
|
|
760
|
+
type: "object",
|
|
761
|
+
properties: {
|
|
762
|
+
type: { type: "string" },
|
|
763
|
+
month: { type: "string" },
|
|
764
|
+
year: { type: "integer" },
|
|
765
|
+
quarter: { type: "integer" },
|
|
766
|
+
value: { type: "string" },
|
|
767
|
+
},
|
|
768
|
+
},
|
|
769
|
+
},
|
|
770
|
+
},
|
|
771
|
+
},
|
|
772
|
+
{
|
|
773
|
+
name: "get_subscription_audit",
|
|
774
|
+
description:
|
|
775
|
+
"Subscription audit — wraps the Subscription Auditor engine to " +
|
|
776
|
+
"find recurring charges, duplicates, price increases, and " +
|
|
777
|
+
"trial-conversion suspects in the user's expenses. Examples: " +
|
|
778
|
+
"'recurring subscriptions', 'duplicate subscriptions', 'price " +
|
|
779
|
+
"increases', 'trial conversions', 'subscriptions over $20/month'. " +
|
|
780
|
+
"Returns: { message, data: { recurring, duplicates, priceIncreases, " +
|
|
781
|
+
"trialConversions, totalMonthlyCost, sampleMeta? } }.",
|
|
782
|
+
inputSchema: {
|
|
783
|
+
type: "object",
|
|
784
|
+
properties: {
|
|
785
|
+
query: {
|
|
786
|
+
type: "string",
|
|
787
|
+
description:
|
|
788
|
+
"Natural language subscription question (e.g., 'find duplicate subscriptions', 'price increases this year')",
|
|
789
|
+
},
|
|
790
|
+
focus: {
|
|
791
|
+
type: "string",
|
|
792
|
+
enum: ["recurring", "duplicates", "price_increases", "trial_conversions", "all"],
|
|
793
|
+
description: "Narrow the audit to a single category (default: all)",
|
|
794
|
+
},
|
|
795
|
+
dateRange: {
|
|
796
|
+
type: "object",
|
|
797
|
+
properties: {
|
|
798
|
+
type: { type: "string" },
|
|
799
|
+
month: { type: "string" },
|
|
800
|
+
year: { type: "integer" },
|
|
801
|
+
quarter: { type: "integer" },
|
|
802
|
+
value: { type: "string" },
|
|
803
|
+
},
|
|
804
|
+
},
|
|
805
|
+
},
|
|
806
|
+
},
|
|
807
|
+
},
|
|
808
|
+
|
|
710
809
|
// ── Read-only mutation helpers + onboarding (v0.7.0) ─────────────────
|
|
711
810
|
{
|
|
712
811
|
name: "get_expense_by_id",
|
|
@@ -839,7 +938,7 @@ async function handleTool(name, args) {
|
|
|
839
938
|
text:
|
|
840
939
|
"**ExpenseBot — 60-day free trial, no credit card required**\n\n" +
|
|
841
940
|
`Sign up: https://www.expensebot.ai?utm_source=${args?.utmSource || "mcp"}&utm_medium=ai-assistant\n\n` +
|
|
842
|
-
"After signing up, generate an AI Assistant Token from Settings to unlock all
|
|
941
|
+
"After signing up, generate an AI Assistant Token from Settings to unlock all 33 tools " +
|
|
843
942
|
"(submit receipts, scan Gmail, search expenses, run income / P&L / per-tag P&L analytics, create reports).\n\n" +
|
|
844
943
|
"Free for accountants forever. $10/month for everyone else.",
|
|
845
944
|
},
|
|
@@ -1027,6 +1126,35 @@ async function handleTool(name, args) {
|
|
|
1027
1126
|
})
|
|
1028
1127
|
);
|
|
1029
1128
|
|
|
1129
|
+
// ── Mileage & Subscriptions (v0.6.1) ──
|
|
1130
|
+
// Both proxy to query_analytics; classifyMileageIntent /
|
|
1131
|
+
// classifySubscriptionIntent route to the correct helper server-side.
|
|
1132
|
+
case "get_mileage_summary": {
|
|
1133
|
+
let q = args.query || "mileage summary";
|
|
1134
|
+
if (args.groupBy) q = `${q} grouped by ${args.groupBy}`;
|
|
1135
|
+
return formatResult(
|
|
1136
|
+
await client.execute("query_analytics", {
|
|
1137
|
+
...args,
|
|
1138
|
+
message: q,
|
|
1139
|
+
intent: "mileage",
|
|
1140
|
+
})
|
|
1141
|
+
);
|
|
1142
|
+
}
|
|
1143
|
+
|
|
1144
|
+
case "get_subscription_audit": {
|
|
1145
|
+
let q = args.query || "subscription audit";
|
|
1146
|
+
if (args.focus && args.focus !== "all") {
|
|
1147
|
+
q = `${q} (focus: ${args.focus})`;
|
|
1148
|
+
}
|
|
1149
|
+
return formatResult(
|
|
1150
|
+
await client.execute("query_analytics", {
|
|
1151
|
+
...args,
|
|
1152
|
+
message: q,
|
|
1153
|
+
intent: "subscriptions",
|
|
1154
|
+
})
|
|
1155
|
+
);
|
|
1156
|
+
}
|
|
1157
|
+
|
|
1030
1158
|
// ── Read-only mutation helpers (v0.7.0) ──
|
|
1031
1159
|
case "get_expense_by_id":
|
|
1032
1160
|
return formatResult(
|
|
@@ -1174,7 +1302,7 @@ function formatResult(result) {
|
|
|
1174
1302
|
|
|
1175
1303
|
async function main() {
|
|
1176
1304
|
const server = new Server(
|
|
1177
|
-
{ name: "expensebot-auth", version: "0.6.
|
|
1305
|
+
{ name: "expensebot-auth", version: "0.6.1" },
|
|
1178
1306
|
{ capabilities: { tools: {} } }
|
|
1179
1307
|
);
|
|
1180
1308
|
|
package/src/test.js
CHANGED
|
@@ -21,7 +21,7 @@ import path from "node:path";
|
|
|
21
21
|
const __dirname = path.dirname(fileURLToPath(import.meta.url));
|
|
22
22
|
const SERVER_PATH = path.join(__dirname, "index.js");
|
|
23
23
|
|
|
24
|
-
const EXPECTED_TOOL_COUNT =
|
|
24
|
+
const EXPECTED_TOOL_COUNT = 33;
|
|
25
25
|
const REQUIRED_TOOLS = [
|
|
26
26
|
// v0.5.x
|
|
27
27
|
"search_expenses",
|
|
@@ -34,6 +34,9 @@ const REQUIRED_TOOLS = [
|
|
|
34
34
|
"get_per_tag_pnl",
|
|
35
35
|
"list_income_categories",
|
|
36
36
|
"get_recent_activity",
|
|
37
|
+
// v0.6.1
|
|
38
|
+
"get_mileage_summary",
|
|
39
|
+
"get_subscription_audit",
|
|
37
40
|
// v0.7.0
|
|
38
41
|
"get_expense_by_id",
|
|
39
42
|
"export_report",
|
|
@@ -212,8 +215,8 @@ function check(label, ok, details = "") {
|
|
|
212
215
|
const signupResp = byId.get(5);
|
|
213
216
|
const signupText = signupResp?.result?.content?.[0]?.text || "";
|
|
214
217
|
check(
|
|
215
|
-
"get_signup_link succeeds + advertises
|
|
216
|
-
!signupResp?.result?.isError && signupText.includes("
|
|
218
|
+
"get_signup_link succeeds + advertises 33 tools",
|
|
219
|
+
!signupResp?.result?.isError && signupText.includes("33 tools")
|
|
217
220
|
);
|
|
218
221
|
|
|
219
222
|
// 5. Token-gated tool (id=6) returns isError with helpful message
|