@crscreditapi/finstack-mcp-server 0.6.0-06bd3a8 → 0.7.0-3660044

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_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_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. |
@@ -139,6 +140,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_users`
+
+```json
+{ "customer_code": "CID18068" }
+```
+
+Identify the customer with either `customer_code` or `user_id`. Returns `{customer, users_count, users: [...], contacts_count, contacts: [...]}`. Each `users[]` row is a portal login: `id`, `name`, `email`, `phone`, `title`, `roles` (customer-facing role names), `role_labels` (as shown on the portal Users tab — `Admin (owner)`, `Admin`, `Developer`, `Agent`, `Billing`, `Main billing contact`, `Generic`), `is_owner`, `status` (`active` / `invited` / `not_invited`), `locked`, `mfa_enabled`, `sign_in_count`, and sign-in / invitation timestamps; the owner comes first, then alphabetical. `contacts[]` are the "Contacts (No portal access)" rows: `id`, `name`, `email`, `phone`, `title`, `roles`. This payload carries PII by design and is backed by the MCP-only `customer_users` chatbase endpoint (mware-portal); credentials and tokens are never included.
+
 ### `finstack_get_customer_cohort`
 
 ```json

package/dist/api/customer.api.d.ts

@@ -187,3 +187,46 @@ export declare function getCustomerCohort(client: ApiClient, args: {
     status?: string;
     stage?: string;
 }): Promise<CustomerCohortPage>;
+export interface CustomerPortalUser {
+    id: number;
+    name: string;
+    email: string;
+    phone: string | null;
+    title: string | null;
+    /** Customer-facing rolify role names, e.g. ["customer"], ["developer"]. Empty = generic user. */
+    roles: string[];
+    /** Same labels the portal Users tab shows: "Admin (owner)", "Admin", "Developer", "Agent", "Billing", "Main billing contact", "Generic". */
+    role_labels: string[];
+    is_owner: boolean;
+    status: 'active' | 'invited' | 'not_invited';
+    locked: boolean;
+    mfa_enabled: boolean;
+    sign_in_count: number;
+    last_sign_in_at: string | null;
+    invitation_sent_at: string | null;
+    invitation_accepted_at: string | null;
+    created_at: string | null;
+}
+export interface CustomerContact {
+    id: number;
+    name: string;
+    email: string | null;
+    phone: string | null;
+    title: string | null;
+    /** Portal CustomerRole names (free-form, e.g. "Billing"). */
+    roles: string[];
+}
+export interface CustomerUsers {
+    customer: {
+        name: string;
+        customer_code: string | null;
+    };
+    users_count: number;
+    users: CustomerPortalUser[];
+    contacts_count: number;
+    contacts: CustomerContact[];
+}
+export declare function getCustomerUsers(client: ApiClient, args: {
+    customerCode?: string;
+    userId?: string;
+}): Promise<CustomerUsers>;

package/dist/api/customer.api.js

@@ -126,3 +126,22 @@ export async function getCustomerCohort(client, args) {
     }
     return response.data;
 }
+export async function getCustomerUsers(client, args) {
+    const secret = process.env.FINSTACK_CHATBASE_SECRET;
+    if (!secret) {
+        throw new Error('FINSTACK_CHATBASE_SECRET must be set');
+    }
+    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 response = await client.get(`/api/v1/chatbase/customer_users?${params}`, { 'X-Chatbase-Secret': secret });
+    if (response.status !== 'success' || !response.data) {
+        throw new Error(response.message || 'Failed to fetch customer users');
+    }
+    return response.data;
+}

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

@@ -45,4 +45,10 @@ interface GetPricingAddendumTextArgs {
     environment?: string;
 }
 export declare function handleGetPricingAddendumText(args: GetPricingAddendumTextArgs): Promise<unknown>;
+interface GetCustomerUsersArgs {
+    customer_code?: string;
+    user_id?: string;
+    environment?: string;
+}
+export declare function handleGetCustomerUsers(args: GetCustomerUsersArgs): Promise<unknown>;
 export {};

package/dist/handlers/customer.handler.js

@@ -2,7 +2,7 @@
  * Customer tool handlers
  */
 import { getClient } from '../api/client.js';
-import { getCustomerCohort, getCustomerInvoices, getCustomerPricingConfig, getCustomerRevenue, getCustomerSummary, getPricingAddendumText, searchCustomers, } from '../api/customer.api.js';
+import { getCustomerCohort, getCustomerInvoices, getCustomerPricingConfig, getCustomerRevenue, getCustomerSummary, getCustomerUsers, getPricingAddendumText, searchCustomers, } from '../api/customer.api.js';
 export async function handleGetCustomerSummary(args) {
     const client = getClient(args.environment ?? 'prod');
     return getCustomerSummary(client, args.customer_code);
@@ -49,3 +49,10 @@ export async function handleGetPricingAddendumText(args) {
         variant: args.variant ?? 'with_disclaimer',
     });
 }
+export async function handleGetCustomerUsers(args) {
+    const client = getClient(args.environment ?? 'prod');
+    return getCustomerUsers(client, {
+        customerCode: args.customer_code,
+        userId: args.user_id,
+    });
+}

package/dist/handlers/index.js

@@ -1,4 +1,4 @@
-import { handleGetCustomerCohort, handleGetCustomerInvoices, handleGetCustomerPricingConfig, handleGetCustomerRevenue, handleGetCustomerSummary, handleGetPricingAddendumText, handleSearchCustomer, } from './customer.handler.js';
+import { handleGetCustomerCohort, handleGetCustomerInvoices, handleGetCustomerPricingConfig, handleGetCustomerRevenue, handleGetCustomerSummary, handleGetCustomerUsers, handleGetPricingAddendumText, handleSearchCustomer, } from './customer.handler.js';
 import { handleGetLeadiqAnalytics, handleGetLeadiqCustomer, } from './leadiq.handler.js';
 import { handleGetVendors } from './vendor.handler.js';
 const wrap = (fn) => {
@@ -12,6 +12,7 @@ export const handlers = {
     finstack_get_customer_pricing_config: wrap(handleGetCustomerPricingConfig),
     finstack_get_pricing_addendum_text: wrap(handleGetPricingAddendumText),
     finstack_get_customer_cohort: wrap(handleGetCustomerCohort),
+    finstack_get_customer_users: wrap(handleGetCustomerUsers),
     finstack_get_leadiq_analytics: wrap(handleGetLeadiqAnalytics),
     finstack_get_leadiq_customer: wrap(handleGetLeadiqCustomer),
     finstack_get_vendors: wrap(handleGetVendors),

package/dist/tools/customer.tools.js

@@ -1,7 +1,7 @@
 export const customerTools = [
     {
         name: 'finstack_get_customer_summary',
-        description: "Fetch a non-PII summary of a B2B customer: portal account status (account.status: active/inactive/blacklisted/locked/obsolete/new_account) and account type (account/channel_partner), onboarding progress, products, sales opportunities (sales_opportunities[] with opportunity_type full/upsell/expand/land and stage closed_won/closed_lost/churned), API credentials, inspection status, and recent billing. Use this when asked for a customer's status or sales opp stage. Backed by the mware-portal chatbase customer_context endpoint.",
+        description: "Fetch a non-PII summary of a B2B customer: portal account status (account.status: active/inactive/blacklisted/locked/obsolete/new_account) and account type (account/channel_partner), onboarding progress, products, sales opportunities (sales_opportunities[] with opportunity_type full/upsell/expand/land and stage closed_won/closed_lost/churned), API credentials, inspection status, and recent billing. Use this when asked for a customer's status or sales opp stage. Does NOT include portal users, contacts or emails — for those call finstack_get_customer_users. Backed by the mware-portal chatbase customer_context endpoint.",
         inputSchema: {
             type: 'object',
             properties: {
@@ -152,6 +152,28 @@ export const customerTools = [
             required: ['customer_code', 'type', 'start_date', 'end_date'],
         },
     },
+    {
+        name: 'finstack_get_customer_users',
+        description: "The people attached to a B2B customer account — the ONLY tool that returns portal users and contacts with names and emails. Use whenever asked for a customer's users, contacts, contact list, emails, who has portal access, who the admin/owner is, or who to email at an account. Returns users[] (portal logins: id, name, email, phone, title, roles, role_labels matching the portal Users tab — \"Admin (owner)\", \"Admin\", \"Developer\", \"Agent\", \"Billing\", \"Main billing contact\", \"Generic\" — is_owner, status active/invited/not_invited, locked, mfa_enabled, sign-in and invitation timestamps; owner first) and contacts[] (the \"no portal access\" contacts: name, email, phone, title, roles). When asked for \"contacts\" or a \"contact list\", return the portal users AND the contacts[] rows. For a list spanning many customers, call this once per CID (use finstack_search_customer to resolve names first). Identify the customer with EITHER customer_code OR user_id.",
+        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.',
+                },
+                environment: {
+                    type: 'string',
+                    description: 'Target environment: "prod" (default) or "dev"',
+                    enum: ['dev', 'prod'],
+                },
+            },
+        },
+    },
     {
         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.',

package/package.json

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