@spritz-finance/mcp-server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Spritz Finance
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,145 @@
+# Spritz MCP Server
+
+MCP server for [Spritz](https://www.spritz.finance) fiat rails — let AI agents off-ramp crypto to bank accounts.
+
+## What This Does
+
+An MCP (Model Context Protocol) server that gives AI agents tools to interact with the Spritz API. Tools are derived from the [OpenAPI spec](https://sandbox.spritz.finance/openapi/json) — no hand-written schemas.
+
+## Installation
+
+### npx (recommended)
+
+```bash
+npx @spritz-finance/mcp-server
+```
+
+### Global install
+
+```bash
+npm install -g @spritz-finance/mcp-server
+spritz-mcp-server
+```
+
+### From source
+
+```bash
+git clone https://github.com/spritz-finance/spritz-mcp-server.git
+cd spritz-mcp-server
+npm install && npm run build
+```
+
+## Configuration
+
+### 1. Get Your API Key
+
+1. Log in to [app.spritz.finance](https://app.spritz.finance)
+2. Go to **Settings > API Keys**
+3. Create a new key
+
+### 2. Configure Your MCP Client
+
+#### Claude Desktop
+
+Add to `~/.config/claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "spritz": {
+      "command": "npx",
+      "args": ["@spritz-finance/mcp-server"],
+      "env": {
+        "SPRITZ_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+#### Claude Code
+
+Add to your project's `.mcp.json`:
+
+```json
+{
+  "spritz": {
+    "command": "npx",
+    "args": ["@spritz-finance/mcp-server"],
+    "env": {
+      "SPRITZ_API_KEY": "your-api-key"
+    }
+  }
+}
+```
+
+#### Cursor
+
+Add to `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "spritz": {
+      "command": "npx",
+      "args": ["@spritz-finance/mcp-server"],
+      "env": {
+        "SPRITZ_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+## Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `list_bank_accounts` | List all bank accounts saved as off-ramp payment destinations |
+
+More tools coming soon.
+
+## Architecture
+
+Tools are driven by the OpenAPI spec — not hand-written. To expose a new endpoint, add one entry to `src/config.ts`:
+
+```ts
+export const EXPOSED_TOOLS: ToolConfig[] = [
+  {
+    name: "list_bank_accounts",
+    operationId: "getV1Bank-accounts",
+    description: "List all bank accounts saved as off-ramp payment destinations.",
+  },
+  // To add a new tool, just add another entry here.
+  // The inputSchema, HTTP method, and path are all derived from the OpenAPI spec.
+];
+```
+
+The server reads `openapi.json`, finds each `operationId`, extracts the JSON Schema for parameters and request bodies, and registers them as MCP tools. A generic handler dispatches tool calls to the Spritz API.
+
+```
+openapi.json          → source of truth for request/response schemas
+src/config.ts         → which operations to expose (cherry-pick)
+src/spec.ts           → reads spec, builds MCP tool definitions
+src/handlers.ts       → generic dispatcher (path params, query, body)
+src/index.ts          → MCP server + API client
+```
+
+## Development
+
+```bash
+npm install
+npm run dev          # Watch mode
+npm run build        # Build
+npm run inspector    # MCP inspector
+```
+
+### Updating the OpenAPI spec
+
+```bash
+curl -s https://sandbox.spritz.finance/openapi/json > openapi.json
+```
+
+## License
+
+MIT

package/build/src/client.d.ts

@@ -0,0 +1,10 @@
+export declare class SpritzClient {
+    private apiKey;
+    private baseUrl;
+    private sessionId;
+    private sessionCreatedAt;
+    constructor();
+    private getSessionId;
+    request(method: string, path: string, body?: Record<string, unknown>): Promise<any>;
+}
+//# sourceMappingURL=client.d.ts.map

package/build/src/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"AAMA,qBAAa,YAAY;IACvB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,gBAAgB,CAAS;;IAcjC,OAAO,CAAC,YAAY;IAQd,OAAO,CACX,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAyBjC"}

package/build/src/client.js

@@ -0,0 +1,43 @@
+import { randomUUID } from "node:crypto";
+const USER_AGENT = "spritz-mcp-server/0.1.0";
+const ORIGIN = "https://mcp.spritz.finance";
+const SESSION_TTL_MS = 15 * 60 * 1000;
+export class SpritzClient {
+    constructor() {
+        this.apiKey = process.env.SPRITZ_API_KEY || "";
+        this.baseUrl =
+            process.env.SPRITZ_API_BASE_URL || "https://platform.spritz.finance";
+        this.sessionId = randomUUID();
+        this.sessionCreatedAt = Date.now();
+        if (!this.apiKey) {
+            throw new Error("SPRITZ_API_KEY must be set in environment variables");
+        }
+    }
+    getSessionId() {
+        if (Date.now() - this.sessionCreatedAt >= SESSION_TTL_MS) {
+            this.sessionId = randomUUID();
+            this.sessionCreatedAt = Date.now();
+        }
+        return this.sessionId;
+    }
+    async request(method, path, body) {
+        const url = `${this.baseUrl}${path}`;
+        const response = await fetch(url, {
+            method,
+            headers: {
+                Authorization: `Bearer ${this.apiKey}`,
+                "Content-Type": "application/json",
+                "User-Agent": USER_AGENT,
+                Origin: ORIGIN,
+                "session-id": this.getSessionId(),
+            },
+            ...(body ? { body: JSON.stringify(body) } : {}),
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new Error(`Spritz API error: ${response.status} ${response.statusText} - ${errorText}`);
+        }
+        return response.json();
+    }
+}
+//# sourceMappingURL=client.js.map

package/build/src/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,MAAM,UAAU,GAAG,yBAAyB,CAAC;AAC7C,MAAM,MAAM,GAAG,4BAA4B,CAAC;AAC5C,MAAM,cAAc,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAEtC,MAAM,OAAO,YAAY;IAMvB;QACE,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,cAAc,IAAI,EAAE,CAAC;QAC/C,IAAI,CAAC,OAAO;YACV,OAAO,CAAC,GAAG,CAAC,mBAAmB,IAAI,iCAAiC,CAAC;QACvE,IAAI,CAAC,SAAS,GAAG,UAAU,EAAE,CAAC;QAC9B,IAAI,CAAC,gBAAgB,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAEnC,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;YACjB,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;QACzE,CAAC;IACH,CAAC;IAEO,YAAY;QAClB,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,gBAAgB,IAAI,cAAc,EAAE,CAAC;YACzD,IAAI,CAAC,SAAS,GAAG,UAAU,EAAE,CAAC;YAC9B,IAAI,CAAC,gBAAgB,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACrC,CAAC;QACD,OAAO,IAAI,CAAC,SAAS,CAAC;IACxB,CAAC;IAED,KAAK,CAAC,OAAO,CACX,MAAc,EACd,IAAY,EACZ,IAA8B;QAE9B,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,OAAO,GAAG,IAAI,EAAE,CAAC;QAErC,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;YAChC,MAAM;YACN,OAAO,EAAE;gBACP,aAAa,EAAE,UAAU,IAAI,CAAC,MAAM,EAAE;gBACtC,cAAc,EAAE,kBAAkB;gBAClC,YAAY,EAAE,UAAU;gBACxB,MAAM,EAAE,MAAM;gBACd,YAAY,EAAE,IAAI,CAAC,YAAY,EAAE;aAClC;YACD,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAChD,CAAC,CAAC;QAEH,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC;YACjB,MAAM,SAAS,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;YACxC,MAAM,IAAI,KAAK,CACb,qBAAqB,QAAQ,CAAC,MAAM,IAAI,QAAQ,CAAC,UAAU,MAAM,SAAS,EAAE,CAC7E,CAAC;QACJ,CAAC;QAED,OAAO,QAAQ,CAAC,IAAI,EAAE,CAAC;IACzB,CAAC;CACF"}

package/build/src/config.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Which OpenAPI operations to expose as MCP tools.
+ *
+ * To add a new tool: add an entry here with the operationId from openapi.json.
+ * The inputSchema and HTTP details are derived from the spec automatically.
+ */
+export interface ToolConfig {
+    /** MCP tool name (what the AI agent sees) */
+    name: string;
+    /** operationId from the OpenAPI spec */
+    operationId: string;
+    /** Override the spec's summary/description */
+    description?: string;
+}
+export declare const EXPOSED_TOOLS: ToolConfig[];
+//# sourceMappingURL=config.d.ts.map

package/build/src/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/config.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,UAAU;IACzB,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,wCAAwC;IACxC,WAAW,EAAE,MAAM,CAAC;IACpB,8CAA8C;IAC9C,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,eAAO,MAAM,aAAa,EAAE,UAAU,EAMrC,CAAC"}

package/build/src/config.js

@@ -0,0 +1,14 @@
+/**
+ * Which OpenAPI operations to expose as MCP tools.
+ *
+ * To add a new tool: add an entry here with the operationId from openapi.json.
+ * The inputSchema and HTTP details are derived from the spec automatically.
+ */
+export const EXPOSED_TOOLS = [
+    {
+        name: "list_bank_accounts",
+        operationId: "getV1Bank-accounts",
+        description: "List all bank accounts saved as off-ramp payment destinations.",
+    },
+];
+//# sourceMappingURL=config.js.map

package/build/src/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/config.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAWH,MAAM,CAAC,MAAM,aAAa,GAAiB;IACzC;QACE,IAAI,EAAE,oBAAoB;QAC1B,WAAW,EAAE,oBAAoB;QACjC,WAAW,EAAE,gEAAgE;KAC9E;CACF,CAAC"}

package/build/src/handlers.d.ts

@@ -0,0 +1,21 @@
+import { CallToolRequest } from "@modelcontextprotocol/sdk/types.js";
+import type { SpritzClient } from "./client.js";
+import type { ResolvedOperation } from "./spec.js";
+/**
+ * Generic handler that dispatches MCP tool calls to the Spritz API
+ * based on resolved OpenAPI operations.
+ */
+export declare function handleToolCall(request: CallToolRequest, operations: ResolvedOperation[], client: SpritzClient): Promise<{
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: boolean;
+} | {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError?: undefined;
+}>;
+//# sourceMappingURL=handlers.d.ts.map

package/build/src/handlers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handlers.d.ts","sourceRoot":"","sources":["../../src/handlers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AACrE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAEnD;;;GAGG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,eAAe,EACxB,UAAU,EAAE,iBAAiB,EAAE,EAC/B,MAAM,EAAE,YAAY;;;;;;;;;;;;GAoDrB"}

package/build/src/handlers.js

@@ -0,0 +1,50 @@
+/**
+ * Generic handler that dispatches MCP tool calls to the Spritz API
+ * based on resolved OpenAPI operations.
+ */
+export async function handleToolCall(request, operations, client) {
+    const { name, arguments: args } = request.params;
+    const op = operations.find((o) => o.config.name === name);
+    if (!op) {
+        return {
+            content: [{ type: "text", text: `Error: Unknown tool "${name}"` }],
+            isError: true,
+        };
+    }
+    try {
+        // Substitute path parameters, e.g. /v1/bank-accounts/{accountId}
+        let path = op.path;
+        const queryParams = {};
+        const bodyParams = {};
+        // Separate args into path params, query params, and body params
+        const pathParamNames = [...path.matchAll(/\{(\w+)\}/g)].map((m) => m[1]);
+        for (const [key, value] of Object.entries(args ?? {})) {
+            if (pathParamNames.includes(key)) {
+                path = path.replace(`{${key}}`, encodeURIComponent(String(value)));
+            }
+            else if (op.method === "get" || op.method === "delete") {
+                queryParams[key] = String(value);
+            }
+            else {
+                bodyParams[key] = value;
+            }
+        }
+        // Build query string for GET/DELETE
+        const qs = new URLSearchParams(queryParams).toString();
+        if (qs)
+            path = `${path}?${qs}`;
+        // Make the request
+        const result = await client.request(op.method.toUpperCase(), path, Object.keys(bodyParams).length > 0 ? bodyParams : undefined);
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : "Unknown error";
+        return {
+            content: [{ type: "text", text: `Error: ${message}` }],
+            isError: true,
+        };
+    }
+}
+//# sourceMappingURL=handlers.js.map

package/build/src/handlers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handlers.js","sourceRoot":"","sources":["../../src/handlers.ts"],"names":[],"mappings":"AAIA;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,OAAwB,EACxB,UAA+B,EAC/B,MAAoB;IAEpB,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAEjD,MAAM,EAAE,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC;IAC1D,IAAI,CAAC,EAAE,EAAE,CAAC;QACR,OAAO;YACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,wBAAwB,IAAI,GAAG,EAAE,CAAC;YAC3E,OAAO,EAAE,IAAI;SACd,CAAC;IACJ,CAAC;IAED,IAAI,CAAC;QACH,iEAAiE;QACjE,IAAI,IAAI,GAAG,EAAE,CAAC,IAAI,CAAC;QACnB,MAAM,WAAW,GAA2B,EAAE,CAAC;QAC/C,MAAM,UAAU,GAA4B,EAAE,CAAC;QAE/C,gEAAgE;QAChE,MAAM,cAAc,GAAG,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QAEzE,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,IAAI,EAAE,CAAC,EAAE,CAAC;YACtD,IAAI,cAAc,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;gBACjC,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,GAAG,GAAG,EAAE,kBAAkB,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YACrE,CAAC;iBAAM,IAAI,EAAE,CAAC,MAAM,KAAK,KAAK,IAAI,EAAE,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;gBACzD,WAAW,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;YACnC,CAAC;iBAAM,CAAC;gBACN,UAAU,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;YAC1B,CAAC;QACH,CAAC;QAED,oCAAoC;QACpC,MAAM,EAAE,GAAG,IAAI,eAAe,CAAC,WAAW,CAAC,CAAC,QAAQ,EAAE,CAAC;QACvD,IAAI,EAAE;YAAE,IAAI,GAAG,GAAG,IAAI,IAAI,EAAE,EAAE,CAAC;QAE/B,mBAAmB;QACnB,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,OAAO,CACjC,EAAE,CAAC,MAAM,CAAC,WAAW,EAAE,EACvB,IAAI,EACJ,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS,CAC5D,CAAC;QAEF,OAAO;YACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;SAC5E,CAAC;IACJ,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,CAAC;QACzE,OAAO;YACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,UAAU,OAAO,EAAE,EAAE,CAAC;YAC/D,OAAO,EAAE,IAAI;SACd,CAAC;IACJ,CAAC;AACH,CAAC"}

package/build/src/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/build/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":""}

package/build/src/index.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import dotenv from "dotenv";
+import { EXPOSED_TOOLS } from "./config.js";
+import { loadSpec, resolveTools, toMcpTools } from "./spec.js";
+import { handleToolCall } from "./handlers.js";
+import { SpritzClient } from "./client.js";
+dotenv.config();
+// ============================================================================
+// Server
+// ============================================================================
+async function main() {
+    if (!process.env.SPRITZ_API_KEY) {
+        console.error("Missing SPRITZ_API_KEY in environment variables.");
+        console.error("Create a .env file based on .env.example with your Spritz API key.");
+        process.exit(1);
+    }
+    // Load OpenAPI spec and resolve selected operations
+    const spec = loadSpec();
+    const operations = resolveTools(spec, EXPOSED_TOOLS);
+    const mcpTools = toMcpTools(operations);
+    const client = new SpritzClient();
+    const server = new Server({ name: "spritz-mcp-server", version: "0.1.0" }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: mcpTools,
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => handleToolCall(request, operations, client));
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("Spritz MCP Server is running via stdio");
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/build/src/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AACnE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EACL,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,MAAM,MAAM,QAAQ,CAAC;AAC5B,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAC/D,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,MAAM,CAAC,MAAM,EAAE,CAAC;AAEhB,+EAA+E;AAC/E,SAAS;AACT,+EAA+E;AAE/E,KAAK,UAAU,IAAI;IACjB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,EAAE,CAAC;QAChC,OAAO,CAAC,KAAK,CAAC,kDAAkD,CAAC,CAAC;QAClE,OAAO,CAAC,KAAK,CACX,oEAAoE,CACrE,CAAC;QACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,oDAAoD;IACpD,MAAM,IAAI,GAAG,QAAQ,EAAE,CAAC;IACxB,MAAM,UAAU,GAAG,YAAY,CAAC,IAAI,EAAE,aAAa,CAAC,CAAC;IACrD,MAAM,QAAQ,GAAG,UAAU,CAAC,UAAU,CAAC,CAAC;IAExC,MAAM,MAAM,GAAG,IAAI,YAAY,EAAE,CAAC;IAElC,MAAM,MAAM,GAAG,IAAI,MAAM,CACvB,EAAE,IAAI,EAAE,mBAAmB,EAAE,OAAO,EAAE,OAAO,EAAE,EAC/C,EAAE,YAAY,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,CAChC,CAAC;IAEF,MAAM,CAAC,iBAAiB,CAAC,sBAAsB,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC;QAC5D,KAAK,EAAE,QAAQ;KAChB,CAAC,CAAC,CAAC;IAEJ,MAAM,CAAC,iBAAiB,CAAC,qBAAqB,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,CAChE,cAAc,CAAC,OAAO,EAAE,UAAU,EAAE,MAAM,CAAC,CAC5C,CAAC;IAEF,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,OAAO,CAAC,KAAK,CAAC,wCAAwC,CAAC,CAAC;AAC1D,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACrB,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE,KAAK,CAAC,CAAC;IACrC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/build/src/spec.d.ts

@@ -0,0 +1,60 @@
+import type { ToolConfig } from "./config.js";
+export interface ResolvedOperation {
+    /** HTTP method (lowercase) */
+    method: string;
+    /** URL path template, e.g. /v1/bank-accounts/{accountId} */
+    path: string;
+    /** JSON Schema for the MCP tool's input */
+    inputSchema: Record<string, unknown>;
+    /** The original tool config entry */
+    config: ToolConfig;
+    /** Summary from the spec (fallback for description) */
+    summary: string;
+}
+export interface OpenAPIOperation {
+    operationId?: string;
+    summary?: string;
+    description?: string;
+    parameters?: OpenAPIParameter[];
+    requestBody?: {
+        content?: Record<string, {
+            schema?: Record<string, unknown>;
+        }>;
+    };
+}
+export interface OpenAPIParameter {
+    name: string;
+    in: string;
+    required?: boolean;
+    description?: string;
+    schema?: Record<string, unknown>;
+}
+export declare function loadSpec(): Record<string, unknown>;
+/**
+ * Walk every path+method in the spec and index by operationId.
+ */
+export declare function indexOperations(spec: Record<string, unknown>): Map<string, {
+    method: string;
+    path: string;
+    op: OpenAPIOperation;
+}>;
+/**
+ * Build a JSON Schema inputSchema for an MCP tool from an OpenAPI operation.
+ *
+ * Merges path params, query params, and request body into a single flat object schema.
+ */
+export declare function buildInputSchema(op: OpenAPIOperation): Record<string, unknown>;
+/**
+ * Resolve the selected tool configs against the OpenAPI spec.
+ * Throws if an operationId is not found.
+ */
+export declare function resolveTools(spec: Record<string, unknown>, tools: ToolConfig[]): ResolvedOperation[];
+/**
+ * Convert resolved operations to MCP tool definitions.
+ */
+export declare function toMcpTools(operations: ResolvedOperation[]): {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+}[];
+//# sourceMappingURL=spec.d.ts.map

package/build/src/spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec.d.ts","sourceRoot":"","sources":["../../src/spec.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAM9C,MAAM,WAAW,iBAAiB;IAChC,8BAA8B;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC;IACb,2CAA2C;IAC3C,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,qCAAqC;IACrC,MAAM,EAAE,UAAU,CAAC;IACnB,uDAAuD;IACvD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,gBAAgB;IAC/B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAChC,WAAW,CAAC,EAAE;QACZ,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;YAAE,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;SAAE,CAAC,CAAC;KAChE,CAAC;CACH;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAClC;AAMD,wBAAgB,QAAQ,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAIlD;AAMD;;GAEG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,GAAG,CAAC,MAAM,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,gBAAgB,CAAA;CAAE,CAAC,CAiBrE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,EAAE,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAqC9E;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,KAAK,EAAE,UAAU,EAAE,GAClB,iBAAiB,EAAE,CAuBrB;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,UAAU,EAAE,iBAAiB,EAAE;;;;IAMzD"}

package/build/src/spec.js

@@ -0,0 +1,108 @@
+import { readFileSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+// ============================================================================
+// Spec loading
+// ============================================================================
+export function loadSpec() {
+    const __dirname = dirname(fileURLToPath(import.meta.url));
+    const specPath = resolve(__dirname, "../../openapi.json");
+    return JSON.parse(readFileSync(specPath, "utf-8"));
+}
+// ============================================================================
+// Operation resolution
+// ============================================================================
+/**
+ * Walk every path+method in the spec and index by operationId.
+ */
+export function indexOperations(spec) {
+    const paths = spec["paths"];
+    if (!paths)
+        return new Map();
+    const index = new Map();
+    for (const [path, methods] of Object.entries(paths)) {
+        for (const [method, opOrRef] of Object.entries(methods)) {
+            if (typeof opOrRef !== "object" || opOrRef === null)
+                continue;
+            const op = opOrRef;
+            if (op.operationId) {
+                index.set(op.operationId, { method, path, op });
+            }
+        }
+    }
+    return index;
+}
+/**
+ * Build a JSON Schema inputSchema for an MCP tool from an OpenAPI operation.
+ *
+ * Merges path params, query params, and request body into a single flat object schema.
+ */
+export function buildInputSchema(op) {
+    const properties = {};
+    const required = [];
+    // Path and query parameters
+    for (const param of op.parameters ?? []) {
+        if (param.in === "path" || param.in === "query") {
+            properties[param.name] = {
+                ...param.schema,
+                ...(param.description ? { description: param.description } : {}),
+            };
+            if (param.required || param.in === "path") {
+                required.push(param.name);
+            }
+        }
+    }
+    // Request body (JSON only)
+    const bodySchema = op.requestBody?.content?.["application/json"]?.schema;
+    if (bodySchema && typeof bodySchema === "object" && "properties" in bodySchema) {
+        const bodyProps = bodySchema["properties"];
+        if (bodyProps) {
+            for (const [key, value] of Object.entries(bodyProps)) {
+                properties[key] = value;
+            }
+        }
+        const bodyRequired = bodySchema["required"];
+        if (bodyRequired) {
+            required.push(...bodyRequired);
+        }
+    }
+    return {
+        type: "object",
+        properties,
+        required,
+    };
+}
+/**
+ * Resolve the selected tool configs against the OpenAPI spec.
+ * Throws if an operationId is not found.
+ */
+export function resolveTools(spec, tools) {
+    const index = indexOperations(spec);
+    const resolved = [];
+    for (const config of tools) {
+        const entry = index.get(config.operationId);
+        if (!entry) {
+            throw new Error(`operationId "${config.operationId}" not found in OpenAPI spec. ` +
+                `Available: ${[...index.keys()].join(", ")}`);
+        }
+        resolved.push({
+            method: entry.method,
+            path: entry.path,
+            inputSchema: buildInputSchema(entry.op),
+            config,
+            summary: entry.op.summary ?? "",
+        });
+    }
+    return resolved;
+}
+/**
+ * Convert resolved operations to MCP tool definitions.
+ */
+export function toMcpTools(operations) {
+    return operations.map((op) => ({
+        name: op.config.name,
+        description: op.config.description ?? op.summary,
+        inputSchema: op.inputSchema,
+    }));
+}
+//# sourceMappingURL=spec.js.map

package/build/src/spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"spec.js","sourceRoot":"","sources":["../../src/spec.ts"],"names":[],"mappings":"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"}