@crscreditapi/finstack-mcp-server 0.1.0-a04547f → 0.1.0-eff2af8

package/README.md

@@ -0,0 +1,145 @@
+# finstack-mcp-server
+
+MCP server exposing CRS B2B (Finstack) customer data over the [Model Context Protocol](https://modelcontextprotocol.io). Backed by the mware-portal chatbase API.
+
+## Tools
+
+| Name | Purpose |
+|---|---|
+| `finstack_search_customer` | Fuzzy-match a customer by name and return candidate CIDs. Use when only a name is known. |
+| `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. |
+
+## Install
+
+```bash
+npm install -g @crscreditapi/finstack-mcp-server
+```
+
+After install, the `finstack-mcp-server` binary is on your `PATH`.
+
+## Configuration
+
+The server reads configuration from environment variables (also loaded from a local `.env` file via `dotenv`).
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `FINSTACK_PROD_BASE_URL` | yes | — | Base URL of the mware-portal API (production). |
+| `FINSTACK_CHATBASE_SECRET` | yes | — | Shared secret sent as `X-Chatbase-Secret` on every request. |
+| `FINSTACK_DEV_BASE_URL` | no | falls back to prod | Base URL for the dev environment. Used when a tool call passes `environment: "dev"`. |
+| `FINSTACK_TIMEOUT_MS` | no | `30000` | Per-request timeout in milliseconds. |
+| `MCP_TRANSPORT` | no | `stdio` | Transport mode: `stdio` (for Claude Code and other CLI clients) or `http` (for n8n and remote clients). |
+| `MCP_PORT` | no | `3002` | Port for the HTTP transport. Ignored when `MCP_TRANSPORT=stdio`. |
+
+A starter file is included as `.env.example`.
+
+## Usage
+
+### Stdio (Claude Code, Claude Desktop, other CLI clients)
+
+Add an entry to your MCP config (`.mcp.json` for Claude Code, `claude_desktop_config.json` for Claude Desktop):
+
+```json
+{
+  "mcpServers": {
+    "finstack": {
+      "command": "finstack-mcp-server",
+      "env": {
+        "MCP_TRANSPORT": "stdio",
+        "FINSTACK_PROD_BASE_URL": "https://portal.example.com",
+        "FINSTACK_CHATBASE_SECRET": "<your-secret>"
+      }
+    }
+  }
+}
+```
+
+The client launches the process; tool calls travel over stdio. No port to open.
+
+### HTTP (n8n, remote MCP clients)
+
+Run it as a long-lived service:
+
+```bash
+MCP_TRANSPORT=http \
+MCP_PORT=3002 \
+FINSTACK_PROD_BASE_URL=https://portal.example.com \
+FINSTACK_CHATBASE_SECRET=<your-secret> \
+finstack-mcp-server
+```
+
+Endpoints:
+
+- `POST /` and `POST /mcp` — MCP requests (streamable HTTP transport)
+- `GET /health` — health check, returns `{"status":"ok","uptime":<seconds>}`
+
+Point your client at `http://<host>:3002/mcp`.
+
+### Docker
+
+```dockerfile
+FROM node:20-alpine
+RUN npm install -g @crscreditapi/finstack-mcp-server
+ENV MCP_TRANSPORT=http MCP_PORT=3002
+EXPOSE 3002
+CMD ["finstack-mcp-server"]
+```
+
+Pass the `FINSTACK_*` variables at runtime (e.g. via `--env-file` or an orchestrator's secret store).
+
+## Tool call reference
+
+### `finstack_search_customer`
+
+```json
+{ "q": "rentvine", "threshold": 0.8 }
+```
+
+`q` (required, min 2 chars) is matched case-insensitively. `threshold` (optional, 0.0–1.0, default `0.9`) controls fuzziness — lower it if nothing comes back.
+
+### `finstack_get_customer_summary`
+
+```json
+{ "customer_code": "CID18068" }
+```
+
+### `finstack_get_customer_revenue`
+
+```json
+{
+  "customer_code": "CID18068",
+  "type": "month",
+  "start_date": "2025-05-08",
+  "end_date": "2026-05-08"
+}
+```
+
+Range caps depend on `type`: `day` ≤ 92 days, `week` ≤ 2 years, `month`/`quarter` ≤ 10 years, `year` ≤ 50 years.
+
+### `finstack_get_customer_invoices`
+
+```json
+{ "customer_code": "CID18068", "page": 1, "per_page": 50 }
+```
+
+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.
+
+All tools accept an optional `environment: "prod" | "dev"` (default `"prod"`).
+
+## Development
+
+```bash
+git clone https://github.com/StitchCredit/finstack-mcp-server.git
+cd finstack-mcp-server
+npm install
+cp .env.example .env   # fill in FINSTACK_PROD_BASE_URL and FINSTACK_CHATBASE_SECRET
+npm run build
+npm start
+```
+
+For stdio mode while iterating, set `MCP_TRANSPORT=stdio` in `.env` and wire the local `dist/index.js` into your MCP client's config.
+
+## License
+
+Private — internal use within CRS Credit API.

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

@@ -74,3 +74,46 @@ export declare function getCustomerRevenue(client: ApiClient, args: {
     startDate: string;
     endDate: string;
 }): Promise<CustomerRevenue>;
+export interface InvoicePermissiblePurpose {
+    id: number;
+    name: string;
+    code: string;
+    onboarding_path: string;
+}
+export interface InvoiceItem {
+    description: string;
+    item_code: string;
+    netsuite_id: string | null;
+    quantity: number;
+    rate_in_cents: number | null;
+    amount_in_cents: number;
+    amount: number;
+}
+export interface CustomerInvoice {
+    invoice_number: string;
+    accounting_period: string;
+    date: string;
+    due_date: string | null;
+    amount: number;
+    status: string;
+    netsuite_status: string | null;
+    memo: string | null;
+    created_at: string;
+    updated_at: string;
+    permissible_purpose: InvoicePermissiblePurpose | null;
+    items: InvoiceItem[];
+}
+export interface CustomerInvoicesPage {
+    customer_code: string;
+    page: number;
+    per_page: number;
+    total_count: number;
+    total_pages: number;
+    invoices: CustomerInvoice[];
+}
+export declare function getCustomerInvoices(client: ApiClient, args: {
+    customerCode?: string;
+    userId?: string;
+    page?: number;
+    perPage?: number;
+}): Promise<CustomerInvoicesPage>;

package/dist/api/customer.api.js

@@ -46,3 +46,26 @@ export async function getCustomerRevenue(client, args) {
     }
     return response.data;
 }
+export async function getCustomerInvoices(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);
+    if (args.page !== undefined)
+        params.set('page', String(args.page));
+    if (args.perPage !== undefined)
+        params.set('per_page', String(args.perPage));
+    const response = await client.get(`/api/v1/chatbase/customer_invoices?${params}`, { 'X-Chatbase-Secret': secret });
+    if (response.status !== 'success' || !response.data) {
+        throw new Error(response.message || 'Failed to fetch customer invoices');
+    }
+    return response.data;
+}

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

@@ -18,4 +18,12 @@ interface GetCustomerRevenueArgs {
     environment?: string;
 }
 export declare function handleGetCustomerRevenue(args: GetCustomerRevenueArgs): Promise<unknown>;
+interface GetCustomerInvoicesArgs {
+    customer_code?: string;
+    user_id?: string;
+    page?: number;
+    per_page?: number;
+    environment?: string;
+}
+export declare function handleGetCustomerInvoices(args: GetCustomerInvoicesArgs): Promise<unknown>;
 export {};

package/dist/handlers/customer.handler.js

@@ -2,7 +2,7 @@
  * Customer tool handlers
  */
 import { getClient } from '../api/client.js';
-import { getCustomerRevenue, getCustomerSummary, searchCustomers, } from '../api/customer.api.js';
+import { getCustomerInvoices, getCustomerRevenue, getCustomerSummary, searchCustomers, } from '../api/customer.api.js';
 export async function handleGetCustomerSummary(args) {
     const client = getClient(args.environment ?? 'prod');
     return getCustomerSummary(client, args.customer_code);
@@ -20,3 +20,12 @@ export async function handleGetCustomerRevenue(args) {
         endDate: args.end_date,
     });
 }
+export async function handleGetCustomerInvoices(args) {
+    const client = getClient(args.environment ?? 'prod');
+    return getCustomerInvoices(client, {
+        customerCode: args.customer_code,
+        userId: args.user_id,
+        page: args.page,
+        perPage: args.per_page,
+    });
+}

package/dist/handlers/index.js

@@ -1,4 +1,4 @@
-import { handleGetCustomerRevenue, handleGetCustomerSummary, handleSearchCustomer, } from './customer.handler.js';
+import { handleGetCustomerInvoices, handleGetCustomerRevenue, handleGetCustomerSummary, handleSearchCustomer, } from './customer.handler.js';
 const wrap = (fn) => {
     return async (args) => fn(args);
 };
@@ -6,4 +6,5 @@ export const handlers = {
     finstack_get_customer_summary: wrap(handleGetCustomerSummary),
     finstack_search_customer: wrap(handleSearchCustomer),
     finstack_get_customer_revenue: wrap(handleGetCustomerRevenue),
+    finstack_get_customer_invoices: wrap(handleGetCustomerInvoices),
 };

package/dist/tools/customer.tools.js

@@ -44,6 +44,39 @@ export const customerTools = [
             required: ['q'],
         },
     },
+    {
+        name: 'finstack_get_customer_invoices',
+        description: "Paginated list of finalized invoices for a B2B customer with full line-item breakdown. Use when the user asks for billing history, invoice details, what they were charged for, or itemized lines (vs. finstack_get_customer_summary which only shows the 3 most recent invoices without line items). Each invoice includes status, permissible_purpose, and items with quantity / rate_in_cents / amount. 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.',
+                },
+                page: {
+                    type: 'number',
+                    description: 'Page number, 1-indexed. Default 1. Invalid values fall back to 1 server-side.',
+                    minimum: 1,
+                },
+                per_page: {
+                    type: 'number',
+                    description: 'Page size. Default 50, silently capped at 100. Invalid values fall back to 50 server-side.',
+                    minimum: 1,
+                    maximum: 100,
+                },
+                environment: {
+                    type: 'string',
+                    description: 'Target environment: "prod" (default) or "dev"',
+                    enum: ['dev', 'prod'],
+                },
+            },
+        },
+    },
     {
         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-a04547f",
+	"version": "0.1.0-eff2af8",
 	"description": "MCP server for Finstack",
 	"type": "module",
 	"main": "dist/index.js",