@crscreditapi/finstack-mcp-server 0.7.0-92ce169 → 0.9.0-6062c00

package/README.md

@@ -16,6 +16,8 @@ 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_cop_ai_analytics` | Credit Order Pro AI summary & chat usage for a trailing window: totals, per-customer activity (reports, summaries, opens, questions, ratings, Bedrock cost) and who currently has the feature enabled. |
+| `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 +182,21 @@ 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_cop_ai_analytics`
+
+```json
+{ "days": 30 }
+```
+
+`days` is optional (default `7`, clamped server-side to 1–92; the window ends yesterday). Returns `{period, totals, customers, enabled_customers}`. `customers[]` lists every account with activity in the window, most reports first: `reports` are successful credit reports on products carrying the AI add-on, `summaries` the AI summaries generated (`precomputed` of them right after the order), `opened` how many a user actually looked at, `questions` chat messages answered with `up`/`down` ratings, and `cost` the Bedrock spend in USD. `enabled_customers[]` is who has the feature on right now (id, name, product codes, `enabled_at`), regardless of activity. Counts only; report and chat content is never exposed.
+### `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/copai.api.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Credit Order Pro AI summary & chat usage against the mware-portal API.
+ *
+ * Same numbers the #cop-ai-usage Slack digest posts: per customer, the
+ * successful credit reports on products that carry the AI add-on, the
+ * summaries generated (precomputed vs on click), how many were opened,
+ * chat questions with thumbs up/down, and the Bedrock cost in USD. Counts
+ * only — the portal never exposes report or chat content here.
+ */
+import type { ApiClient } from './client.js';
+export interface CopAiCustomerRow {
+    customer: string;
+    reports: number;
+    summaries: number;
+    precomputed: number;
+    opened: number;
+    questions: number;
+    up: number;
+    down: number;
+    /** Bedrock cost in USD (Haiku 4.5 list price). */
+    cost: number;
+}
+export interface CopAiTotals {
+    reports: number;
+    summaries: number;
+    precomputed: number;
+    opened: number;
+    /** Opened summaries as a percentage of generated summaries. */
+    opened_pct: number;
+    questions: number;
+    up: number;
+    down: number;
+    cost: number;
+    /** Customers with at least one enabled report in the window. */
+    customers: number;
+}
+export interface CopAiEnabledCustomer {
+    id: number;
+    name: string;
+    /** Billing product codes carrying the add-on, e.g. ["EXP1101", "TUC1101"]. */
+    products: string[];
+    enabled_at: string | null;
+}
+export interface CopAiAnalyticsDigest {
+    period: {
+        start_date: string;
+        end_date: string;
+        days: number;
+    };
+    totals: CopAiTotals;
+    /** Every customer with activity in the window, most reports first. */
+    customers: CopAiCustomerRow[];
+    /** Who has the feature switched on right now, regardless of activity. */
+    enabled_customers: CopAiEnabledCustomer[];
+}
+export declare function getCopAiAnalytics(client: ApiClient, days?: number): Promise<CopAiAnalyticsDigest>;

package/dist/api/copai.api.js

@@ -0,0 +1,15 @@
+export async function getCopAiAnalytics(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/cop_ai_analytics?${params}`, { 'X-Chatbase-Secret': secret });
+    if (response.status !== 'success' || !response.data) {
+        throw new Error(response.message || 'Failed to fetch Credit Order Pro AI analytics');
+    }
+    return response.data;
+}

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

@@ -0,0 +1,6 @@
+interface GetCopAiAnalyticsArgs {
+    days?: number;
+    environment?: string;
+}
+export declare function handleGetCopAiAnalytics(args: GetCopAiAnalyticsArgs): Promise<unknown>;
+export {};

package/dist/handlers/copai.handler.js

@@ -0,0 +1,9 @@
+/**
+ * Credit Order Pro AI tool handlers
+ */
+import { getClient } from '../api/client.js';
+import { getCopAiAnalytics } from '../api/copai.api.js';
+export async function handleGetCopAiAnalytics(args) {
+    const client = getClient(args.environment ?? 'prod');
+    return getCopAiAnalytics(client, args.days);
+}

package/dist/handlers/index.js

@@ -1,5 +1,7 @@
+import { handleGetCopAiAnalytics } from './copai.handler.js';
 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 +17,7 @@ export const handlers = {
     finstack_get_customer_users: wrap(handleGetCustomerUsers),
     finstack_get_leadiq_analytics: wrap(handleGetLeadiqAnalytics),
     finstack_get_leadiq_customer: wrap(handleGetLeadiqCustomer),
+    finstack_get_cop_ai_analytics: wrap(handleGetCopAiAnalytics),
+    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/copai.tools.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Credit Order Pro AI summary & chat tool definitions
+ */
+import type { ToolDefinition } from '../types/tool.types.js';
+export declare const copAiTools: ToolDefinition[];

package/dist/tools/copai.tools.js

@@ -0,0 +1,22 @@
+export const copAiTools = [
+    {
+        name: 'finstack_get_cop_ai_analytics',
+        description: 'Usage of the Credit Order Pro AI summary & chat (early-access feature on the customer portal) for a trailing window. Returns totals (reports on AI-enabled products, summaries generated and how many were precomputed, opened count and opened_pct, chat questions, thumbs up/down, Bedrock cost in USD, active customers), customers[] — every account with activity in the window, most reports first, with the same fields — and enabled_customers[] — who currently has the add-on switched on, with their product codes and when it was enabled. Use for questions like "how is the AI summary beta going" (totals + customers[]), "who has enabled AI summary" (enabled_customers[]), "is anyone using the chat" (questions), or "what does the AI feature cost us per week" (totals.cost). Counts only; report and chat content is never exposed.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                days: {
+                    type: 'number',
+                    description: 'Trailing window in days ending yesterday, 1-92 (default 7; values outside the range are clamped server-side). Use 30 for "last month".',
+                    minimum: 1,
+                    maximum: 92,
+                },
+                environment: {
+                    type: 'string',
+                    description: 'Target environment: "prod" (default) or "dev"',
+                    enum: ['dev', 'prod'],
+                },
+            },
+        },
+    },
+];

package/dist/tools/index.js

@@ -1,8 +1,12 @@
+import { copAiTools } from './copai.tools.js';
 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,
+    ...copAiTools,
     ...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.9.0-6062c00",
 	"description": "MCP server for Finstack",
 	"type": "module",
 	"main": "dist/index.js",