@crscreditapi/finstack-mcp-server 0.8.0-8468b06 → 0.9.0-6062c00

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_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. |
 
@@ -181,6 +182,13 @@ 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

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/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,3 +1,4 @@
+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';
@@ -16,6 +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/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,9 +1,11 @@
+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/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@crscreditapi/finstack-mcp-server",
-	"version": "0.8.0-8468b06",
+	"version": "0.9.0-6062c00",
 	"description": "MCP server for Finstack",
 	"type": "module",
 	"main": "dist/index.js",