@crscreditapi/finstack-mcp-server 0.1.0-eff2af8 → 0.2.0-cbc96e9

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/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,4 @@
-import { handleGetCustomerInvoices, handleGetCustomerRevenue, handleGetCustomerSummary, handleSearchCustomer, } from './customer.handler.js';
+import { handleGetCustomerInvoices, handleGetCustomerPricingConfig, handleGetCustomerRevenue, handleGetCustomerSummary, handleGetPricingAddendumText, handleSearchCustomer, } from './customer.handler.js';
 const wrap = (fn) => {
     return async (args) => fn(args);
 };
@@ -7,4 +7,6 @@ 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),
 };

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/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@crscreditapi/finstack-mcp-server",
-	"version": "0.1.0-eff2af8",
+	"version": "0.2.0-cbc96e9",
 	"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"
 	}
 }