@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 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
- **31 tools** across:
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.0",
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.0",
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
- "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? } }.",
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, 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', " +
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'. Returns: { message, data: " +
573
- "{ total, breakdown?, sampleMeta? } }.",
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 margin'. " +
611
- "Returns: { message, data: { revenue, expenses, netIncome, margin, " +
612
- "sampleMeta? } }.",
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 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.",
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 31 tools " +
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.0" },
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 = 31;
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 31 tools",
216
- !signupResp?.result?.isError && signupText.includes("31 tools")
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