@crscreditapi/finstack-mcp-server 0.7.0-92ce169 → 0.8.0-8468b06

package/README.md

@@ -16,6 +16,7 @@ MCP server exposing CRS B2B (Finstack) customer data over the [Model Context Pro
 | `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_product_catalog` | The CRS product catalog: code, status, vendor, names, description, base cost / default price, inquiry type, FCRA, platforms, add-ons and permissible purposes. Optional exact `code` / `status` / `vendor` filters plus free-text `query`. |
 | `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
@@ -180,6 +181,14 @@ All parameters optional. `page` defaults to `1`; `per_page` defaults to `500`, c
 
 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.
 
+### `finstack_get_product_catalog`
+
+```json
+{ "vendor": "exp", "status": "active", "query": "credit profile" }
+```
+
+All arguments are optional. `code` (one code or a comma list, e.g. `"EXP1001,TUC2000"`), `status` (`active` / `terminated`) and `vendor` (`exp`, `tuc`, `eqf`, `cic`, `lnr`, `pps`, `mcl`, `kcb`, `cic_tn`, `service_link`, `fico`, `crs`, `ubq`, `at_data`, `accurate_append`, `socure`, `hansa`, `tod`) are exact-match filters applied by the portal; `query` is a case-insensitive AND-match over code, names, description, labels, add-ons and permissible purposes, applied in the MCP server. Returns `{filters, count, products}`, ordered by code. Each product carries `status` / `termination_date`, type / category / vendor (each with a `_label`), `public_name`, `private_name`, `description`, `plan_includes`, `base_cost` and `default_price` (decimal strings, default = base × 2), `inquiry` (`hard` / `soft` / `not_applicable`), `fcra`, `on_path`, `platforms` (`mcl`, `crs`, `b2c`, `liq`, `bureau_direct`), `parent_codes`, `product_codes`, `warning_notice`, `add_ons[]` (code, status, category, name, `bureau_service_code`, `base_cost`, `rolled_up_in_parent`) and `permissible_purposes[]`. Backed by the MCP `product_catalog` chatbase endpoint (mware-portal); subscriber codes and internal notes are not exposed.
+
 All tools accept an optional `environment: "prod" | "dev"` (default `"prod"`).
 
 ## Development

package/dist/api/product.api.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Product catalog calls.
+ *
+ * Backed by the mware-portal chatbase API:
+ * GET /api/v1/chatbase/product_catalog returns the full catalog snapshot (no
+ * pagination, ordered by code), authenticated with the shared
+ * X-Chatbase-Secret. `code`, `status` and `vendor` are exact-match filters
+ * applied server-side; the free-text `query` is matched here in-process.
+ */
+import type { ApiClient } from './client.js';
+export declare const PRODUCT_VENDORS: readonly ["exp", "tuc", "eqf", "cic", "lnr", "pps", "mcl", "kcb", "cic_tn", "service_link", "fico", "crs", "ubq", "at_data", "accurate_append", "socure", "hansa", "tod"];
+export type ProductVendor = (typeof PRODUCT_VENDORS)[number];
+export type ProductStatus = 'active' | 'terminated';
+export interface ProductAddOn {
+    id: number;
+    code: string;
+    /** null = active */
+    status: 'active' | 'inactive' | null;
+    category: string | null;
+    category_label: string | null;
+    name: string | null;
+    private_name: string | null;
+    description: string | null;
+    bureau_service_code: string | null;
+    /** Decimal string */
+    base_cost: string | null;
+    rolled_up_in_parent: boolean;
+}
+export interface ProductPermissiblePurpose {
+    id: number;
+    code: string;
+    name: string;
+    onboarding_path: string | null;
+}
+export interface Product {
+    id: number;
+    code: string;
+    status: ProductStatus;
+    termination_date: string | null;
+    type: string | null;
+    type_label: string | null;
+    category: string | null;
+    category_label: string | null;
+    vendor: string | null;
+    vendor_label: string | null;
+    public_name: string | null;
+    private_name: string | null;
+    description: string | null;
+    plan_includes: string | null;
+    /** Decimal string */
+    base_cost: string | null;
+    /** Decimal string, base_cost x 2 */
+    default_price: string | null;
+    inquiry: 'hard' | 'soft' | 'not_applicable' | null;
+    inquiry_label: string | null;
+    fcra: boolean | null;
+    on_path: string | null;
+    platforms: Record<string, boolean>;
+    parent_codes: string | null;
+    product_codes: string | null;
+    warning_notice: string | null;
+    add_ons: ProductAddOn[];
+    permissible_purposes: ProductPermissiblePurpose[];
+    created_at: string | null;
+    updated_at: string | null;
+}
+export interface ProductCatalogResult {
+    filters: {
+        code: string | null;
+        status: ProductStatus | null;
+        vendor: ProductVendor | null;
+        query: string | null;
+    };
+    count: number;
+    products: Product[];
+}
+export declare function getProductCatalog(client: ApiClient, args: {
+    code?: string;
+    status?: ProductStatus;
+    vendor?: ProductVendor;
+    query?: string;
+}): Promise<ProductCatalogResult>;

package/dist/api/product.api.js

@@ -0,0 +1,81 @@
+export const PRODUCT_VENDORS = [
+    'exp',
+    'tuc',
+    'eqf',
+    'cic',
+    'lnr',
+    'pps',
+    'mcl',
+    'kcb',
+    'cic_tn',
+    'service_link',
+    'fico',
+    'crs',
+    'ubq',
+    'at_data',
+    'accurate_append',
+    'socure',
+    'hansa',
+    'tod',
+];
+function productHaystack(p) {
+    return [
+        p.code,
+        p.public_name,
+        p.private_name,
+        p.description,
+        p.type_label,
+        p.category_label,
+        p.vendor_label,
+        p.product_codes,
+        p.parent_codes,
+        ...p.add_ons.flatMap((a) => [a.code, a.name, a.private_name, a.bureau_service_code]),
+        ...p.permissible_purposes.flatMap((pp) => [pp.code, pp.name]),
+    ]
+        .filter(Boolean)
+        .join(' ')
+        .toLowerCase();
+}
+export async function getProductCatalog(client, args) {
+    const secret = process.env.FINSTACK_CHATBASE_SECRET;
+    if (!secret) {
+        throw new Error('FINSTACK_CHATBASE_SECRET must be set');
+    }
+    const code = args.code
+        ?.split(',')
+        .map((c) => c.trim().toUpperCase())
+        .filter(Boolean)
+        .join(',');
+    const params = new URLSearchParams();
+    if (code)
+        params.set('code', code);
+    if (args.status)
+        params.set('status', args.status);
+    if (args.vendor)
+        params.set('vendor', args.vendor);
+    const qs = params.toString();
+    const response = await client.get(`/api/v1/chatbase/product_catalog${qs ? `?${qs}` : ''}`, { 'X-Chatbase-Secret': secret });
+    if (response.status !== 'success' || !response.data) {
+        throw new Error(response.message || 'Failed to fetch product catalog');
+    }
+    let products = response.data.products;
+    // Every term must match (AND), so "experian soft" narrows rather than widens.
+    const q = args.query?.trim().toLowerCase();
+    if (q) {
+        const terms = q.split(/\s+/).filter(Boolean);
+        products = products.filter((p) => {
+            const haystack = productHaystack(p);
+            return terms.every((t) => haystack.includes(t));
+        });
+    }
+    return {
+        filters: {
+            code: code || null,
+            status: args.status ?? null,
+            vendor: args.vendor ?? null,
+            query: args.query ?? null,
+        },
+        count: products.length,
+        products,
+    };
+}

package/dist/handlers/index.js

@@ -1,5 +1,6 @@
 import { handleGetCustomerCohort, handleGetCustomerInvoices, handleGetCustomerPricingConfig, handleGetCustomerRevenue, handleGetCustomerSummary, handleGetCustomerUsers, handleGetPricingAddendumText, handleSearchCustomer, } from './customer.handler.js';
 import { handleGetLeadiqAnalytics, handleGetLeadiqCustomer, } from './leadiq.handler.js';
+import { handleGetProductCatalog } from './product.handler.js';
 import { handleGetVendors } from './vendor.handler.js';
 const wrap = (fn) => {
     return async (args) => fn(args);
@@ -15,5 +16,6 @@ export const handlers = {
     finstack_get_customer_users: wrap(handleGetCustomerUsers),
     finstack_get_leadiq_analytics: wrap(handleGetLeadiqAnalytics),
     finstack_get_leadiq_customer: wrap(handleGetLeadiqCustomer),
+    finstack_get_product_catalog: wrap(handleGetProductCatalog),
     finstack_get_vendors: wrap(handleGetVendors),
 };

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

@@ -0,0 +1,10 @@
+import { type ProductStatus, type ProductVendor } from '../api/product.api.js';
+interface GetProductCatalogArgs {
+    code?: string;
+    status?: ProductStatus;
+    vendor?: ProductVendor;
+    query?: string;
+    environment?: string;
+}
+export declare function handleGetProductCatalog(args: GetProductCatalogArgs): Promise<unknown>;
+export {};

package/dist/handlers/product.handler.js

@@ -0,0 +1,14 @@
+/**
+ * Product catalog handlers
+ */
+import { getClient } from '../api/client.js';
+import { getProductCatalog, } from '../api/product.api.js';
+export async function handleGetProductCatalog(args) {
+    const client = getClient(args.environment ?? 'prod');
+    return getProductCatalog(client, {
+        code: args.code,
+        status: args.status,
+        vendor: args.vendor,
+        query: args.query,
+    });
+}

package/dist/tools/index.js

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

package/dist/tools/product.tools.d.ts

@@ -0,0 +1,2 @@
+import type { ToolDefinition } from '../types/tool.types.js';
+export declare const productTools: ToolDefinition[];

package/dist/tools/product.tools.js

@@ -0,0 +1,38 @@
+/**
+ * Product catalog tool definitions
+ */
+import { PRODUCT_VENDORS } from '../api/product.api.js';
+export const productTools = [
+    {
+        name: 'finstack_get_product_catalog',
+        description: "The CRS product catalog — every product CRS sells (not a specific customer's configuration; for what one customer has, use finstack_get_customer_pricing_config). Use when asked what a product code (e.g. EXP1001, TUC2000) is, what products exist for a bureau/vendor, whether a product is hard or soft pull / FCRA, its base cost or default list price, which platforms it is on (mcl, crs, b2c, liq, bureau_direct), its add-ons (score models etc. with bureau service codes and base costs), its permissible purposes, or whether it is active or terminated. Each product includes: code, status (active/terminated) and termination_date, type, category, vendor, public_name and private_name, description, plan_includes, base_cost and default_price (decimal strings; default_price = base_cost x 2), inquiry (hard/soft/not_applicable), fcra, on_path, platforms, parent_codes, product_codes, warning_notice, add_ons[], permissible_purposes[]. Filters: `code` (exact, one or comma-separated), `status`, `vendor` are applied server-side; `query` is a free-text AND-match across code, names, description, labels, add-on names/codes and permissible purposes. With no filters the whole catalog is returned (can be large — prefer a filter). Does not include subscriber codes or internal notes. Backed by the mware-portal chatbase product_catalog endpoint.",
+        inputSchema: {
+            type: 'object',
+            properties: {
+                code: {
+                    type: 'string',
+                    description: 'Exact product code, or a comma-separated list — e.g. "EXP1001" or "EXP1001,TUC2000".',
+                },
+                status: {
+                    type: 'string',
+                    enum: ['active', 'terminated'],
+                    description: 'Only products with this status. Omit for both.',
+                },
+                vendor: {
+                    type: 'string',
+                    enum: [...PRODUCT_VENDORS],
+                    description: 'Only products from this vendor. exp=Experian, tuc=TransUnion, eqf=Equifax, lnr=LexisNexis, fico=FICO, crs=CRS; others as named.',
+                },
+                query: {
+                    type: 'string',
+                    description: "Free-text keywords, all of which must match (case-insensitive) across code, public/private name, description, type/category/vendor labels, add-on names/codes and permissible purposes. e.g. 'credit profile', 'FICO 9', 'tenant'.",
+                },
+                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.7.0-92ce169",
+	"version": "0.8.0-8468b06",
 	"description": "MCP server for Finstack",
 	"type": "module",
 	"main": "dist/index.js",