@crscreditapi/finstack-mcp-server 0.1.1-3d2b39b → 0.2.0-fac1a77

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=
+
+# === Vendor contact directory (crs-vendor-contacts) ===
+# Base URL of the already-deployed vendor contacts app. Read-only, no auth.
+# Defaults to the production Vercel URL if unset.
+# VENDOR_CONTACTS_BASE_URL=https://crs-vendor-contacts.vercel.app

package/README.md

@@ -10,6 +10,8 @@ MCP server exposing CRS B2B (Finstack) customer data over the [Model Context Pro
 | `finstack_get_customer_summary` | Non-PII summary for one customer: onboarding progress, products, API credentials, inspection status, recent billing. |
 | `finstack_get_customer_revenue` | Revenue for one customer over a date range, bucketed by `day` / `week` / `month` / `quarter` / `year`. |
 | `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. |
 
 ## Install
 
@@ -125,6 +127,22 @@ Range caps depend on `type`: `day` ≤ 92 days, `week` ≤ 2 years, `month`/`qua
 
 Identify the customer with either `customer_code` or `user_id`. `page` defaults to `1`, `per_page` defaults to `50` and is silently capped at `100`. Returns `{customer_code, page, per_page, total_count, total_pages, invoices: [...]}`, where each invoice carries its full `items[]` line-item breakdown.
 
+### `finstack_get_customer_pricing_config`
+
+```json
+{ "customer_code": "CID18068" }
+```
+
+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_pricing_addendum_text`
+
+```json
+{ "id": 1234, "variant": "with_disclaimer" }
+```
+
+`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.
+
 All tools accept an optional `environment: "prod" | "dev"` (default `"prod"`).
 
 ## Development

package/dist/api/client.d.ts

@@ -18,6 +18,10 @@ export declare class ApiClient {
     post<T>(path: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
     put<T>(path: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
     del<T>(path: string, headers?: Record<string, string>): Promise<T>;
+    getBuffer(path: string, headers?: Record<string, string>): Promise<{
+        buffer: Buffer;
+        contentType: string;
+    }>;
 }
 export declare function getClient(env?: Environment): ApiClient;
 export {};

package/dist/api/client.js

@@ -43,6 +43,18 @@ export class ApiClient {
     async del(path, headers) {
         return this.request('DELETE', path, undefined, headers);
     }
+    async getBuffer(path, headers) {
+        const response = await this.fetchWithTimeout(`${this.config.baseUrl}${path}`, { method: 'GET', headers: headers ?? {} });
+        if (!response.ok) {
+            const error = await response.text();
+            throw new Error(`GET ${path} failed: ${response.status} - ${error}`);
+        }
+        const arrayBuffer = await response.arrayBuffer();
+        return {
+            buffer: Buffer.from(arrayBuffer),
+            contentType: response.headers.get('content-type') ?? 'application/octet-stream',
+        };
+    }
 }
 function loadConfigs() {
     const timeoutMs = process.env.FINSTACK_TIMEOUT_MS

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

@@ -1,6 +1,3 @@
-/**
- * Customer-related calls against the mware-portal API.
- */
 import type { ApiClient } from './client.js';
 export interface CustomerSummary {
     summary: string;
@@ -117,3 +114,32 @@ export declare function getCustomerInvoices(client: ApiClient, args: {
     page?: number;
     perPage?: number;
 }): Promise<CustomerInvoicesPage>;
+export interface PricingAddendum {
+    id: number;
+    name: string;
+    status: string;
+    quote_id: string | number | null;
+    created_at: string;
+    updated_at: string;
+    has_pdf: boolean;
+    has_pdf_without_disclaimer: boolean;
+    pdf_url: string | null;
+    pdf_without_disclaimer_url: string | null;
+}
+export interface CustomerPricingConfig {
+    products: Array<Record<string, unknown>>;
+    pricing_addendums: PricingAddendum[];
+    environment_users: Array<Record<string, unknown>>;
+}
+export declare function getCustomerPricingConfig(client: ApiClient, customerCode: string): Promise<CustomerPricingConfig>;
+export type PricingAddendumVariant = 'with_disclaimer' | 'without_disclaimer';
+export interface PricingAddendumText {
+    addendum_id: number;
+    variant: PricingAddendumVariant;
+    page_count: number;
+    text: string;
+}
+export declare function getPricingAddendumText(client: ApiClient, args: {
+    id: number;
+    variant: PricingAddendumVariant;
+}): Promise<PricingAddendumText>;

package/dist/api/customer.api.js

@@ -1,3 +1,7 @@
+/**
+ * Customer-related calls against the mware-portal API.
+ */
+import { PDFParse } from 'pdf-parse';
 export async function getCustomerSummary(client, customerCode) {
     const secret = process.env.FINSTACK_CHATBASE_SECRET;
     if (!secret) {
@@ -69,3 +73,36 @@ export async function getCustomerInvoices(client, args) {
     }
     return response.data;
 }
+export async function getCustomerPricingConfig(client, customerCode) {
+    const secret = process.env.FINSTACK_CHATBASE_SECRET;
+    if (!secret) {
+        throw new Error('FINSTACK_CHATBASE_SECRET must be set');
+    }
+    const params = new URLSearchParams({ customer_code: customerCode });
+    const response = await client.get(`/api/v1/chatbase/customer_pricing_config?${params}`, { 'X-Chatbase-Secret': secret });
+    if (response.status !== 'success' || !response.data) {
+        throw new Error(response.message || 'Failed to fetch customer pricing config');
+    }
+    return response.data;
+}
+export async function getPricingAddendumText(client, args) {
+    const secret = process.env.FINSTACK_CHATBASE_SECRET;
+    if (!secret) {
+        throw new Error('FINSTACK_CHATBASE_SECRET must be set');
+    }
+    const params = new URLSearchParams({ variant: args.variant });
+    const { buffer } = await client.getBuffer(`/api/v1/chatbase/pricing_addendum_pdf/${args.id}?${params}`, { 'X-Chatbase-Secret': secret });
+    const parser = new PDFParse({ data: new Uint8Array(buffer) });
+    try {
+        const result = await parser.getText();
+        return {
+            addendum_id: args.id,
+            variant: args.variant,
+            page_count: result.total,
+            text: result.text,
+        };
+    }
+    finally {
+        await parser.destroy();
+    }
+}

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

@@ -0,0 +1,34 @@
+export interface VendorContact {
+    id: string;
+    vendor: string;
+    name: string;
+    email: string;
+    phone: string;
+    role: string;
+    notes: string;
+    connection: string;
+    location: string;
+    bestFor: string;
+    specialties: 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 connection filter is applied server-side; the keyword query is applied
+ * here, 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(args: {
+    query?: string;
+    connection?: VendorConnection;
+    limit?: number;
+}): Promise<VendorSearchResult>;

package/dist/api/vendor.api.js

@@ -0,0 +1,76 @@
+/**
+ * Vendor contact directory calls.
+ *
+ * Backed by the standalone crs-vendor-contacts web service (the CPO's
+ * Slack-powered vendor Rolodex). There is no database — the service stores
+ * contacts in a JSON blob and exposes them over a read-only REST endpoint
+ * (GET /api/vendors). We fetch the list and filter in-process so callers can
+ * match on specialty tags too (the upstream ?q= filter only covers a subset
+ * of fields).
+ *
+ * This calls the vendor app's already-deployed public API, so it needs no
+ * redeploy of that project — only the env var VENDOR_CONTACTS_BASE_URL
+ * (defaults to the production Vercel URL).
+ */
+import { ApiClient } from './client.js';
+const DEFAULT_BASE_URL = 'https://crs-vendor-contacts.vercel.app';
+const DEFAULT_TIMEOUT_MS = 30_000;
+let _vendorClient = null;
+function getVendorClient() {
+    if (_vendorClient)
+        return _vendorClient;
+    const baseUrl = process.env.VENDOR_CONTACTS_BASE_URL ?? DEFAULT_BASE_URL;
+    const timeoutMs = process.env.FINSTACK_TIMEOUT_MS
+        ? parseInt(process.env.FINSTACK_TIMEOUT_MS, 10)
+        : DEFAULT_TIMEOUT_MS;
+    _vendorClient = new ApiClient({ baseUrl, timeoutMs });
+    return _vendorClient;
+}
+/**
+ * Search the vendor contact directory.
+ *
+ * The connection filter is applied server-side; the keyword query is applied
+ * here, 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(args) {
+    const client = getVendorClient();
+    const params = new URLSearchParams();
+    if (args.connection && args.connection !== 'all') {
+        params.set('connection', args.connection);
+    }
+    const qs = params.toString();
+    const all = await client.get(qs ? `/api/vendors?${qs}` : '/api/vendors');
+    let matched = all;
+    const q = args.query?.trim().toLowerCase();
+    if (q) {
+        const terms = q.split(/\s+/).filter((t) => t.length > 1);
+        if (terms.length > 0) {
+            matched = all.filter((v) => {
+                const haystack = [
+                    v.vendor,
+                    v.name,
+                    v.email,
+                    v.role,
+                    v.notes,
+                    v.location,
+                    v.bestFor,
+                    ...(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/customer.handler.d.ts

@@ -1,4 +1,4 @@
-import { type RevenuePeriodType } from '../api/customer.api.js';
+import { type PricingAddendumVariant, type RevenuePeriodType } from '../api/customer.api.js';
 interface GetCustomerSummaryArgs {
     customer_code: string;
     environment?: string;
@@ -26,4 +26,15 @@ interface GetCustomerInvoicesArgs {
     environment?: string;
 }
 export declare function handleGetCustomerInvoices(args: GetCustomerInvoicesArgs): Promise<unknown>;
+interface GetCustomerPricingConfigArgs {
+    customer_code: string;
+    environment?: string;
+}
+export declare function handleGetCustomerPricingConfig(args: GetCustomerPricingConfigArgs): Promise<unknown>;
+interface GetPricingAddendumTextArgs {
+    id: number;
+    variant?: PricingAddendumVariant;
+    environment?: string;
+}
+export declare function handleGetPricingAddendumText(args: GetPricingAddendumTextArgs): Promise<unknown>;
 export {};

package/dist/handlers/customer.handler.js

@@ -2,7 +2,7 @@
  * Customer tool handlers
  */
 import { getClient } from '../api/client.js';
-import { getCustomerInvoices, getCustomerRevenue, getCustomerSummary, searchCustomers, } from '../api/customer.api.js';
+import { getCustomerInvoices, getCustomerPricingConfig, getCustomerRevenue, getCustomerSummary, getPricingAddendumText, searchCustomers, } from '../api/customer.api.js';
 export async function handleGetCustomerSummary(args) {
     const client = getClient(args.environment ?? 'prod');
     return getCustomerSummary(client, args.customer_code);
@@ -29,3 +29,14 @@ export async function handleGetCustomerInvoices(args) {
         perPage: args.per_page,
     });
 }
+export async function handleGetCustomerPricingConfig(args) {
+    const client = getClient(args.environment ?? 'prod');
+    return getCustomerPricingConfig(client, args.customer_code);
+}
+export async function handleGetPricingAddendumText(args) {
+    const client = getClient(args.environment ?? 'prod');
+    return getPricingAddendumText(client, {
+        id: args.id,
+        variant: args.variant ?? 'with_disclaimer',
+    });
+}

package/dist/handlers/index.js

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

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

@@ -0,0 +1,11 @@
+/**
+ * Vendor contact directory handlers
+ */
+import { type VendorConnection } from '../api/vendor.api.js';
+interface GetVendorArgs {
+    query?: string;
+    connection?: VendorConnection;
+    limit?: number;
+}
+export declare function handleGetVendor(args: GetVendorArgs): Promise<unknown>;
+export {};

package/dist/handlers/vendor.handler.js

@@ -0,0 +1,11 @@
+/**
+ * Vendor contact directory handlers
+ */
+import { searchVendorContacts, } from '../api/vendor.api.js';
+export async function handleGetVendor(args) {
+    return searchVendorContacts({
+        query: args.query,
+        connection: args.connection,
+        limit: args.limit,
+    });
+}

package/dist/tools/customer.tools.js

@@ -77,6 +77,49 @@ export const customerTools = [
             },
         },
     },
+    {
+        name: 'finstack_get_customer_pricing_config',
+        description: "Full configured pricing state for a B2B customer: per-product BillingProductCustomer records (tiers, fees, add-ons, override_price), pricing_addendums (id, name, status, quote_id, timestamps, has_pdf flags, pdf URLs), and environment_users with their productPricing config (billingAmount, effectiveDate, pricingTiers, tiered/volume flags; credentials excluded). Use when the user asks what a customer is contracted to pay, to cross-check invoice line-item rates against contracted pricing, or to inspect tier/volume pricing setup. Each pricing addendum's PDF text can be fetched with finstack_get_pricing_addendum_text using the returned id.",
+        inputSchema: {
+            type: 'object',
+            properties: {
+                customer_code: {
+                    type: 'string',
+                    description: 'Customer code (CID) — e.g. "CID18068"',
+                },
+                environment: {
+                    type: 'string',
+                    description: 'Target environment: "prod" (default) or "dev"',
+                    enum: ['dev', 'prod'],
+                },
+            },
+            required: ['customer_code'],
+        },
+    },
+    {
+        name: 'finstack_get_pricing_addendum_text',
+        description: "Extracted text contents of a pricing addendum PDF. Use after finstack_get_customer_pricing_config to read the full body of an addendum (terms, line items, footnotes) when the structured pricing config doesn't answer the question. Pass the addendum's id from pricing_addendums[]. Returns page_count and the concatenated text. Table layouts may come through with run-together columns — readable for LLM reasoning but not pixel-perfect.",
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: {
+                    type: 'number',
+                    description: 'Pricing addendum id, from pricing_addendums[].id in finstack_get_customer_pricing_config',
+                },
+                variant: {
+                    type: 'string',
+                    enum: ['with_disclaimer', 'without_disclaimer'],
+                    description: 'Which attachment to read. Default "with_disclaimer". Use "without_disclaimer" only if pricing_addendums[].has_pdf_without_disclaimer is true.',
+                },
+                environment: {
+                    type: 'string',
+                    description: 'Target environment: "prod" (default) or "dev"',
+                    enum: ['dev', 'prod'],
+                },
+            },
+            required: ['id'],
+        },
+    },
     {
         name: 'finstack_get_customer_revenue',
         description: 'Fetch revenue for a B2B customer over a date range, bucketed by period (day/week/month/quarter/year). Use when the user asks how much a customer paid, revenue trends, MRR/ARR-style figures, or billing over time. Returns periods[{period,revenue}] plus a total. Max range: day=92d, week=2y, month/quarter=10y, year=50y; pick the coarsest type that covers the range.',

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: 'vendorproject_find_vendor_contact',
+        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/Asurint, SentiLink), NOT CRS customers (use the 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, 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.1.1-3d2b39b",
+	"version": "0.2.0-fac1a77",
 	"description": "MCP server for Finstack",
 	"type": "module",
 	"main": "dist/index.js",
@@ -31,11 +31,13 @@
 	"dependencies": {
 		"@modelcontextprotocol/sdk": "^1.0.0",
 		"dotenv": "^16.3.0",
-		"express": "^5.2.1"
+		"express": "^5.2.1",
+		"pdf-parse": "^2.4.5"
 	},
 	"devDependencies": {
 		"@types/express": "^5.0.6",
 		"@types/node": "^20.11.0",
+		"@types/pdf-parse": "^1.1.5",
 		"typescript": "^5.3.0"
 	}
 }