@crscreditapi/finstack-mcp-server 0.9.0-6062c00 → 0.10.0-80b4ec3

package/.env.example

@@ -11,3 +11,8 @@ FINSTACK_PROD_BASE_URL=https://portal.example.com
 
 # Shared secret for the mware-portal chatbase endpoints (X-Chatbase-Secret header)
 FINSTACK_CHATBASE_SECRET=
+
+# Support Autopsy observability: insert one row per tool call into the shared tool_calls table
+# (n8n Postgres). Leave unset to emit a JSON log line instead. TOOL_LOG=off disables both.
+TOOL_CALLS_DATABASE_URL=
+# SSL is on by default (no sslmode needed in the URL). TOOL_CALLS_PGSSL=off for a local DB.

package/README.md

@@ -14,6 +14,10 @@ MCP server exposing CRS B2B (Finstack) customer data over the [Model Context Pro
 | `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_users` | Portal users and no-portal-access contacts for one customer, with names, emails, phones, roles (labelled as on the portal Users tab), owner flag, invitation status and lock/MFA state. The only tool that returns people for an account. |
 | `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_product_customers` | Which customers hold a product, by billing product code (e.g. `TUC1002`). Paged over customers; each row carries its subscription status and add-ons. |
+| `finstack_get_add_on_customers` | Which customers have an add-on (by add-on code, e.g. `CRS1002`) attached to at least one product, and on which products. Paged. |
+| `finstack_get_customer_products` | The products one customer holds with subscription status, platform, activation date and attached add-ons. No prices. |
+| `finstack_get_customer_add_ons` | The add-ons one customer has, each with the products it is attached to. |
 | `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. |
@@ -166,6 +170,38 @@ All parameters optional. `page` defaults to `1`; `per_page` defaults to `500`, c
 
 `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_product_customers`
+
+```json
+{ "code": "TUC1002", "status": "activated", "page": 1, "per_page": 500 }
+```
+
+`code` (required) is an exact billing product code. `status` (optional) is one subscription status or a comma list / array of them — `not_categorized`, `activated`, `in_review`, `disabled`, `terminating`, `deactivated`, `quoted`, `archived`; omit it and every status comes back, each row labelled. `page` defaults to `1`; `per_page` defaults to `500`, capped at `1000`. Returns `{product: {code, name, private_name, status}, page, per_page, total_count, total_pages, customers: [...]}` — `total_count` counts customers, not subscriptions, and each customer carries `products[]`, its subscriptions to that product (one per platform, possibly more than one). Each product row has `code`, `name`, `private_name`, `vendor`, `category`, `status`, `enabled`, `platform`, `format`, `activated_at`, `part_of_merge`, `part_of_bundle` and `add_ons[{code, name}]`. Unknown code → 404, unknown status → 400. Backed by the MCP-only `customers_by_product` chatbase endpoint.
+
+### `finstack_get_add_on_customers`
+
+```json
+{ "code": "CRS1002", "status": "activated" }
+```
+
+Same parameters and paging as `finstack_get_product_customers`, keyed by add-on code. Returns `{add_on: {code, name, private_name, status, category, category_label}, page, per_page, total_count, total_pages, customers: [...]}`; each customer's `products[]` lists only the products carrying this add-on. `add_on.status` is `active`, `inactive` or `null` (null means active). `status` filters on the subscription status of the product the add-on is attached to.
+
+### `finstack_get_customer_products`
+
+```json
+{ "customer_code": "CID18068", "status": "activated,in_review" }
+```
+
+Identify the customer with either `customer_code` or `user_id`. Returns `{customer: {customer_code, name, status}, count, products: [...]}` ordered by product code, with the product rows described above. No prices — use `finstack_get_customer_pricing_config` for those.
+
+### `finstack_get_customer_add_ons`
+
+```json
+{ "customer_code": "CID18068" }
+```
+
+Identify the customer with either `customer_code` or `user_id`. Returns `{customer, count, add_ons: [...]}` where `count` is the number of distinct add-ons and each add-on carries `products[]`, the product rows it is attached to (without their own `add_ons` list). `status` filters on the status of the product the add-on is attached to.
+
 ### `finstack_get_leadiq_analytics`
 
 ```json

package/dist/api/product_lookup.api.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Product / add-on holding lookups against the mware-portal chatbase API.
+ *
+ * Four read-only endpoints answer "who has what" in both directions:
+ *   customers_by_product, customers_by_add_on (paged over customers)
+ *   customer_products, customer_add_ons (one customer)
+ *
+ * They read BillingProductCustomer rows (a customer's subscription to a
+ * product) and the add-ons attached to them. No prices — that is
+ * customer_pricing_config.
+ */
+import type { ApiClient } from './client.js';
+/** Product subscription status on a BillingProductCustomer row. */
+export type SubscriptionStatus = 'not_categorized' | 'activated' | 'in_review' | 'disabled' | 'terminating' | 'deactivated' | 'quoted' | 'archived';
+export declare const SUBSCRIPTION_STATUSES: SubscriptionStatus[];
+export interface AddOnRef {
+    code: string;
+    name: string;
+}
+/** One customer's subscription to a product. */
+export interface ProductSubscription {
+    code: string;
+    name: string;
+    private_name: string | null;
+    vendor: string | null;
+    category: string | null;
+    status: SubscriptionStatus;
+    enabled: boolean;
+    platform: string | null;
+    format: string | null;
+    activated_at: string | null;
+    /** true = component row of a merge product rather than a product sold on its own */
+    part_of_merge: boolean;
+    /** true = component row of a bundle */
+    part_of_bundle: boolean;
+    add_ons?: AddOnRef[];
+}
+export interface LookupCustomer {
+    customer_code: string | null;
+    name: string;
+    status: string | null;
+}
+export interface ProductRef {
+    code: string;
+    name: string;
+    private_name: string | null;
+    status: 'active' | 'terminated' | string;
+}
+export interface AddOnDetail {
+    code: string;
+    name: string;
+    private_name: string | null;
+    /** active | inactive | null (null = active) */
+    status: string | null;
+    category: string | null;
+    category_label: string | null;
+}
+interface CustomersPage {
+    page: number;
+    per_page: number;
+    /** customers, not subscriptions */
+    total_count: number;
+    total_pages: number;
+    customers: Array<LookupCustomer & {
+        products: ProductSubscription[];
+    }>;
+}
+export interface ProductCustomersPage extends CustomersPage {
+    product: ProductRef;
+}
+export interface AddOnCustomersPage extends CustomersPage {
+    add_on: AddOnDetail;
+}
+export interface CustomerProducts {
+    customer: LookupCustomer;
+    count: number;
+    products: ProductSubscription[];
+}
+export interface CustomerAddOns {
+    customer: LookupCustomer;
+    /** distinct add-ons */
+    count: number;
+    add_ons: Array<AddOnDetail & {
+        products: ProductSubscription[];
+    }>;
+}
+/**
+ * Normalize the status filter to the comma list the endpoint expects.
+ * Accepts a single value, a comma list, or an array; returns undefined when
+ * empty so every status comes back.
+ */
+export declare function normalizeStatusFilter(status?: string | string[]): string | undefined;
+/** Which customers hold a product (paged over customers). */
+export declare function getProductCustomers(client: ApiClient, args: {
+    code: string;
+    status?: string | string[];
+    page?: number;
+    perPage?: number;
+}): Promise<ProductCustomersPage>;
+/** Which customers have an add-on attached to at least one product (paged). */
+export declare function getAddOnCustomers(client: ApiClient, args: {
+    code: string;
+    status?: string | string[];
+    page?: number;
+    perPage?: number;
+}): Promise<AddOnCustomersPage>;
+/** The products one customer holds, each with status and add-ons. */
+export declare function getCustomerProducts(client: ApiClient, args: {
+    customerCode?: string;
+    userId?: string;
+    status?: string | string[];
+}): Promise<CustomerProducts>;
+/** The add-ons one customer has, each with the products it is attached to. */
+export declare function getCustomerAddOns(client: ApiClient, args: {
+    customerCode?: string;
+    userId?: string;
+    status?: string | string[];
+}): Promise<CustomerAddOns>;
+export {};

package/dist/api/product_lookup.api.js

@@ -0,0 +1,79 @@
+export const SUBSCRIPTION_STATUSES = [
+    'not_categorized',
+    'activated',
+    'in_review',
+    'disabled',
+    'terminating',
+    'deactivated',
+    'quoted',
+    'archived',
+];
+function chatbaseSecret() {
+    const secret = process.env.FINSTACK_CHATBASE_SECRET;
+    if (!secret) {
+        throw new Error('FINSTACK_CHATBASE_SECRET must be set');
+    }
+    return secret;
+}
+/**
+ * Normalize the status filter to the comma list the endpoint expects.
+ * Accepts a single value, a comma list, or an array; returns undefined when
+ * empty so every status comes back.
+ */
+export function normalizeStatusFilter(status) {
+    const raw = Array.isArray(status) ? status : (status ?? '').split(',');
+    const values = raw.map((s) => s.trim()).filter(Boolean);
+    return values.length ? values.join(',') : undefined;
+}
+async function lookup(client, action, params, failureMessage) {
+    const response = await client.get(`/api/v1/chatbase/${action}?${params}`, { 'X-Chatbase-Secret': chatbaseSecret() });
+    if (response.status !== 'success' || !response.data) {
+        throw new Error(response.message || failureMessage);
+    }
+    return response.data;
+}
+function pagedParams(args) {
+    const code = args.code?.trim();
+    if (!code) {
+        throw new Error('code is required');
+    }
+    const params = new URLSearchParams({ code });
+    const status = normalizeStatusFilter(args.status);
+    if (status)
+        params.set('status', status);
+    if (args.page !== undefined)
+        params.set('page', String(args.page));
+    if (args.perPage !== undefined)
+        params.set('per_page', String(args.perPage));
+    return params;
+}
+function customerParams(args) {
+    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);
+    const status = normalizeStatusFilter(args.status);
+    if (status)
+        params.set('status', status);
+    return params;
+}
+/** Which customers hold a product (paged over customers). */
+export async function getProductCustomers(client, args) {
+    return lookup(client, 'customers_by_product', pagedParams(args), 'Failed to fetch customers by product');
+}
+/** Which customers have an add-on attached to at least one product (paged). */
+export async function getAddOnCustomers(client, args) {
+    return lookup(client, 'customers_by_add_on', pagedParams(args), 'Failed to fetch customers by add-on');
+}
+/** The products one customer holds, each with status and add-ons. */
+export async function getCustomerProducts(client, args) {
+    return lookup(client, 'customer_products', customerParams(args), 'Failed to fetch customer products');
+}
+/** The add-ons one customer has, each with the products it is attached to. */
+export async function getCustomerAddOns(client, args) {
+    return lookup(client, 'customer_add_ons', customerParams(args), 'Failed to fetch customer add-ons');
+}

package/dist/handlers/index.js

@@ -2,6 +2,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 { handleGetAddOnCustomers, handleGetCustomerAddOns, handleGetCustomerProducts, handleGetProductCustomers, } from './product_lookup.handler.js';
 import { handleGetVendors } from './vendor.handler.js';
 const wrap = (fn) => {
     return async (args) => fn(args);
@@ -19,5 +20,9 @@ export const handlers = {
     finstack_get_leadiq_customer: wrap(handleGetLeadiqCustomer),
     finstack_get_cop_ai_analytics: wrap(handleGetCopAiAnalytics),
     finstack_get_product_catalog: wrap(handleGetProductCatalog),
+    finstack_get_product_customers: wrap(handleGetProductCustomers),
+    finstack_get_add_on_customers: wrap(handleGetAddOnCustomers),
+    finstack_get_customer_products: wrap(handleGetCustomerProducts),
+    finstack_get_customer_add_ons: wrap(handleGetCustomerAddOns),
     finstack_get_vendors: wrap(handleGetVendors),
 };

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

@@ -0,0 +1,18 @@
+interface ByCodeArgs {
+    code: string;
+    status?: string | string[];
+    page?: number;
+    per_page?: number;
+    environment?: string;
+}
+interface ByCustomerArgs {
+    customer_code?: string;
+    user_id?: string;
+    status?: string | string[];
+    environment?: string;
+}
+export declare function handleGetProductCustomers(args: ByCodeArgs): Promise<unknown>;
+export declare function handleGetAddOnCustomers(args: ByCodeArgs): Promise<unknown>;
+export declare function handleGetCustomerProducts(args: ByCustomerArgs): Promise<unknown>;
+export declare function handleGetCustomerAddOns(args: ByCustomerArgs): Promise<unknown>;
+export {};

package/dist/handlers/product_lookup.handler.js

@@ -0,0 +1,39 @@
+/**
+ * Product / add-on lookup handlers
+ */
+import { getClient } from '../api/client.js';
+import { getAddOnCustomers, getCustomerAddOns, getCustomerProducts, getProductCustomers, } from '../api/product_lookup.api.js';
+export async function handleGetProductCustomers(args) {
+    const client = getClient(args.environment ?? 'prod');
+    return getProductCustomers(client, {
+        code: args.code,
+        status: args.status,
+        page: args.page,
+        perPage: args.per_page,
+    });
+}
+export async function handleGetAddOnCustomers(args) {
+    const client = getClient(args.environment ?? 'prod');
+    return getAddOnCustomers(client, {
+        code: args.code,
+        status: args.status,
+        page: args.page,
+        perPage: args.per_page,
+    });
+}
+export async function handleGetCustomerProducts(args) {
+    const client = getClient(args.environment ?? 'prod');
+    return getCustomerProducts(client, {
+        customerCode: args.customer_code,
+        userId: args.user_id,
+        status: args.status,
+    });
+}
+export async function handleGetCustomerAddOns(args) {
+    const client = getClient(args.environment ?? 'prod');
+    return getCustomerAddOns(client, {
+        customerCode: args.customer_code,
+        userId: args.user_id,
+        status: args.status,
+    });
+}

package/dist/server.js

@@ -4,6 +4,7 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, ErrorCode, McpError, } from '@modelcontextprotocol/sdk/types.js';
 import { resources, getResourceContent } from './resources.js';
+import { logToolCall } from './toolLog.js';
 export function createServer(tools, handlers) {
     const server = new Server({ name: 'finstack-mcp-server', version: '0.1.0' }, { capabilities: { tools: {}, resources: {} } });
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
@@ -15,16 +16,21 @@ export function createServer(tools, handlers) {
         if (!handler) {
             throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
         }
+        const startedAt = Date.now();
+        const safeArgs = (args || {});
         try {
-            const result = await handler((args || {}));
+            const result = await handler(safeArgs);
+            const text = JSON.stringify(result, null, 2);
+            logToolCall({ server: 'finstack', tool: name, args: safeArgs, durationMs: Date.now() - startedAt, ok: true, resultText: text });
             return {
                 content: [
-                    { type: 'text', text: JSON.stringify(result, null, 2) },
+                    { type: 'text', text },
                 ],
             };
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
+            logToolCall({ server: 'finstack', tool: name, args: safeArgs, durationMs: Date.now() - startedAt, ok: false, errorMessage: message });
             return {
                 content: [{ type: 'text', text: `Error: ${message}` }],
                 isError: true,

package/dist/toolLog.d.ts

@@ -0,0 +1,33 @@
+export interface ToolLogEntry {
+    server: string;
+    tool: string;
+    args: Record<string, unknown>;
+    durationMs: number;
+    ok: boolean;
+    resultText?: string;
+    errorMessage?: string;
+    traceId?: string | null;
+}
+export declare function hashArgs(args: Record<string, unknown>): string;
+/** Pull an HTTP status out of upstream error text such as "GET /x failed: 404 - ..." */
+export declare function upstreamStatusFrom(message: string | undefined): number | null;
+export declare function toRecord(e: ToolLogEntry): {
+    trace_id: string | null;
+    channel: string;
+    agent: string;
+    server: string;
+    tool: string;
+    args_hash: string;
+    args_summary: {
+        keys: string[];
+    };
+    started_at: string;
+    duration_ms: number;
+    ok: boolean;
+    error_class: string | null;
+    error_message: string | null;
+    result_bytes: number;
+    truncated: boolean;
+    upstream_status: number | null;
+};
+export declare function logToolCall(e: ToolLogEntry): void;

package/dist/toolLog.js

@@ -0,0 +1,96 @@
+/**
+ * One record per tool call (Support Autopsy observability, CREM-110).
+ *
+ * If TOOL_CALLS_DATABASE_URL is set, each call is inserted into the shared `tool_calls`
+ * table (same table the n8n agents write to), fire-and-forget: a slow or unreachable
+ * database never delays or fails a tool call. Without the URL, one JSON line is written
+ * instead (stdout in http mode, stderr in stdio mode where stdout is the MCP channel).
+ *
+ * Argument values are never stored or logged, only a hash and the key names.
+ * Disable entirely with TOOL_LOG=off.
+ */
+import { createHash } from 'node:crypto';
+import pg from 'pg';
+const ENABLED = (process.env.TOOL_LOG || 'on').toLowerCase() !== 'off';
+// sslmode is stripped from the URL on purpose: pg >= 8.16 treats sslmode=require as
+// verify-full and the RDS certificate chain is not in the container's trust store. SSL is
+// on by default without chain verification (traffic stays inside the VPC);
+// TOOL_CALLS_PGSSL=off disables it for a local database.
+const DB_URL = (process.env.TOOL_CALLS_DATABASE_URL || '').replace(/[?&]sslmode=[^&]+/, '').replace(/\?$/, '');
+const DB_SSL = (process.env.TOOL_CALLS_PGSSL || 'on').toLowerCase() === 'off' ? false : { rejectUnauthorized: false };
+const STREAM = (process.env.MCP_TRANSPORT || 'stdio') === 'http' ? process.stdout : process.stderr;
+let pool = null;
+let lastDbErrorAt = 0;
+function getPool() {
+    if (!DB_URL)
+        return null;
+    if (!pool) {
+        pool = new pg.Pool({
+            connectionString: DB_URL,
+            max: 2,
+            idleTimeoutMillis: 30_000,
+            connectionTimeoutMillis: 3_000,
+            ssl: DB_SSL,
+        });
+        pool.on('error', (err) => warnDb(err));
+    }
+    return pool;
+}
+function warnDb(err) {
+    const now = Date.now();
+    if (now - lastDbErrorAt < 60_000)
+        return; // at most one warning per minute
+    lastDbErrorAt = now;
+    const msg = err instanceof Error ? err.message : String(err);
+    process.stderr.write(`[toolLog] tool_calls insert failed: ${msg}\n`);
+}
+export function hashArgs(args) {
+    const canonical = JSON.stringify(args, Object.keys(args).sort());
+    return createHash('sha1').update(canonical).digest('hex').slice(0, 16);
+}
+/** Pull an HTTP status out of upstream error text such as "GET /x failed: 404 - ..." */
+export function upstreamStatusFrom(message) {
+    if (!message)
+        return null;
+    const m = message.match(/\b(?:failed|status|HTTP)\D{0,10}(\d{3})\b/i);
+    return m ? Number(m[1]) : null;
+}
+export function toRecord(e) {
+    const durationMs = Math.round(e.durationMs);
+    return {
+        trace_id: e.traceId ?? null,
+        channel: 'mcp',
+        agent: 'mcp_server',
+        server: e.server,
+        tool: e.tool,
+        args_hash: hashArgs(e.args),
+        args_summary: { keys: Object.keys(e.args) },
+        started_at: new Date(Date.now() - durationMs).toISOString(),
+        duration_ms: durationMs,
+        ok: e.ok,
+        error_class: e.ok ? null : 'tool_error',
+        error_message: e.ok ? null : (e.errorMessage || '').slice(0, 200),
+        result_bytes: e.resultText ? Buffer.byteLength(e.resultText) : 0,
+        truncated: e.resultText ? /"truncated"\s*:\s*true/.test(e.resultText) : false,
+        upstream_status: e.ok ? null : upstreamStatusFrom(e.errorMessage),
+    };
+}
+const INSERT = `INSERT INTO tool_calls
+  (trace_id, channel, agent, server, tool, args_hash, args_summary, started_at,
+   duration_ms, ok, error_class, error_message, result_bytes, truncated, upstream_status)
+  VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9,$10,$11,$12,$13,$14,$15)`;
+export function logToolCall(e) {
+    if (!ENABLED)
+        return;
+    const r = toRecord(e);
+    const p = getPool();
+    if (!p) {
+        STREAM.write(JSON.stringify({ ts: new Date().toISOString(), kind: 'tool_call', ...r }) + '\n');
+        return;
+    }
+    p.query(INSERT, [
+        r.trace_id, r.channel, r.agent, r.server, r.tool, r.args_hash, JSON.stringify(r.args_summary),
+        r.started_at, r.duration_ms, r.ok, r.error_class, r.error_message, r.result_bytes,
+        r.truncated, r.upstream_status,
+    ]).catch(warnDb);
+}

package/dist/tools/index.js

@@ -2,11 +2,13 @@ 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 { productLookupTools } from './product_lookup.tools.js';
 import { vendorTools } from './vendor.tools.js';
 export const tools = [
     ...customerTools,
     ...copAiTools,
     ...leadiqTools,
     ...productTools,
+    ...productLookupTools,
     ...vendorTools,
 ];

package/dist/tools/product.tools.js

@@ -5,7 +5,7 @@ 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.",
+        description: "The CRS product catalog — every product CRS sells (not a specific customer's configuration; for what one customer has, use finstack_get_customer_products or finstack_get_customer_pricing_config; for which customers hold a product, finstack_get_product_customers). 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: {

package/dist/tools/product_lookup.tools.d.ts

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

package/dist/tools/product_lookup.tools.js

@@ -0,0 +1,102 @@
+/**
+ * Product / add-on lookup tool definitions
+ */
+import { SUBSCRIPTION_STATUSES } from '../api/product_lookup.api.js';
+const STATUS_LIST = SUBSCRIPTION_STATUSES.join(', ');
+const statusProperty = {
+    type: 'string',
+    description: `Only subscriptions in these statuses — one value or a comma list, e.g. "activated" or "activated,in_review". Values: ${STATUS_LIST}. Omit for every status (each row carries its own status). For "who currently has X" use "activated".`,
+};
+const environmentProperty = {
+    type: 'string',
+    description: 'Target environment: "prod" (default) or "dev"',
+    enum: ['dev', 'prod'],
+};
+const pageProperty = {
+    type: 'number',
+    description: 'Page number, 1-indexed. Default 1.',
+    minimum: 1,
+};
+const perPageProperty = {
+    type: 'number',
+    description: 'Customers per page. Default 500, capped at 1000.',
+    minimum: 1,
+    maximum: 1000,
+};
+const PRODUCT_ROW_DOC = 'Each product row has code, name, private_name, vendor, category, status (subscription status), enabled, platform, format, activated_at, part_of_merge / part_of_bundle (true = component row of a merge or bundle rather than a product sold on its own), and add_ons[{code,name}].';
+export const productLookupTools = [
+    {
+        name: 'finstack_get_product_customers',
+        description: `Which B2B customers hold a given product (by billing product code, e.g. TUC1002 = TransUnion Bankruptcy, EXP1001 = Experian Credit Profile). Use for "which customers have / use / are subscribed to product X" — do NOT loop finstack_get_customer_summary over the cohort for that. Requires the exact product code; if the user gives a product name, resolve the code with finstack_get_product_catalog first and pass it here. Paged over customers (default 500, max 1000): read total_pages and fetch the rest. Returns {product:{code,name,private_name,status active|terminated}, page, per_page, total_count, total_pages, customers[{customer_code,name,status,products[]}]} where products[] are that customer's subscriptions to this product (can be more than one, e.g. per platform). ${PRODUCT_ROW_DOC} Without a status filter every subscription status is returned (quoted, activated, deactivated...), so filter with status="activated" for current holders. Errors: 404 unknown product code, 400 unknown status. No prices.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                code: {
+                    type: 'string',
+                    description: 'Billing product code, exact match — e.g. "EXP1001", "TUC1002".',
+                },
+                status: statusProperty,
+                page: pageProperty,
+                per_page: perPageProperty,
+                environment: environmentProperty,
+            },
+            required: ['code'],
+        },
+    },
+    {
+        name: 'finstack_get_add_on_customers',
+        description: `Which B2B customers have a given add-on (by add-on code, e.g. CRS1002 = Credit Order Pro) attached to at least one of their products, and on which products. Use for "which customers have add-on X / feature X enabled". Requires the exact add-on code. Paged over customers (default 500, max 1000): read total_pages and fetch the rest. Returns {add_on:{code,name,private_name,status active|inactive|null (null = active),category,category_label}, page, per_page, total_count, total_pages, customers[{customer_code,name,status,products[]}]} where products[] are only the products carrying this add-on. ${PRODUCT_ROW_DOC} status filters on the subscription status of the product the add-on is attached to. Errors: 404 unknown add-on code, 400 unknown status.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                code: {
+                    type: 'string',
+                    description: 'Add-on code, exact match — e.g. "CRS1002".',
+                },
+                status: statusProperty,
+                page: pageProperty,
+                per_page: perPageProperty,
+                environment: environmentProperty,
+            },
+            required: ['code'],
+        },
+    },
+    {
+        name: 'finstack_get_customer_products',
+        description: `The products one B2B customer holds, each with its subscription status and attached add-ons — the lean answer to "what products does customer X have / is X subscribed to Y / when was Y activated". Prefer this over finstack_get_customer_pricing_config when prices are not needed, and over finstack_get_customer_summary when you need codes, statuses beyond activated/not_activated, activation dates, or add-ons. Returns {customer:{customer_code,name,status}, count, products[]} ordered by product code. ${PRODUCT_ROW_DOC} Without a status filter every status is returned (quoted, deactivated...), so check each row's status before saying the customer "has" a product. Identify the customer with EITHER customer_code OR user_id; an unknown customer returns 401.`,
+        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.',
+                },
+                status: statusProperty,
+                environment: environmentProperty,
+            },
+        },
+    },
+    {
+        name: 'finstack_get_customer_add_ons',
+        description: `The add-ons one B2B customer has, each with the products it is attached to — the answer to "which add-ons / features does customer X have" or "does X have add-on Y, on which product". Returns {customer:{customer_code,name,status}, count (distinct add-ons), add_ons[{code,name,private_name,status active|inactive|null (null = active),category,category_label,products[]}]} ordered by add-on code; products[] rows are the product rows without their own add_ons list. status filters on the subscription status of the product the add-on is attached to. Identify the customer with EITHER customer_code OR user_id; an unknown customer returns 401.`,
+        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.',
+                },
+                status: statusProperty,
+                environment: environmentProperty,
+            },
+        },
+    },
+];

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@crscreditapi/finstack-mcp-server",
-	"version": "0.9.0-6062c00",
+	"version": "0.10.0-80b4ec3",
 	"description": "MCP server for Finstack",
 	"type": "module",
 	"main": "dist/index.js",
@@ -32,12 +32,14 @@
 		"@modelcontextprotocol/sdk": "^1.0.0",
 		"dotenv": "^16.3.0",
 		"express": "^5.2.1",
-		"pdf-parse": "^2.4.5"
+		"pdf-parse": "^2.4.5",
+		"pg": "^8.23.1"
 	},
 	"devDependencies": {
 		"@types/express": "^5.0.6",
 		"@types/node": "^20.11.0",
 		"@types/pdf-parse": "^1.1.5",
+		"@types/pg": "^8.23.1",
 		"typescript": "^5.3.0"
 	}
 }