@crscreditapi/finstack-mcp-server 0.4.0-0c53dac → 0.6.0-06bd3a8

package/README.md

@@ -12,6 +12,9 @@ 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_customer_cohort` | Bulk, paginated list of all customers with portal status, account type, and sales opportunities (type + stage). For cohort/tracker refreshes instead of per-customer summary calls. Optional `status` / `stage` filters. |
+| `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
@@ -136,6 +139,14 @@ Identify the customer with either `customer_code` or `user_id`. `page` defaults
 
 Returns `{products, pricing_addendums, environment_users}`. `pricing_addendums[]` entries carry `id`, `name`, `status`, `quote_id`, timestamps, `has_pdf`, `has_pdf_without_disclaimer`, and `pdf_url` / `pdf_without_disclaimer_url`. The PDF URLs require the chatbase secret to hit directly — use `finstack_get_pricing_addendum_text` to read the contents instead.
 
+### `finstack_get_customer_cohort`
+
+```json
+{ "page": 1, "per_page": 500, "status": "active", "stage": "closed_won" }
+```
+
+All parameters optional. `page` defaults to `1`; `per_page` defaults to `500`, capped at `1000`. `status` filters by portal account status (`active`, `inactive`, `blacklisted`, `locked`, `obsolete`); `stage` keeps only customers with at least one sales opportunity in that stage (`closed_won` / `closed_lost` / `churned`). Returns `{page, per_page, total_count, total_pages, customers: [...]}` where each customer carries `customer_code`, `name`, `status`, `account_type`, and `sales_opportunities[]`. Read `total_pages` and fetch the remaining pages to cover the whole cohort.
+
 ### `finstack_get_pricing_addendum_text`
 
 ```json
@@ -144,6 +155,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/customer.api.d.ts

@@ -161,3 +161,29 @@ export declare function getPricingAddendumText(client: ApiClient, args: {
     id: number;
     variant: PricingAddendumVariant;
 }): Promise<PricingAddendumText>;
+export interface CohortCustomer {
+    customer_code: string | null;
+    name: string;
+    status: string | null;
+    account_type: 'account' | 'channel_partner' | null;
+    sales_opportunities: Array<{
+        opportunity_code: string | null;
+        opportunity_type: 'full' | 'upsell' | 'expand' | 'land';
+        stage: 'closed_won' | 'closed_lost' | 'churned';
+        booking_value_mrr: number | null;
+        close_date: string | null;
+    }>;
+}
+export interface CustomerCohortPage {
+    page: number;
+    per_page: number;
+    total_count: number;
+    total_pages: number;
+    customers: CohortCustomer[];
+}
+export declare function getCustomerCohort(client: ApiClient, args: {
+    page?: number;
+    perPage?: number;
+    status?: string;
+    stage?: string;
+}): Promise<CustomerCohortPage>;

package/dist/api/customer.api.js

@@ -106,3 +106,23 @@ export async function getPricingAddendumText(client, args) {
         await parser.destroy();
     }
 }
+export async function getCustomerCohort(client, args) {
+    const secret = process.env.FINSTACK_CHATBASE_SECRET;
+    if (!secret) {
+        throw new Error('FINSTACK_CHATBASE_SECRET must be set');
+    }
+    const params = new URLSearchParams();
+    if (args.page !== undefined)
+        params.set('page', String(args.page));
+    if (args.perPage !== undefined)
+        params.set('per_page', String(args.perPage));
+    if (args.status)
+        params.set('status', args.status);
+    if (args.stage)
+        params.set('stage', args.stage);
+    const response = await client.get(`/api/v1/chatbase/customer_cohort?${params}`, { 'X-Chatbase-Secret': secret });
+    if (response.status !== 'success' || !response.data) {
+        throw new Error(response.message || 'Failed to fetch customer cohort');
+    }
+    return response.data;
+}

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/customer.handler.d.ts

@@ -31,6 +31,14 @@ interface GetCustomerPricingConfigArgs {
     environment?: string;
 }
 export declare function handleGetCustomerPricingConfig(args: GetCustomerPricingConfigArgs): Promise<unknown>;
+interface GetCustomerCohortArgs {
+    page?: number;
+    per_page?: number;
+    status?: string;
+    stage?: string;
+    environment?: string;
+}
+export declare function handleGetCustomerCohort(args: GetCustomerCohortArgs): Promise<unknown>;
 interface GetPricingAddendumTextArgs {
     id: number;
     variant?: PricingAddendumVariant;

package/dist/handlers/customer.handler.js

@@ -2,7 +2,7 @@
  * Customer tool handlers
  */
 import { getClient } from '../api/client.js';
-import { getCustomerInvoices, getCustomerPricingConfig, getCustomerRevenue, getCustomerSummary, getPricingAddendumText, searchCustomers, } from '../api/customer.api.js';
+import { getCustomerCohort, getCustomerInvoices, getCustomerPricingConfig, getCustomerRevenue, getCustomerSummary, getPricingAddendumText, searchCustomers, } from '../api/customer.api.js';
 export async function handleGetCustomerSummary(args) {
     const client = getClient(args.environment ?? 'prod');
     return getCustomerSummary(client, args.customer_code);
@@ -33,6 +33,15 @@ export async function handleGetCustomerPricingConfig(args) {
     const client = getClient(args.environment ?? 'prod');
     return getCustomerPricingConfig(client, args.customer_code);
 }
+export async function handleGetCustomerCohort(args) {
+    const client = getClient(args.environment ?? 'prod');
+    return getCustomerCohort(client, {
+        page: args.page,
+        perPage: args.per_page,
+        status: args.status,
+        stage: args.stage,
+    });
+}
 export async function handleGetPricingAddendumText(args) {
     const client = getClient(args.environment ?? 'prod');
     return getPricingAddendumText(client, {

package/dist/handlers/index.js

@@ -1,4 +1,5 @@
-import { handleGetCustomerInvoices, handleGetCustomerPricingConfig, handleGetCustomerRevenue, handleGetCustomerSummary, handleGetPricingAddendumText, handleSearchCustomer, } from './customer.handler.js';
+import { handleGetCustomerCohort, 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,8 @@ 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_customer_cohort: wrap(handleGetCustomerCohort),
+    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/customer.tools.js

@@ -152,4 +152,38 @@ export const customerTools = [
             required: ['customer_code', 'type', 'start_date', 'end_date'],
         },
     },
+    {
+        name: 'finstack_get_customer_cohort',
+        description: 'Bulk, paginated list of ALL B2B customers with their tracker fields: portal account status (active/inactive/blacklisted/locked/obsolete/new_account), account_type (account/channel_partner), and sales_opportunities[] (opportunity_code, opportunity_type full/upsell/expand/land, stage closed_won/closed_lost/churned, booking_value_mrr, close_date). Use this for cohort/tracker/dashboard refreshes or any question spanning many customers — NEVER call finstack_get_customer_summary once per customer for that. Default 500 customers per page (max 1000); read total_pages from the response and fetch the remaining pages. Optional server-side filters: status and stage.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                page: {
+                    type: 'number',
+                    description: 'Page number, 1-indexed. Default 1.',
+                    minimum: 1,
+                },
+                per_page: {
+                    type: 'number',
+                    description: 'Customers per page. Default 500, capped at 1000.',
+                    minimum: 1,
+                    maximum: 1000,
+                },
+                status: {
+                    type: 'string',
+                    description: 'Only customers with this portal status, e.g. "active", "inactive", "blacklisted", "locked", "obsolete". Omit for all.',
+                },
+                stage: {
+                    type: 'string',
+                    enum: ['closed_won', 'closed_lost', 'churned'],
+                    description: 'Only customers having at least one sales opportunity in this stage. Omit for all.',
+                },
+                environment: {
+                    type: 'string',
+                    description: 'Target environment: "prod" (default) or "dev"',
+                    enum: ['dev', 'prod'],
+                },
+            },
+        },
+    },
 ];

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.6.0-06bd3a8",
 	"description": "MCP server for Finstack",
 	"type": "module",
 	"main": "dist/index.js",