@crscreditapi/finstack-mcp-server 0.5.0-23af60a → 0.6.0-06bd3a8

package/README.md

@@ -12,6 +12,7 @@ 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. |
@@ -138,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

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/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,4 @@
-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) => {
@@ -11,6 +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_customer_cohort: wrap(handleGetCustomerCohort),
     finstack_get_leadiq_analytics: wrap(handleGetLeadiqAnalytics),
     finstack_get_leadiq_customer: wrap(handleGetLeadiqCustomer),
     finstack_get_vendors: wrap(handleGetVendors),

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/package.json

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