@crscreditapi/finstack-mcp-server 0.2.0-cbc96e9 → 0.3.0-61c51ea

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_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
 

package/dist/api/vendor.api.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Vendor contact directory calls.
+ *
+ * Backed by the mware-portal chatbase API, same as the customer tools:
+ * GET /api/v1/chatbase/vendor_contacts returns the whole vendor contact list
+ * in one shot (authenticated with the shared X-Chatbase-Secret). We fetch the
+ * full list and filter in-process so callers can match on specialty tags and
+ * connection degree too.
+ */
+import type { ApiClient } from './client.js';
+export interface VendorContact {
+    id: number;
+    vendor: string;
+    name: string;
+    email: string;
+    phone: string;
+    role: string;
+    location: string;
+    linkedin: string | null;
+    specialties: string[];
+    degree: string;
+    notes: string;
+}
+export type VendorConnection = '1st Degree' | '2nd Degree' | 'all';
+export interface VendorSearchResult {
+    query: string | null;
+    connection: VendorConnection;
+    total_matched: number;
+    returned: number;
+    contacts: VendorContact[];
+}
+/**
+ * Search the vendor contact directory.
+ *
+ * The whole list is fetched from the chatbase endpoint, then filtered here:
+ * the connection filter narrows by degree, and the keyword query is OR-matched
+ * across every contact field plus specialty tags so that a question like
+ * "who handles ECM pricing" matches on role, notes, AND the `pricing` specialty.
+ */
+export declare function searchVendorContacts(client: ApiClient, args: {
+    query?: string;
+    connection?: VendorConnection;
+    limit?: number;
+}): Promise<VendorSearchResult>;

package/dist/api/vendor.api.js

@@ -0,0 +1,56 @@
+const CONNECTION_TO_DEGREE = {
+    '1st Degree': 'first_degree',
+    '2nd Degree': 'second_degree',
+};
+/**
+ * Search the vendor contact directory.
+ *
+ * The whole list is fetched from the chatbase endpoint, then filtered here:
+ * the connection filter narrows by degree, and the keyword query is OR-matched
+ * across every contact field plus specialty tags so that a question like
+ * "who handles ECM pricing" matches on role, notes, AND the `pricing` specialty.
+ */
+export async function searchVendorContacts(client, args) {
+    const secret = process.env.FINSTACK_CHATBASE_SECRET;
+    if (!secret) {
+        throw new Error('FINSTACK_CHATBASE_SECRET must be set');
+    }
+    const response = await client.get('/api/v1/chatbase/vendor_contacts', { 'X-Chatbase-Secret': secret });
+    if (response.status !== 'success' || !response.data) {
+        throw new Error(response.message || 'Failed to fetch vendor contacts');
+    }
+    let matched = response.data.vendor_contacts;
+    if (args.connection && args.connection !== 'all') {
+        const degree = CONNECTION_TO_DEGREE[args.connection];
+        matched = matched.filter((v) => v.degree === degree);
+    }
+    const q = args.query?.trim().toLowerCase();
+    if (q) {
+        const terms = q.split(/\s+/).filter((t) => t.length > 1);
+        if (terms.length > 0) {
+            matched = matched.filter((v) => {
+                const haystack = [
+                    v.vendor,
+                    v.name,
+                    v.email,
+                    v.role,
+                    v.notes,
+                    v.location,
+                    ...(v.specialties ?? []),
+                ]
+                    .filter(Boolean)
+                    .join(' ')
+                    .toLowerCase();
+                return terms.some((t) => haystack.includes(t));
+            });
+        }
+    }
+    const limit = args.limit && args.limit > 0 ? Math.min(args.limit, 100) : 25;
+    return {
+        query: args.query ?? null,
+        connection: args.connection ?? 'all',
+        total_matched: matched.length,
+        returned: Math.min(matched.length, limit),
+        contacts: matched.slice(0, limit),
+    };
+}

package/dist/handlers/index.js

@@ -1,4 +1,5 @@
 import { handleGetCustomerInvoices, handleGetCustomerPricingConfig, handleGetCustomerRevenue, handleGetCustomerSummary, handleGetPricingAddendumText, handleSearchCustomer, } from './customer.handler.js';
+import { handleGetVendors } from './vendor.handler.js';
 const wrap = (fn) => {
     return async (args) => fn(args);
 };
@@ -9,4 +10,5 @@ export const handlers = {
     finstack_get_customer_invoices: wrap(handleGetCustomerInvoices),
     finstack_get_customer_pricing_config: wrap(handleGetCustomerPricingConfig),
     finstack_get_pricing_addendum_text: wrap(handleGetPricingAddendumText),
+    finstack_get_vendors: wrap(handleGetVendors),
 };

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

@@ -0,0 +1,9 @@
+import { type VendorConnection } from '../api/vendor.api.js';
+interface GetVendorsArgs {
+    query?: string;
+    connection?: VendorConnection;
+    limit?: number;
+    environment?: string;
+}
+export declare function handleGetVendors(args: GetVendorsArgs): Promise<unknown>;
+export {};

package/dist/handlers/vendor.handler.js

@@ -0,0 +1,13 @@
+/**
+ * Vendor contact directory handlers
+ */
+import { getClient } from '../api/client.js';
+import { searchVendorContacts, } from '../api/vendor.api.js';
+export async function handleGetVendors(args) {
+    const client = getClient(args.environment ?? 'prod');
+    return searchVendorContacts(client, {
+        query: args.query,
+        connection: args.connection,
+        limit: args.limit,
+    });
+}

package/dist/tools/index.js

@@ -1,2 +1,3 @@
 import { customerTools } from './customer.tools.js';
-export const tools = [...customerTools];
+import { vendorTools } from './vendor.tools.js';
+export const tools = [...customerTools, ...vendorTools];

package/dist/tools/vendor.tools.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Vendor contact directory tool definitions
+ */
+import type { ToolDefinition } from '../types/tool.types.js';
+export declare const vendorTools: ToolDefinition[];

package/dist/tools/vendor.tools.js

@@ -0,0 +1,26 @@
+export const vendorTools = [
+    {
+        name: 'finstack_get_vendors',
+        description: "Look up WHO to contact at an external vendor or partner — the person to email, call, or get introduced to. This is about CRS's OWN vendors/partners (credit bureaus and data vendors like Equifax, TransUnion, Experian, CIC, LexisNexis, FICO, SBFE), NOT CRS customers (use the other finstack_* tools for customer accounts, billing, and pricing). Use whenever the user asks who to speak to / talk to / contact / reach out to / get an intro to, or who the point of contact or relationship owner is — for a vendor, a product or topic area (e.g. ECM), a role, or a specialty. Examples: 'who should I speak to for new ECM products', 'who is our pricing contact at Equifax', 'who handles compliance at Experian', 'who owns the TransUnion relationship'. Pass the key terms (vendor name, product/topic like 'ECM', role, or specialty) as `query` — it OR-matches across company, contact name, role, notes, location, and specialty tags (pricing, technical, legal, paperwork, champion, compliance, onboarding, sales, support, executive). Each result includes name, vendor, role, email, phone, location, LinkedIn, connection degree, and specialties. Omit `query` to list the whole directory. Read-only — it cannot add, edit, or delete contacts.",
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: {
+                    type: 'string',
+                    description: "Keywords to match — company, person, role, product area, or specialty. e.g. 'ECM', 'Equifax pricing', 'compliance'. Tokenized and OR-matched across all contact fields and specialty tags. Omit to return the full directory.",
+                },
+                connection: {
+                    type: 'string',
+                    enum: ['1st Degree', '2nd Degree', 'all'],
+                    description: "Filter by connection strength. '1st Degree' = direct contacts, '2nd Degree' = warm intros. Default 'all'.",
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Max contacts to return. Default 25, capped at 100.',
+                    minimum: 1,
+                    maximum: 100,
+                },
+            },
+        },
+    },
+];

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@crscreditapi/finstack-mcp-server",
-	"version": "0.2.0-cbc96e9",
+	"version": "0.3.0-61c51ea",
 	"description": "MCP server for Finstack",
 	"type": "module",
 	"main": "dist/index.js",