@venlyfinance/settlement-mcp 0.1.0

package/dist/safety.js

@@ -0,0 +1,46 @@
+/**
+ * The write-tool safety gate. This is the core safety property of the server.
+ *
+ * A write tool executes a live call ONLY when ALL THREE hold:
+ *   1. the tool arg `confirm === true`
+ *   2. the env flag VENLY_MCP_LIVE === "1"
+ *   3. credentials are present (client id + secret in env)
+ *
+ * If ANY is missing the tool returns a dry-run object describing the exact
+ * request it WOULD have sent, and never calls the transport. Fail closed.
+ */
+import { LIVE_FLAG } from "./constants.js";
+export function credentialsPresent(env) {
+    return Boolean(env.VENLY_CLIENT_ID && env.VENLY_CLIENT_SECRET);
+}
+export function evaluateWriteGate(confirm, env) {
+    const liveFlagArmed = env[LIVE_FLAG] === "1";
+    const creds = credentialsPresent(env);
+    const blockedReasons = [];
+    if (!confirm)
+        blockedReasons.push("confirm arg is not true");
+    if (!liveFlagArmed)
+        blockedReasons.push(`${LIVE_FLAG} is not set to "1"`);
+    if (!creds)
+        blockedReasons.push("credentials are not present in env");
+    return {
+        armed: confirm && liveFlagArmed && creds,
+        confirm,
+        liveFlagArmed,
+        credentialsPresent: creds,
+        blockedReasons,
+    };
+}
+export function buildDryRun(tool, method, api, path, body, gate) {
+    return {
+        mode: "dry-run",
+        tool,
+        method,
+        api,
+        path,
+        body,
+        gate,
+        note: "No live call was made. To execute, set confirm:true AND VENLY_MCP_LIVE=1 " +
+            "AND provide VENLY_CLIENT_ID / VENLY_CLIENT_SECRET.",
+    };
+}

package/dist/server.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Build the MCP server: registers all three tool tiers over an injected
+ * VenlyClient. Kept transport-agnostic so tests can construct the server with a
+ * mock client and no network.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { VenlyClient } from "./types.js";
+import type { EnvLike } from "./safety.js";
+export interface CreateServerOptions {
+    client: VenlyClient;
+    /** Env used for the write gate. Defaults to process.env. */
+    env?: EnvLike;
+}
+export declare function createServer(options: CreateServerOptions): McpServer;

package/dist/server.js

@@ -0,0 +1,21 @@
+/**
+ * Build the MCP server: registers all three tool tiers over an injected
+ * VenlyClient. Kept transport-agnostic so tests can construct the server with a
+ * mock client and no network.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { SERVER_NAME, SERVER_VERSION } from "./constants.js";
+import { registerReadTools } from "./tools/read-tools.js";
+import { registerWriteTools } from "./tools/write-tools.js";
+import { registerX402Tools } from "./tools/x402-tools.js";
+export function createServer(options) {
+    const env = options.env ?? process.env;
+    const server = new McpServer({
+        name: SERVER_NAME,
+        version: SERVER_VERSION,
+    });
+    registerReadTools(server, options.client);
+    registerWriteTools(server, options.client, env);
+    registerX402Tools(server);
+    return server;
+}

package/dist/tools/read-tools.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Tier 1: READ tools. Always on. Call SDK/transport GETs only. No mutation.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { VenlyClient } from "../types.js";
+export declare function registerReadTools(server: McpServer, client: VenlyClient): void;

package/dist/tools/read-tools.js

@@ -0,0 +1,196 @@
+/**
+ * Tier 1: READ tools. Always on. Call SDK/transport GETs only. No mutation.
+ */
+import { z } from "zod";
+import { reconcileByReferenceCode } from "../reconcile.js";
+/** Serialize a result as a text-content tool response. */
+function jsonResult(data) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+    };
+}
+function errorResult(message) {
+    return {
+        content: [{ type: "text", text: `Error: ${message}` }],
+        isError: true,
+    };
+}
+const READ_ONLY = {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: true,
+};
+export function registerReadTools(server, client) {
+    server.registerTool("list_ramp_requests", {
+        title: "List ramp requests",
+        description: "List on-ramp / off-ramp requests (fundflow GET /v1/ramp-requests). " +
+            "Filter by rampType, status, date range, or paymentReference. Read-only.",
+        inputSchema: {
+            rampType: z.enum(["ON_RAMP", "OFF_RAMP"]).optional(),
+            status: z
+                .enum([
+                "AWAITING_APPROVAL",
+                "AWAITING_FUNDS",
+                "PROCESSING",
+                "SUCCEEDED",
+                "FAILED",
+                "BLOCKED",
+                "DENIED",
+                "REJECTED",
+                "CANCELLED",
+            ])
+                .optional(),
+            fromDate: z.string().optional().describe("YYYY-MM-DD inclusive"),
+            toDate: z.string().optional().describe("YYYY-MM-DD inclusive"),
+            paymentReference: z.string().optional(),
+            page: z.number().int().min(1).optional(),
+            size: z.number().int().min(1).max(200).optional(),
+        },
+        annotations: READ_ONLY,
+    }, async (params) => {
+        try {
+            const result = await client.listRampRequests(params);
+            return jsonResult({ count: result.length, rampRequests: result });
+        }
+        catch (e) {
+            return errorResult(e.message);
+        }
+    });
+    server.registerTool("get_ramp_request", {
+        title: "Get ramp request",
+        description: "Fetch a single ramp request with full detail incl. status and four-eyes " +
+            "version (fundflow GET /v1/ramp-requests/{id}). Read-only.",
+        inputSchema: { id: z.string().describe("Ramp request UUID") },
+        annotations: READ_ONLY,
+    }, async ({ id }) => {
+        try {
+            return jsonResult(await client.getRampRequest(id));
+        }
+        catch (e) {
+            return errorResult(e.message);
+        }
+    });
+    server.registerTool("get_account", {
+        title: "Get account",
+        description: "Fetch a settlement account (finance GET /accounts/{accountId}). Read-only.",
+        inputSchema: { accountId: z.string().describe("Account UUID") },
+        annotations: READ_ONLY,
+    }, async ({ accountId }) => {
+        try {
+            return jsonResult(await client.getAccount(accountId));
+        }
+        catch (e) {
+            return errorResult(e.message);
+        }
+    });
+    server.registerTool("list_virtual_bank_accounts", {
+        title: "List virtual bank accounts",
+        description: "List the EUR vIBANs on an account, each with its reconciliation " +
+            "referenceCode (finance GET /accounts/{accountId}/virtual-bank-accounts). Read-only.",
+        inputSchema: { accountId: z.string().describe("Account UUID") },
+        annotations: READ_ONLY,
+    }, async ({ accountId }) => {
+        try {
+            const result = await client.listVirtualBankAccounts(accountId);
+            return jsonResult({ count: result.length, virtualBankAccounts: result });
+        }
+        catch (e) {
+            return errorResult(e.message);
+        }
+    });
+    server.registerTool("reconcile_by_reference_code", {
+        title: "Reconcile by referenceCode",
+        description: "Match observed incoming bank transactions on an account's EUR vIBANs to " +
+            "the vIBAN whose referenceCode they carry. Fetches the account's vIBANs " +
+            "(finance GET .../virtual-bank-accounts) and matches against the supplied " +
+            "transactions. Read-only, no mutation. Returns the matched vIBAN, matched " +
+            "transactions, and total amount.",
+        inputSchema: {
+            accountId: z.string().describe("Account UUID whose vIBANs to reconcile against"),
+            referenceCode: z.string().describe("The reference code to reconcile"),
+            transactions: z
+                .array(z.object({
+                referenceCode: z.string(),
+                amount: z.number(),
+                currency: z.string(),
+                remitterName: z.string().optional(),
+                valueDate: z.string().optional(),
+                bankTransactionId: z.string().optional(),
+            }))
+                .default([])
+                .describe("Observed incoming bank transactions (operator- or feed-supplied)"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ accountId, referenceCode, transactions }) => {
+        try {
+            const vbans = await client.listVirtualBankAccounts(accountId);
+            const result = reconcileByReferenceCode(referenceCode, vbans, transactions);
+            return jsonResult(result);
+        }
+        catch (e) {
+            return errorResult(e.message);
+        }
+    });
+    server.registerTool("get_transfer", {
+        title: "Get transfer",
+        description: "Fetch a transfer by id (finance GET /accounts/{accountId}/transfers/{transferId}). Read-only.",
+        inputSchema: {
+            accountId: z.string().describe("Account UUID"),
+            transferId: z.string().describe("Transfer UUID"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ accountId, transferId }) => {
+        try {
+            return jsonResult(await client.getTransfer(accountId, transferId));
+        }
+        catch (e) {
+            return errorResult(e.message);
+        }
+    });
+    server.registerTool("list_parties", {
+        title: "List parties",
+        description: "List parties (individuals and organisations) (finance GET /parties). Read-only.",
+        inputSchema: {
+            page: z.number().int().min(1).optional(),
+            size: z.number().int().min(1).max(200).optional(),
+        },
+        annotations: READ_ONLY,
+    }, async (params) => {
+        try {
+            const result = await client.listParties(params);
+            return jsonResult({ count: result.length, parties: result });
+        }
+        catch (e) {
+            return errorResult(e.message);
+        }
+    });
+    server.registerTool("get_reference_data", {
+        title: "Get reference data",
+        description: "Fetch settlement reference data: supported chains, fiat currencies, " +
+            "cryptocurrencies, and company fees (fundflow GETs). Read-only. Choose one " +
+            "dataset or 'all'.",
+        inputSchema: {
+            dataset: z
+                .enum(["chains", "fiat_currencies", "cryptocurrencies", "fees", "all"])
+                .default("all"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ dataset }) => {
+        try {
+            const out = {};
+            if (dataset === "chains" || dataset === "all")
+                out.chains = await client.getSupportedChains();
+            if (dataset === "fiat_currencies" || dataset === "all")
+                out.fiatCurrencies = await client.getFiatCurrencies();
+            if (dataset === "cryptocurrencies" || dataset === "all")
+                out.cryptocurrencies = await client.getCryptocurrencies();
+            if (dataset === "fees" || dataset === "all")
+                out.fees = await client.getCompanyFees();
+            return jsonResult(out);
+        }
+        catch (e) {
+            return errorResult(e.message);
+        }
+    });
+}

package/dist/tools/write-tools.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Tier 2: WRITE tools. Present but DISARMED by default.
+ *
+ * Every write tool is dry-run UNLESS all three hold: confirm===true AND
+ * VENLY_MCP_LIVE==="1" AND credentials present (see safety.ts). When not armed
+ * it returns the exact request it WOULD send and never touches the transport.
+ * This is the core safety property, proven by test/write-tools.test.ts.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { VenlyClient } from "../types.js";
+import { type EnvLike } from "../safety.js";
+export declare function registerWriteTools(server: McpServer, client: VenlyClient, env: EnvLike): void;

package/dist/tools/write-tools.js

@@ -0,0 +1,161 @@
+/**
+ * Tier 2: WRITE tools. Present but DISARMED by default.
+ *
+ * Every write tool is dry-run UNLESS all three hold: confirm===true AND
+ * VENLY_MCP_LIVE==="1" AND credentials present (see safety.ts). When not armed
+ * it returns the exact request it WOULD send and never touches the transport.
+ * This is the core safety property, proven by test/write-tools.test.ts.
+ */
+import { z } from "zod";
+import { buildDryRun, evaluateWriteGate } from "../safety.js";
+function jsonResult(data) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+    };
+}
+function errorResult(message) {
+    return {
+        content: [{ type: "text", text: `Error: ${message}` }],
+        isError: true,
+    };
+}
+const WRITE_ANNOTATIONS = {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true,
+};
+const confirmField = z
+    .boolean()
+    .default(false)
+    .describe("Must be true to attempt a live call. Even then, VENLY_MCP_LIVE=1 and " +
+    "credentials are also required, otherwise the tool dry-runs.");
+export function registerWriteTools(server, client, env) {
+    server.registerTool("stage_transfer", {
+        title: "Stage a fiat transfer (dry-run by default)",
+        description: "Stage a fiat-to-crypto transfer (finance POST /accounts/{senderAccountId}/transfers/fiat). " +
+            "DISARMED by default: returns the exact request it would send unless " +
+            "confirm:true AND VENLY_MCP_LIVE=1 AND credentials are present.",
+        inputSchema: {
+            senderAccountId: z.string().describe("Account initiating the transfer"),
+            receiverAccountId: z.string(),
+            fiatAmount: z.string().describe("Decimal string, e.g. \"1000.00\""),
+            fiatCurrency: z.string().describe("e.g. EUR"),
+            cryptocurrency: z.string().optional(),
+            description: z.string().optional(),
+            merchantReference: z.string().optional(),
+            confirm: confirmField,
+        },
+        annotations: WRITE_ANNOTATIONS,
+    }, async ({ senderAccountId, confirm, ...rest }) => {
+        const gate = evaluateWriteGate(confirm, env);
+        const body = {
+            receiverAccountId: rest.receiverAccountId,
+            fiatAmount: rest.fiatAmount,
+            fiatCurrency: rest.fiatCurrency,
+            cryptocurrency: rest.cryptocurrency,
+            description: rest.description,
+            merchantReference: rest.merchantReference,
+        };
+        if (!gate.armed) {
+            return jsonResult(buildDryRun("stage_transfer", "POST", "finance", `/accounts/${senderAccountId}/transfers/fiat`, body, gate));
+        }
+        try {
+            const result = await client.createFiatTransfer(senderAccountId, body);
+            return jsonResult({ mode: "live", result });
+        }
+        catch (e) {
+            return errorResult(e.message);
+        }
+    });
+    server.registerTool("approve_ramp_request", {
+        title: "Approve a ramp request (dry-run by default)",
+        description: "Approve a ramp request through four-eyes (fundflow POST /v1/ramp-requests/{id}/approve). " +
+            "Requires the current optimistic-locking version. The API enforces that an " +
+            "identity cannot approve a request it created; this tool surfaces that state, " +
+            "it does not bypass it. DISARMED by default.",
+        inputSchema: {
+            id: z.string().describe("Ramp request UUID"),
+            version: z
+                .number()
+                .int()
+                .describe("Current version (from get_ramp_request) for optimistic locking"),
+            confirm: confirmField,
+        },
+        annotations: WRITE_ANNOTATIONS,
+    }, async ({ id, version, confirm }) => {
+        const gate = evaluateWriteGate(confirm, env);
+        const body = { version };
+        if (!gate.armed) {
+            return jsonResult(buildDryRun("approve_ramp_request", "POST", "fundflow", `/v1/ramp-requests/${id}/approve`, body, gate));
+        }
+        try {
+            const result = await client.approveRampRequest(id, body);
+            return jsonResult({ mode: "live", result });
+        }
+        catch (e) {
+            return errorResult(e.message);
+        }
+    });
+    server.registerTool("reject_ramp_request", {
+        title: "Reject a ramp request (dry-run by default)",
+        description: "Reject a ramp request (fundflow POST /v1/ramp-requests/{id}/reject). " +
+            "Requires the current optimistic-locking version. DISARMED by default.",
+        inputSchema: {
+            id: z.string().describe("Ramp request UUID"),
+            version: z
+                .number()
+                .int()
+                .describe("Current version (from get_ramp_request) for optimistic locking"),
+            confirm: confirmField,
+        },
+        annotations: WRITE_ANNOTATIONS,
+    }, async ({ id, version, confirm }) => {
+        const gate = evaluateWriteGate(confirm, env);
+        const body = { version };
+        if (!gate.armed) {
+            return jsonResult(buildDryRun("reject_ramp_request", "POST", "fundflow", `/v1/ramp-requests/${id}/reject`, body, gate));
+        }
+        try {
+            const result = await client.rejectRampRequest(id, body);
+            return jsonResult({ mode: "live", result });
+        }
+        catch (e) {
+            return errorResult(e.message);
+        }
+    });
+    server.registerTool("create_payment_link", {
+        title: "Create a fiat-to-crypto payment link (dry-run by default)",
+        description: "Create a pay-in link (finance POST /accounts/{accountId}/fiat-to-crypto/payment-links). " +
+            "DISARMED by default.",
+        inputSchema: {
+            accountId: z.string(),
+            inAmount: z.string().describe("Decimal string, e.g. \"250.00\""),
+            inCurrency: z.string().describe("e.g. EUR"),
+            outCryptocurrency: z.string().optional().describe("e.g. USDC"),
+            redirectUrl: z.string().optional(),
+            externalRef: z.string().optional(),
+            confirm: confirmField,
+        },
+        annotations: WRITE_ANNOTATIONS,
+    }, async ({ accountId, confirm, ...rest }) => {
+        const gate = evaluateWriteGate(confirm, env);
+        const body = {
+            inAmount: rest.inAmount,
+            inCurrency: rest.inCurrency,
+            outCryptocurrency: rest.outCryptocurrency,
+            redirectUrl: rest.redirectUrl,
+            externalRef: rest.externalRef,
+        };
+        if (!gate.armed) {
+            return jsonResult(buildDryRun("create_payment_link", "POST", "finance", `/accounts/${accountId}/fiat-to-crypto/payment-links`, body, gate));
+        }
+        try {
+            const result = await client.createPaymentLink(accountId, body);
+            return jsonResult({ mode: "live", result });
+        }
+        catch (e) {
+            return errorResult(e.message);
+        }
+    });
+}

package/dist/tools/x402-tools.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Tier 3: x402 tool. Position + stub, no execution.
+ *
+ * The machine-to-machine agent-payments rail is consolidating on x402
+ * (Cloudflare + Coinbase x402 Foundation; MCP tools return HTTP 402). This tool
+ * returns an HTTP-402-shaped quote for a settlement action, documenting the rail
+ * without executing it. It NEVER moves funds and NEVER calls a facilitator.
+ *
+ * Shape follows the x402 `PaymentRequirements` model: a 402 response carrying an
+ * `accepts` array of payment options (scheme, network, asset, payTo, amount).
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerX402Tools(server: McpServer): void;

package/dist/tools/x402-tools.js

@@ -0,0 +1,95 @@
+/**
+ * Tier 3: x402 tool. Position + stub, no execution.
+ *
+ * The machine-to-machine agent-payments rail is consolidating on x402
+ * (Cloudflare + Coinbase x402 Foundation; MCP tools return HTTP 402). This tool
+ * returns an HTTP-402-shaped quote for a settlement action, documenting the rail
+ * without executing it. It NEVER moves funds and NEVER calls a facilitator.
+ *
+ * Shape follows the x402 `PaymentRequirements` model: a 402 response carrying an
+ * `accepts` array of payment options (scheme, network, asset, payTo, amount).
+ */
+import { z } from "zod";
+function jsonResult(data) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+    };
+}
+/** Minimal chain -> x402 network + default USDC asset address map (stub data). */
+const CHAIN_META = {
+    base: {
+        network: "base",
+        usdc: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
+    },
+    "base-sepolia": {
+        network: "base-sepolia",
+        usdc: "0x036CbD53842c5426634e7929541eC2318f3dCF7e",
+    },
+    polygon: {
+        network: "polygon",
+        usdc: "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359",
+    },
+};
+export function registerX402Tools(server) {
+    server.registerTool("quote_x402_payment", {
+        title: "Quote an x402 machine payment (stub)",
+        description: "Return an HTTP-402-shaped quote (price, asset, payTo, chain) for a " +
+            "settlement action on the x402 machine-to-machine rail. STUB: documents " +
+            "the rail and returns a well-formed 402 PaymentRequirements object. It does " +
+            "NOT execute a payment, call a facilitator, or move funds. Production x402 " +
+            "settlement needs a facilitator decision and live rails.",
+        inputSchema: {
+            action: z
+                .string()
+                .describe("The settlement action being priced, e.g. 'stage_transfer' or 'reconcile'"),
+            amount: z.string().describe("Price as a decimal string, e.g. \"1.50\""),
+            asset: z.string().default("USDC").describe("Settlement asset symbol"),
+            chain: z
+                .enum(["base", "base-sepolia", "polygon"])
+                .default("base")
+                .describe("Settlement chain"),
+            payTo: z
+                .string()
+                .describe("Recipient address that would receive the machine payment"),
+            resource: z
+                .string()
+                .optional()
+                .describe("Optional resource/endpoint the payment unlocks"),
+            description: z.string().optional(),
+        },
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async ({ action, amount, asset, chain, payTo, resource, description }) => {
+        const meta = CHAIN_META[chain] ?? CHAIN_META.base;
+        const quote = {
+            mode: "stub",
+            httpStatus: 402,
+            error: "payment_required",
+            x402Version: 1,
+            action,
+            accepts: [
+                {
+                    scheme: "exact",
+                    network: meta.network,
+                    asset,
+                    // For USDC the canonical on-chain asset address for the network.
+                    assetAddress: asset.toUpperCase() === "USDC" ? meta.usdc : undefined,
+                    maxAmountRequired: amount,
+                    payTo,
+                    resource: resource ?? `venly-settlement:${action}`,
+                    description: description ?? `x402 quote for settlement action '${action}' (stub, not executable).`,
+                    mimeType: "application/json",
+                    maxTimeoutSeconds: 60,
+                },
+            ],
+            note: "This is a position stub. No payment is executed and no facilitator is " +
+                "called. Venly's stance: the MCP is the human-gated operator surface; " +
+                "x402 is the machine-to-machine rail.",
+        };
+        return jsonResult(quote);
+    });
+}