@crscreditapi/finstack-mcp-server 0.1.0-2bad4fe

package/.env.example

@@ -0,0 +1,13 @@
+# Transport mode: "stdio" (default, for Claude Code) or "http" (for n8n / EC2)
+MCP_TRANSPORT=stdio
+
+# HTTP transport port (only used when MCP_TRANSPORT=http)
+MCP_PORT=3002
+
+# === mware-portal API ===
+FINSTACK_PROD_BASE_URL=https://portal.example.com
+# FINSTACK_DEV_BASE_URL=https://portal-dev.example.com
+# FINSTACK_TIMEOUT_MS=30000
+
+# Shared secret for the mware-portal chatbase endpoints (X-Chatbase-Secret header)
+FINSTACK_CHATBASE_SECRET=

package/dist/api/client.d.ts

@@ -0,0 +1,23 @@
+/**
+ * HTTP client skeleton for the B2B API.
+ *
+ * No auth wired up yet — add Authorization header / login flow once the
+ * upstream API is decided. This is a thin fetch wrapper with timeouts.
+ */
+export type Environment = 'dev' | 'prod';
+interface ApiClientConfig {
+    baseUrl: string;
+    timeoutMs: number;
+}
+export declare class ApiClient {
+    private config;
+    constructor(config: ApiClientConfig);
+    private fetchWithTimeout;
+    private request;
+    get<T>(path: string, headers?: Record<string, string>): Promise<T>;
+    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>;
+}
+export declare function getClient(env?: Environment): ApiClient;
+export {};

package/dist/api/client.js

@@ -0,0 +1,81 @@
+/**
+ * HTTP client skeleton for the B2B API.
+ *
+ * No auth wired up yet — add Authorization header / login flow once the
+ * upstream API is decided. This is a thin fetch wrapper with timeouts.
+ */
+const DEFAULT_TIMEOUT_MS = 30_000;
+export class ApiClient {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    fetchWithTimeout(url, options) {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.config.timeoutMs);
+        return fetch(url, { ...options, signal: controller.signal }).finally(() => clearTimeout(timeoutId));
+    }
+    async request(method, path, body, headers) {
+        const options = {
+            method,
+            headers: {
+                ...(body !== undefined && { 'Content-Type': 'application/json' }),
+                ...headers,
+            },
+            ...(body !== undefined && { body: JSON.stringify(body) }),
+        };
+        const response = await this.fetchWithTimeout(`${this.config.baseUrl}${path}`, options);
+        if (!response.ok) {
+            const error = await response.text();
+            throw new Error(`${method} ${path} failed: ${response.status} - ${error}`);
+        }
+        return response.json();
+    }
+    async get(path, headers) {
+        return this.request('GET', path, undefined, headers);
+    }
+    async post(path, body, headers) {
+        return this.request('POST', path, body, headers);
+    }
+    async put(path, body, headers) {
+        return this.request('PUT', path, body, headers);
+    }
+    async del(path, headers) {
+        return this.request('DELETE', path, undefined, headers);
+    }
+}
+function loadConfigs() {
+    const timeoutMs = process.env.FINSTACK_TIMEOUT_MS
+        ? parseInt(process.env.FINSTACK_TIMEOUT_MS, 10)
+        : DEFAULT_TIMEOUT_MS;
+    const prodBaseUrl = process.env.FINSTACK_PROD_BASE_URL;
+    if (!prodBaseUrl) {
+        throw new Error('FINSTACK_PROD_BASE_URL must be set');
+    }
+    const prodConfig = {
+        baseUrl: prodBaseUrl,
+        timeoutMs,
+    };
+    const devBaseUrl = process.env.FINSTACK_DEV_BASE_URL;
+    const devConfig = devBaseUrl
+        ? { baseUrl: devBaseUrl, timeoutMs }
+        : prodConfig;
+    return { prod: prodConfig, dev: devConfig };
+}
+let _prodClient = null;
+let _devClient = null;
+function ensureInit() {
+    if (_prodClient)
+        return;
+    const configs = loadConfigs();
+    _prodClient = new ApiClient(configs.prod);
+    _devClient = new ApiClient(configs.dev);
+}
+export function getClient(env = 'prod') {
+    ensureInit();
+    const client = env === 'dev' ? _devClient : _prodClient;
+    if (!client) {
+        throw new Error(`The ${env} environment is not configured.`);
+    }
+    return client;
+}

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

@@ -0,0 +1,46 @@
+/**
+ * Customer-related calls against the mware-portal API.
+ */
+import type { ApiClient } from './client.js';
+export interface CustomerSummary {
+    summary: string;
+    account: {
+        onboarding_path: string | null;
+        onboarding_completion_percent: number;
+        completed_tasks: number;
+        total_tasks: number;
+    };
+    onboarding_steps: Array<{
+        name: string;
+        type: string;
+        status: string;
+    }>;
+    products: Array<{
+        vendor: string | null;
+        product: string;
+        add_ons: string | null;
+        platform: string | null;
+        status: 'activated' | 'not_activated';
+    }>;
+    api_credentials: Record<'sandbox' | 'production', {
+        configured: boolean;
+        enabled_count: number;
+        platforms: string[];
+    }>;
+    inspection: {
+        status: 'not_ordered';
+    } | {
+        status: string;
+        inspection_type: string;
+    };
+    billing: {
+        payment_method_on_file: boolean;
+        recent_invoices: Array<{
+            name: string;
+            date: string;
+            amount: string | number;
+            status: string;
+        }>;
+    };
+}
+export declare function getCustomerSummary(client: ApiClient, customerCode: string): Promise<CustomerSummary>;

package/dist/api/customer.api.js

@@ -0,0 +1,12 @@
+export async function getCustomerSummary(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_context?${params}`, { 'X-Chatbase-Secret': secret });
+    if (response.status !== 'success' || !response.data) {
+        throw new Error(response.message || 'Failed to fetch customer summary');
+    }
+    return response.data;
+}

package/dist/api/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Re-export all API functions
+ */
+export * from './client.js';
+export * from './customer.api.js';

package/dist/api/index.js

@@ -0,0 +1,5 @@
+/**
+ * Re-export all API functions
+ */
+export * from './client.js';
+export * from './customer.api.js';

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

@@ -0,0 +1,6 @@
+interface GetCustomerSummaryArgs {
+    customer_code: string;
+    environment?: string;
+}
+export declare function handleGetCustomerSummary(args: GetCustomerSummaryArgs): Promise<unknown>;
+export {};

package/dist/handlers/customer.handler.js

@@ -0,0 +1,9 @@
+/**
+ * Customer tool handlers
+ */
+import { getClient } from '../api/client.js';
+import { getCustomerSummary } from '../api/customer.api.js';
+export async function handleGetCustomerSummary(args) {
+    const client = getClient(args.environment ?? 'prod');
+    return getCustomerSummary(client, args.customer_code);
+}

package/dist/handlers/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Handler registry — maps tool names to handler functions.
+ */
+import type { Handler } from '../types/tool.types.js';
+export declare const handlers: Record<string, Handler>;

package/dist/handlers/index.js

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

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * Finstack MCP Server Entry Point
+ *
+ * Supports two transport modes via MCP_TRANSPORT env var:
+ *   - "stdio" (default): For CLI tools like Claude Code
+ *   - "http": Streamable HTTP for n8n and other HTTP-based MCP clients
+ */
+import 'dotenv/config';

package/dist/index.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+/**
+ * Finstack MCP Server Entry Point
+ *
+ * Supports two transport modes via MCP_TRANSPORT env var:
+ *   - "stdio" (default): For CLI tools like Claude Code
+ *   - "http": Streamable HTTP for n8n and other HTTP-based MCP clients
+ */
+import 'dotenv/config';
+import { tools } from './tools/index.js';
+import { handlers } from './handlers/index.js';
+import { createServer } from './server.js';
+async function main() {
+    const mode = process.env.MCP_TRANSPORT || 'stdio';
+    if (mode === 'http') {
+        await startHttpServer();
+    }
+    else {
+        await startStdioServer();
+    }
+}
+async function startStdioServer() {
+    const { StdioServerTransport } = await import('@modelcontextprotocol/sdk/server/stdio.js');
+    const server = createServer(tools, handlers);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('finstack-mcp-server running (stdio)');
+}
+async function startHttpServer() {
+    const { StreamableHTTPServerTransport } = await import('@modelcontextprotocol/sdk/server/streamableHttp.js');
+    const express = (await import('express')).default;
+    const port = parseInt(process.env.MCP_PORT || '3002', 10);
+    const app = express();
+    app.use(express.json());
+    app.use((req, _res, next) => {
+        console.log(`[${new Date().toISOString()}] ${req.method} ${req.url} Host:${req.headers.host} Accept:${req.headers.accept}`);
+        if (req.body && Object.keys(req.body).length > 0) {
+            console.log(`  Body: ${JSON.stringify(req.body).substring(0, 200)}`);
+        }
+        next();
+    });
+    const handlePost = async (req, res) => {
+        const server = createServer(tools, handlers);
+        const transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: undefined,
+        });
+        await server.connect(transport);
+        try {
+            await transport.handleRequest(req, res, req.body);
+        }
+        catch (error) {
+            console.error('Error handling MCP request:', error);
+            if (!res.headersSent) {
+                res.status(500).json({
+                    jsonrpc: '2.0',
+                    error: { code: -32603, message: 'Internal server error' },
+                    id: null,
+                });
+            }
+        }
+        res.on('close', () => {
+            transport.close();
+            server.close();
+        });
+    };
+    const handleMethodNotAllowed = (_req, res) => {
+        res.writeHead(405).end(JSON.stringify({
+            jsonrpc: '2.0',
+            error: { code: -32000, message: 'Method not allowed. Use POST.' },
+            id: null,
+        }));
+    };
+    app.get('/health', (_req, res) => {
+        res.json({ status: 'ok', uptime: process.uptime() });
+    });
+    app.post('/', handlePost);
+    app.post('/mcp', handlePost);
+    app.get('/', handleMethodNotAllowed);
+    app.get('/mcp', handleMethodNotAllowed);
+    app.listen(port, '0.0.0.0', () => {
+        console.error(`finstack-mcp-server running (http) on port ${port}`);
+        console.error(`  Health: http://localhost:${port}/health`);
+    });
+}
+main().catch((err) => {
+    console.error('Fatal error:', err);
+    process.exit(1);
+});

package/dist/resources.d.ts

@@ -0,0 +1,16 @@
+/**
+ * MCP Resources configuration
+ */
+export interface Resource {
+    uri: string;
+    name: string;
+    description: string;
+    mimeType: string;
+}
+export interface ResourceContent {
+    uri: string;
+    mimeType: string;
+    text: string;
+}
+export declare const resources: Resource[];
+export declare function getResourceContent(_uri: string): ResourceContent | null;

package/dist/resources.js

@@ -0,0 +1,7 @@
+/**
+ * MCP Resources configuration
+ */
+export const resources = [];
+export function getResourceContent(_uri) {
+    return null;
+}

package/dist/server.d.ts

@@ -0,0 +1,6 @@
+/**
+ * MCP Server configuration
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { ToolDefinition, Handler } from './types/tool.types.js';
+export declare function createServer(tools: ToolDefinition[], handlers: Record<string, Handler>): Server;

package/dist/server.js

@@ -0,0 +1,45 @@
+/**
+ * MCP Server configuration
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSchema, ReadResourceRequestSchema, ErrorCode, McpError, } from '@modelcontextprotocol/sdk/types.js';
+import { resources, getResourceContent } from './resources.js';
+export function createServer(tools, handlers) {
+    const server = new Server({ name: 'finstack-mcp-server', version: '0.1.0' }, { capabilities: { tools: {}, resources: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools,
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        const handler = handlers[name];
+        if (!handler) {
+            throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
+        }
+        try {
+            const result = await handler((args || {}));
+            return {
+                content: [
+                    { type: 'text', text: JSON.stringify(result, null, 2) },
+                ],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                content: [{ type: 'text', text: `Error: ${message}` }],
+                isError: true,
+            };
+        }
+    });
+    server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+        resources,
+    }));
+    server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+        const content = getResourceContent(request.params.uri);
+        if (!content) {
+            throw new McpError(ErrorCode.InvalidRequest, `Unknown resource: ${request.params.uri}`);
+        }
+        return { contents: [content] };
+    });
+    return server;
+}

package/dist/tools/customer.tools.d.ts

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

package/dist/tools/customer.tools.js

@@ -0,0 +1,21 @@
+export const customerTools = [
+    {
+        name: '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',
+            properties: {
+                customer_code: {
+                    type: 'string',
+                    description: 'Customer code (CID) — e.g. "ABC123"',
+                },
+                environment: {
+                    type: 'string',
+                    description: 'Target environment: "prod" (default) or "dev"',
+                    enum: ['dev', 'prod'],
+                },
+            },
+            required: ['customer_code'],
+        },
+    },
+];

package/dist/tools/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Tool registry.
+ *
+ * Add per-domain tool definitions here, e.g.:
+ *   import { fooTools } from './foo.tools.js';
+ *   export const tools: ToolDefinition[] = [...fooTools];
+ */
+import type { ToolDefinition } from '../types/tool.types.js';
+export declare const tools: ToolDefinition[];

package/dist/tools/index.js

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

package/dist/types/index.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Re-export all types
+ */
+export * from './tool.types.js';

package/dist/types/index.js

@@ -0,0 +1,4 @@
+/**
+ * Re-export all types
+ */
+export * from './tool.types.js';

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

@@ -0,0 +1,27 @@
+/**
+ * MCP Tool type definitions
+ */
+export interface JsonSchemaProperty {
+    type?: string;
+    description?: string;
+    enum?: string[];
+    items?: JsonSchemaProperty;
+    properties?: Record<string, JsonSchemaProperty>;
+    required?: string[];
+    minItems?: number;
+    maxItems?: number;
+}
+export interface ToolInputSchema {
+    type: 'object';
+    properties: Record<string, JsonSchemaProperty>;
+    required?: string[];
+    anyOf?: Array<{
+        required: string[];
+    }>;
+}
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: ToolInputSchema;
+}
+export type Handler = (args: Record<string, unknown>) => Promise<unknown>;

package/dist/types/tool.types.js

@@ -0,0 +1,4 @@
+/**
+ * MCP Tool type definitions
+ */
+export {};

package/package.json

@@ -0,0 +1,41 @@
+{
+	"name": "@crscreditapi/finstack-mcp-server",
+	"version": "0.1.0-2bad4fe",
+	"description": "MCP server for Finstack",
+	"type": "module",
+	"main": "dist/index.js",
+	"types": "dist/index.d.ts",
+	"bin": {
+		"finstack-mcp-server": "dist/index.js"
+	},
+	"files": [
+		"dist/**/*",
+		".env.example"
+	],
+	"engines": {
+		"node": ">=18.0.0"
+	},
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/StitchCredit/finstack-mcp-server.git"
+	},
+	"publishConfig": {
+		"registry": "https://registry.npmjs.org",
+		"access": "public"
+	},
+	"scripts": {
+		"build": "tsc",
+		"start": "node dist/index.js",
+		"prepublishOnly": "npm run build"
+	},
+	"dependencies": {
+		"@modelcontextprotocol/sdk": "^1.0.0",
+		"dotenv": "^16.3.0",
+		"express": "^5.2.1"
+	},
+	"devDependencies": {
+		"@types/express": "^5.0.6",
+		"@types/node": "^20.11.0",
+		"typescript": "^5.3.0"
+	}
+}