@crscreditapi/finstack-mcp-server 0.1.0-2bad4fe → 0.1.0-76ce272

package/README.md

@@ -0,0 +1,136 @@
+# 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`. |
+
+## 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.
+
+All three 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

@@ -44,3 +44,33 @@ export interface CustomerSummary {
     };
 }
 export declare function getCustomerSummary(client: ApiClient, customerCode: string): Promise<CustomerSummary>;
+export interface CustomerSearchHit {
+    name: string;
+    customer_code: string;
+    score: number;
+}
+export interface CustomerSearchResult {
+    results: CustomerSearchHit[];
+    threshold: number;
+    message?: string;
+}
+export declare function searchCustomers(client: ApiClient, query: string, threshold?: number): Promise<CustomerSearchResult>;
+export type RevenuePeriodType = 'day' | 'week' | 'month' | 'quarter' | 'year';
+export interface RevenuePeriod {
+    period: string;
+    revenue: number;
+}
+export interface CustomerRevenue {
+    customer_code: string;
+    type: RevenuePeriodType;
+    start_date: string;
+    end_date: string;
+    periods: RevenuePeriod[];
+    total: number;
+}
+export declare function getCustomerRevenue(client: ApiClient, args: {
+    customerCode: string;
+    type: RevenuePeriodType;
+    startDate: string;
+    endDate: string;
+}): Promise<CustomerRevenue>;

package/dist/api/customer.api.js

@@ -10,3 +10,39 @@ export async function getCustomerSummary(client, customerCode) {
     }
     return response.data;
 }
+export async function searchCustomers(client, query, threshold) {
+    const secret = process.env.FINSTACK_CHATBASE_SECRET;
+    if (!secret) {
+        throw new Error('FINSTACK_CHATBASE_SECRET must be set');
+    }
+    const params = new URLSearchParams({ q: query });
+    if (threshold !== undefined) {
+        params.set('threshold', String(threshold));
+    }
+    const response = await client.get(`/api/v1/chatbase/customer_search?${params}`, { 'X-Chatbase-Secret': secret });
+    if (response.status !== 'success') {
+        throw new Error(response.message || 'Customer search failed');
+    }
+    return {
+        results: response.data ?? [],
+        threshold: response.threshold ?? 0.9,
+        message: response.message,
+    };
+}
+export async function getCustomerRevenue(client, args) {
+    const secret = process.env.FINSTACK_CHATBASE_SECRET;
+    if (!secret) {
+        throw new Error('FINSTACK_CHATBASE_SECRET must be set');
+    }
+    const params = new URLSearchParams({
+        customer_code: args.customerCode,
+        type: args.type,
+        start_date: args.startDate,
+        end_date: args.endDate,
+    });
+    const response = await client.get(`/api/v1/chatbase/customer_revenue?${params}`, { 'X-Chatbase-Secret': secret });
+    if (response.status !== 'success' || !response.data) {
+        throw new Error(response.message || 'Failed to fetch customer revenue');
+    }
+    return response.data;
+}

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

@@ -1,6 +1,21 @@
+import { type RevenuePeriodType } from '../api/customer.api.js';
 interface GetCustomerSummaryArgs {
     customer_code: string;
     environment?: string;
 }
 export declare function handleGetCustomerSummary(args: GetCustomerSummaryArgs): Promise<unknown>;
+interface SearchCustomerArgs {
+    q: string;
+    threshold?: number;
+    environment?: string;
+}
+export declare function handleSearchCustomer(args: SearchCustomerArgs): Promise<unknown>;
+interface GetCustomerRevenueArgs {
+    customer_code: string;
+    type: RevenuePeriodType;
+    start_date: string;
+    end_date: string;
+    environment?: string;
+}
+export declare function handleGetCustomerRevenue(args: GetCustomerRevenueArgs): Promise<unknown>;
 export {};

package/dist/handlers/customer.handler.js

@@ -2,8 +2,21 @@
  * Customer tool handlers
  */
 import { getClient } from '../api/client.js';
-import { getCustomerSummary } from '../api/customer.api.js';
+import { 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);
 }
+export async function handleSearchCustomer(args) {
+    const client = getClient(args.environment ?? 'prod');
+    return searchCustomers(client, args.q, args.threshold);
+}
+export async function handleGetCustomerRevenue(args) {
+    const client = getClient(args.environment ?? 'prod');
+    return getCustomerRevenue(client, {
+        customerCode: args.customer_code,
+        type: args.type,
+        startDate: args.start_date,
+        endDate: args.end_date,
+    });
+}

package/dist/handlers/index.js

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

package/dist/tools/customer.tools.js

@@ -1,6 +1,6 @@
 export const customerTools = [
     {
-        name: 'get_customer_summary',
+        name: 'finstack_get_customer_summary',
         description: 'Fetch a non-PII summary of a B2B customer: onboarding progress, products, API credentials, inspection status, and recent billing. Backed by the mware-portal chatbase customer_context endpoint.',
         inputSchema: {
             type: 'object',
@@ -18,4 +18,62 @@ export const customerTools = [
             required: ['customer_code'],
         },
     },
+    {
+        name: 'finstack_search_customer',
+        description: "Find a B2B customer's code (CID) by fuzzy-matching their name. Use this when the user references a customer by name but hasn't supplied a CID — pass the returned customer_code into finstack_get_customer_summary. If no matches at the default threshold, lower it (e.g. 0.5) to broaden the search.",
+        inputSchema: {
+            type: 'object',
+            properties: {
+                q: {
+                    type: 'string',
+                    description: 'Search string — customer name or fragment, min 2 chars, case-insensitive',
+                    minLength: 2,
+                },
+                threshold: {
+                    type: 'number',
+                    description: 'Similarity threshold 0.0-1.0 (default 0.9). Lower for fuzzier matches.',
+                    minimum: 0,
+                    maximum: 1,
+                },
+                environment: {
+                    type: 'string',
+                    description: 'Target environment: "prod" (default) or "dev"',
+                    enum: ['dev', 'prod'],
+                },
+            },
+            required: ['q'],
+        },
+    },
+    {
+        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.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                customer_code: {
+                    type: 'string',
+                    description: 'Customer code (CID) — e.g. "CID18068"',
+                },
+                type: {
+                    type: 'string',
+                    enum: ['day', 'week', 'month', 'quarter', 'year'],
+                    description: 'Bucketing granularity for the returned periods',
+                },
+                start_date: {
+                    type: 'string',
+                    description: 'Start date (inclusive), format YYYY-MM-DD',
+                },
+                end_date: {
+                    type: 'string',
+                    description: 'End date (inclusive), format YYYY-MM-DD. Must be >= start_date.',
+                },
+                environment: {
+                    type: 'string',
+                    description: 'Target environment: "prod" (default) or "dev"',
+                    enum: ['dev', 'prod'],
+                },
+            },
+            required: ['customer_code', 'type', 'start_date', 'end_date'],
+        },
+    },
 ];

package/dist/types/tool.types.d.ts

@@ -10,6 +10,10 @@ export interface JsonSchemaProperty {
     required?: string[];
     minItems?: number;
     maxItems?: number;
+    minLength?: number;
+    maxLength?: number;
+    minimum?: number;
+    maximum?: number;
 }
 export interface ToolInputSchema {
     type: 'object';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@crscreditapi/finstack-mcp-server",
-	"version": "0.1.0-2bad4fe",
+	"version": "0.1.0-76ce272",
 	"description": "MCP server for Finstack",
 	"type": "module",
 	"main": "dist/index.js",