@crscreditapi/finstack-mcp-server 0.4.0-0c53dac → 0.5.0-23af60a

package/README.md

@@ -12,6 +12,8 @@ MCP server exposing CRS B2B (Finstack) customer data over the [Model Context Pro
 | `finstack_get_customer_invoices` | Paginated list of finalized invoices for one customer with full line-item breakdown. |
 | `finstack_get_customer_pricing_config` | Full configured pricing state for one customer: products, pricing addendums, and environment-user productPricing. Use to cross-check invoiced rates against contracted pricing. |
 | `finstack_get_pricing_addendum_text` | Extracted text from a pricing addendum PDF (with or without disclaimer). Server-side parses the PDF and returns plain text. |
+| `finstack_get_leadiq_analytics` | System-wide LeadsIQ analytics for a trailing window: totals vs previous period, the complete list of customers that pulled (revenue desc), entitled/active/invited split, and enrolled-but-never-pulled accounts. |
+| `finstack_get_leadiq_customer` | One customer's LeadsIQ detail: enrollment state, window/YTD/lifetime stats, match rate and append hit rates, most commonly used pull filters, recent pulls. |
 | `finstack_get_vendors` | Look up who to contact at an external vendor/partner (credit bureaus and data vendors like Equifax, TransUnion, Experian, CIC). OR-matches `query` across company, name, role, notes, location, and specialty tags; optional `connection` degree filter. |
 
 ## Install
@@ -144,6 +146,22 @@ Returns `{products, pricing_addendums, environment_users}`. `pricing_addendums[]
 
 `variant` is optional and defaults to `"with_disclaimer"`. Returns `{addendum_id, variant, page_count, text}`. The server fetches the PDF over the chatbase API and extracts text with `pdf-parse`; complex table layouts may run columns together but remain readable for LLM reasoning.
 
+### `finstack_get_leadiq_analytics`
+
+```json
+{ "days": 30 }
+```
+
+`days` is optional (default `7`, clamped server-side to 1–366). Returns `{period, totals, prev_period_totals, customers, customers_truncated, entitlement, never_pulled}`. `customers[]` is the complete list of accounts with ≥ 1 pull in the window, highest revenue first (`customers_truncated` is only `true` if the 50-account safety cap trimmed it). Definitions match the portal's admin LeadsIQ customer dashboard: a pull is one top-level LeadsIQ job, records count the export leg only, and revenue is the job's cost.
+
+### `finstack_get_leadiq_customer`
+
+```json
+{ "customer_code": "CID18068", "days": 30 }
+```
+
+Identify the customer with either `customer_code` or `user_id`; `days` is optional (default `30`) and only scopes the `period` block. Returns `{customer, entitlement, contacts, period, year_to_date, lifetime, top_filters, recent_pulls}`. `top_filters[]` aggregates each pull's submitted form filters (dashboard formatting) with per-filter usage share and most common values.
+
 All tools accept an optional `environment: "prod" | "dev"` (default `"prod"`).
 
 ## Development

package/dist/api/leadiq.api.d.ts

@@ -0,0 +1,104 @@
+/**
+ * LeadsIQ analytics calls against the mware-portal API.
+ *
+ * Both endpoints share the admin LeadsIQ customer dashboard's definitions:
+ * a pull is one top-level LeadiqJob, records count the export leg only,
+ * revenue is the pull's display cost, and entitlement means the customer has
+ * a LeadsIQ environment user in any environment.
+ */
+import type { ApiClient } from './client.js';
+export interface LeadiqPeriodTotals {
+    pulls: number;
+    records: number;
+    revenue: number;
+    active_customers: number;
+}
+export interface LeadiqActiveCustomer {
+    name: string | null;
+    customer_code: string | null;
+    pulls: number;
+    records: number;
+    revenue: number;
+    last_pull_at: string | null;
+}
+export interface LeadiqNeverPulledCustomer {
+    name: string;
+    customer_code: string | null;
+    sales: string | null;
+}
+export interface LeadiqAnalyticsDigest {
+    period: {
+        start_date: string;
+        end_date: string;
+        days: number;
+    };
+    totals: LeadiqPeriodTotals;
+    prev_period_totals: LeadiqPeriodTotals;
+    /** Every customer with >= 1 pull in the window, highest revenue first. */
+    customers: LeadiqActiveCustomer[];
+    /** True only if the 50-account safety cap trimmed `customers`. */
+    customers_truncated: boolean;
+    entitlement: {
+        entitled: number;
+        active: number;
+        invited: number;
+    };
+    never_pulled: LeadiqNeverPulledCustomer[];
+}
+export declare function getLeadiqAnalytics(client: ApiClient, days?: number): Promise<LeadiqAnalyticsDigest>;
+export interface LeadiqStats {
+    pulls: number;
+    records: number;
+    revenue: number;
+}
+export interface LeadiqTopFilter {
+    filter: string;
+    used_in_pulls: number;
+    share_of_pulls_pct: number | null;
+    top_values: Array<{
+        value: string;
+        pulls: number;
+    }>;
+}
+export interface LeadiqRecentPull {
+    submitted_at: string | null;
+    job_type: string;
+    status: string;
+    records: number;
+    revenue: number;
+    append_products: string[] | null;
+}
+export interface LeadiqCustomerDetail {
+    customer: {
+        name: string;
+        customer_code: string | null;
+    };
+    entitlement: {
+        entitled: boolean;
+        production_access: boolean;
+        status: 'active' | 'invited';
+    };
+    contacts: {
+        admin: string | null;
+        sales: string | null;
+    };
+    period: {
+        start_date: string;
+        end_date: string;
+        days: number;
+    } & LeadiqStats;
+    year_to_date: LeadiqStats;
+    lifetime: LeadiqStats & {
+        first_pull_at: string | null;
+        last_pull_at: string | null;
+        match_rate_pct: number | null;
+        append_hit_rates_pct: Record<string, number | null>;
+    };
+    top_filters: LeadiqTopFilter[];
+    recent_pulls: LeadiqRecentPull[];
+}
+export declare function getLeadiqCustomer(client: ApiClient, args: {
+    customerCode?: string;
+    userId?: string;
+    days?: number;
+}): Promise<LeadiqCustomerDetail>;

package/dist/api/leadiq.api.js

@@ -0,0 +1,36 @@
+export async function getLeadiqAnalytics(client, days) {
+    const secret = process.env.FINSTACK_CHATBASE_SECRET;
+    if (!secret) {
+        throw new Error('FINSTACK_CHATBASE_SECRET must be set');
+    }
+    const params = new URLSearchParams();
+    if (days !== undefined) {
+        params.set('days', String(days));
+    }
+    const response = await client.get(`/api/v1/chatbase/leadiq_analytics?${params}`, { 'X-Chatbase-Secret': secret });
+    if (response.status !== 'success' || !response.data) {
+        throw new Error(response.message || 'Failed to fetch LeadsIQ analytics');
+    }
+    return response.data;
+}
+export async function getLeadiqCustomer(client, args) {
+    const secret = process.env.FINSTACK_CHATBASE_SECRET;
+    if (!secret) {
+        throw new Error('FINSTACK_CHATBASE_SECRET must be set');
+    }
+    if (!args.customerCode && !args.userId) {
+        throw new Error('Provide either customer_code or user_id');
+    }
+    const params = new URLSearchParams();
+    if (args.customerCode)
+        params.set('customer_code', args.customerCode);
+    if (args.userId)
+        params.set('user_id', args.userId);
+    if (args.days !== undefined)
+        params.set('days', String(args.days));
+    const response = await client.get(`/api/v1/chatbase/leadiq_customer?${params}`, { 'X-Chatbase-Secret': secret });
+    if (response.status !== 'success' || !response.data) {
+        throw new Error(response.message || 'Failed to fetch LeadsIQ customer detail');
+    }
+    return response.data;
+}

package/dist/handlers/index.js

@@ -1,4 +1,5 @@
 import { handleGetCustomerInvoices, handleGetCustomerPricingConfig, handleGetCustomerRevenue, handleGetCustomerSummary, handleGetPricingAddendumText, handleSearchCustomer, } from './customer.handler.js';
+import { handleGetLeadiqAnalytics, handleGetLeadiqCustomer, } from './leadiq.handler.js';
 import { handleGetVendors } from './vendor.handler.js';
 const wrap = (fn) => {
     return async (args) => fn(args);
@@ -10,5 +11,7 @@ export const handlers = {
     finstack_get_customer_invoices: wrap(handleGetCustomerInvoices),
     finstack_get_customer_pricing_config: wrap(handleGetCustomerPricingConfig),
     finstack_get_pricing_addendum_text: wrap(handleGetPricingAddendumText),
+    finstack_get_leadiq_analytics: wrap(handleGetLeadiqAnalytics),
+    finstack_get_leadiq_customer: wrap(handleGetLeadiqCustomer),
     finstack_get_vendors: wrap(handleGetVendors),
 };

package/dist/handlers/leadiq.handler.d.ts

@@ -0,0 +1,13 @@
+interface GetLeadiqAnalyticsArgs {
+    days?: number;
+    environment?: string;
+}
+export declare function handleGetLeadiqAnalytics(args: GetLeadiqAnalyticsArgs): Promise<unknown>;
+interface GetLeadiqCustomerArgs {
+    customer_code?: string;
+    user_id?: string;
+    days?: number;
+    environment?: string;
+}
+export declare function handleGetLeadiqCustomer(args: GetLeadiqCustomerArgs): Promise<unknown>;
+export {};

package/dist/handlers/leadiq.handler.js

@@ -0,0 +1,17 @@
+/**
+ * LeadsIQ tool handlers
+ */
+import { getClient } from '../api/client.js';
+import { getLeadiqAnalytics, getLeadiqCustomer } from '../api/leadiq.api.js';
+export async function handleGetLeadiqAnalytics(args) {
+    const client = getClient(args.environment ?? 'prod');
+    return getLeadiqAnalytics(client, args.days);
+}
+export async function handleGetLeadiqCustomer(args) {
+    const client = getClient(args.environment ?? 'prod');
+    return getLeadiqCustomer(client, {
+        customerCode: args.customer_code,
+        userId: args.user_id,
+        days: args.days,
+    });
+}

package/dist/tools/index.js

@@ -1,3 +1,8 @@
 import { customerTools } from './customer.tools.js';
+import { leadiqTools } from './leadiq.tools.js';
 import { vendorTools } from './vendor.tools.js';
-export const tools = [...customerTools, ...vendorTools];
+export const tools = [
+    ...customerTools,
+    ...leadiqTools,
+    ...vendorTools,
+];

package/dist/tools/leadiq.tools.d.ts

@@ -0,0 +1,5 @@
+/**
+ * LeadsIQ tool definitions
+ */
+import type { ToolDefinition } from '../types/tool.types.js';
+export declare const leadiqTools: ToolDefinition[];

package/dist/tools/leadiq.tools.js

@@ -0,0 +1,50 @@
+export const leadiqTools = [
+    {
+        name: 'finstack_get_leadiq_analytics',
+        description: 'System-wide LeadsIQ (lead generation / batch append) analytics for a trailing window. Returns totals and previous-period totals (pulls, records, revenue, active_customers), customers — the COMPLETE list of customers with at least one pull in the window (highest revenue first; customers_truncated is true only if the 50-account safety cap trimmed it), the entitled/active/invited account split, and never_pulled — entitled accounts that have never run a pull, with their sales owner. Use for questions like "which customers pulled last month" (set days=30 and read customers[]), "who is the most active LeadsIQ customer by revenue" (customers[0]), or "who is enrolled in LeadsIQ but never pulled". For one customer\'s detail use finstack_get_leadiq_customer.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                days: {
+                    type: 'number',
+                    description: 'Trailing window in days, 1-366 (default 7; values outside the range are clamped server-side). Use 30 for "last month", 365 for "this past year".',
+                    minimum: 1,
+                    maximum: 366,
+                },
+                environment: {
+                    type: 'string',
+                    description: 'Target environment: "prod" (default) or "dev"',
+                    enum: ['dev', 'prod'],
+                },
+            },
+        },
+    },
+    {
+        name: 'finstack_get_leadiq_customer',
+        description: "One B2B customer's LeadsIQ usage detail: enrollment state (entitled, production_access, active/invited status), admin and sales contacts, pulls/records/revenue for a trailing window plus year_to_date and lifetime, lifetime match rate and per-field append hit rates (mobile/email/landline/demographic, as percentages), top_filters — the form filters the customer most commonly runs pulls with, each with usage share and most common values — and the 10 most recent pulls. Use for questions like \"what LeadsIQ revenue did customer X have this year\" (read year_to_date.revenue) or \"which filters does customer X commonly use\". Revenue here is LeadsIQ job cost only; for a customer's total billed revenue across all products use finstack_get_customer_revenue. Identify the customer with EITHER customer_code OR user_id.",
+        inputSchema: {
+            type: 'object',
+            properties: {
+                customer_code: {
+                    type: 'string',
+                    description: 'Customer code (CID) — e.g. "CID18068". Provide this OR user_id.',
+                },
+                user_id: {
+                    type: 'string',
+                    description: 'mware-portal user ID. Provide this OR customer_code.',
+                },
+                days: {
+                    type: 'number',
+                    description: 'Trailing window in days for the period block, 1-366 (default 30; values outside the range are clamped server-side).',
+                    minimum: 1,
+                    maximum: 366,
+                },
+                environment: {
+                    type: 'string',
+                    description: 'Target environment: "prod" (default) or "dev"',
+                    enum: ['dev', 'prod'],
+                },
+            },
+        },
+    },
+];

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@crscreditapi/finstack-mcp-server",
-	"version": "0.4.0-0c53dac",
+	"version": "0.5.0-23af60a",
 	"description": "MCP server for Finstack",
 	"type": "module",
 	"main": "dist/index.js",