@venlyfinance/settlement-mcp 0.1.0 → 0.2.0

package/dist/prompts.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerBuilderPrompts(server: McpServer): void;

package/dist/prompts.js

@@ -0,0 +1,43 @@
+import { z } from "zod";
+export function registerBuilderPrompts(server) {
+    server.registerPrompt("build_international_account", {
+        title: "Build an international account experience",
+        description: "Guide a coding agent to build a mock-first international account product over Venly Finance.",
+        argsSchema: {
+            productName: z.string().optional().describe("Working product name"),
+            customerType: z
+                .enum(["individual", "organisation", "both"])
+                .default("organisation"),
+            targetGeography: z
+                .string()
+                .optional()
+                .describe("Target geography to validate; never treated as supported by assumption"),
+        },
+    }, async ({ productName, customerType, targetGeography }) => ({
+        description: "Mock-first Venly Finance application-building brief",
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: `Build an international account reference experience${productName ? ` called ${productName}` : ""} for ${customerType} customers${targetGeography ? ` targeting ${targetGeography}` : ""}.
+
+Use this operating brief:
+
+1. Read venly://capabilities, venly://safety and venly://workflows/international-account before writing code.
+2. Start in explicit mock mode with VENLY_ENV=mock. Keep all simulated states visibly labelled Mock.
+3. Use @venlyfinance/sdk in server-side code. Never put Venly credentials or access tokens in browser code.
+4. Build the customer experience around atomic Finance capabilities: party, account, auto-provisioned wallet and balances, EUR receiving account, transfer and status/reconciliation.
+5. Do not claim that creating a party completes KYC/KYB. Display verification and pending states honestly.
+6. Venly supplies financial infrastructure through regulated partners. Do not describe the application or its customer as a licensed bank unless separately verified.
+7. EUR/SEPA virtual bank accounts are documented. Validate ${targetGeography ?? "the requested geography"} and any broader currency/coverage requirement instead of inferring support.
+8. Card issuing is not exposed by the current Finance contract; do not invent a card feature.
+9. Require an explicit user decision before switching to staging, adding credentials or arming writes. Dry-run staging mutations before confirmation.
+10. Produce a concise README showing mock setup, the unchanged SDK business logic and the explicit staging transition.
+
+Success means a credible money-product experience backed by real Venly contract shapes – not a generic dashboard and not a claim that the MCP itself generated a regulated bank.`,
+                },
+            },
+        ],
+    }));
+}

package/dist/reconcile.js

@@ -8,7 +8,13 @@
  */
 export function reconcileByReferenceCode(referenceCode, virtualBankAccounts, transactions) {
     const target = referenceCode.trim();
+    if (!target) {
+        throw new Error("referenceCode must not be blank");
+    }
     const vban = virtualBankAccounts.find((v) => (v.referenceCode ?? "").trim() === target) ?? null;
+    if (vban && !(vban.id ?? "").trim()) {
+        throw new Error("matching vIBAN is missing an id");
+    }
     const matchedTransactions = transactions.filter((t) => (t.referenceCode ?? "").trim() === target);
     const totalAmount = matchedTransactions.reduce((sum, t) => sum + (Number.isFinite(t.amount) ? t.amount : 0), 0);
     const currency = vban?.currency ?? matchedTransactions[0]?.currency ?? null;

package/dist/resources.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerBuilderResources(server: McpServer): void;

package/dist/resources.js

@@ -0,0 +1,106 @@
+const RESOURCES = [
+    {
+        name: "venly-finance-capabilities",
+        uri: "venly://capabilities",
+        title: "Venly Finance capabilities",
+        description: "Contract-backed builder capabilities and explicit product boundaries.",
+        text: `# Venly Finance capabilities
+
+Venly Finance provides financial infrastructure through several regulated partners. The public Finance contract exposes:
+
+- individual and organisation party records with KYC/KYB state;
+- accounts with an auto-provisioned wallet;
+- wallet balances split into total, available and reserved token amounts;
+- EUR SEPA virtual bank accounts with IBAN, BIC and reconciliation reference code;
+- fiat-to-crypto payment sessions;
+- account-to-account fiat-denominated and crypto-denominated transfers;
+- payment-request authorization, settlement and reversal primitives;
+- Fundflow on/off-ramp workflows with four-eyes approval.
+
+Current boundaries:
+
+- EUR is the currently documented virtual-bank-account currency. Do not infer global bank-account coverage.
+- Creating a party does not complete KYC/KYB. Live virtual-bank-account provisioning requires a VERIFIED account.
+- Card issuing is not exposed by the current Finance OpenAPI contract.
+- A bank charter, deposit insurance and external-bank payout coverage are not supplied or implied by this MCP.
+- Production x402 settlement is not implemented; the x402 tool is a quote-only stub.
+`,
+    },
+    {
+        name: "venly-finance-safety",
+        uri: "venly://safety",
+        title: "Venly Finance safety model",
+        description: "Environment, write, compliance and secret-handling rules.",
+        text: `# Venly Finance MCP safety
+
+- Set VENLY_ENV explicitly to mock, staging or production. An absent value remains staging for 0.x compatibility.
+- Mock mode uses synthetic SDK fixtures, no credentials and no network. Every mutation result is labelled mode=mock.
+- Staging writes require confirm=true, VENLY_MCP_LIVE=1 and VENLY_CLIENT_ID/VENLY_CLIENT_SECRET.
+- Production requires every staging gate plus VENLY_MCP_PRODUCTION=1.
+- There is no implicit fallback from staging or production to mock.
+- Mutations use idempotency keys where supported. Preserve a caller-supplied key across retries.
+- Fundflow approvals retain four-eyes and optimistic-locking rules.
+- Creating a party does not mean KYC/KYB has passed. A live virtual bank account requires KYC status VERIFIED.
+- Keep Venly credentials and access tokens server-side. Never place them in browser code, tool output or logs.
+- Never arm writes or move from mock to staging/production without an explicit user decision.
+`,
+    },
+    {
+        name: "international-account-workflow",
+        uri: "venly://workflows/international-account",
+        title: "International account golden workflow",
+        description: "Atomic tool order for an international-account reference experience.",
+        text: `# International account workflow
+
+Start with VENLY_ENV=mock.
+
+1. Call get_reference_data to inspect supported chains and assets.
+2. Call create_party for an INDIVIDUAL or ORGANISATION. Treat returned KYC/KYB state as a state, not an approval.
+3. Call create_account with the party ID and selected chain. The Finance API auto-provisions the account wallet.
+4. Call list_wallets and display returned total, available and reserved token balances.
+5. Call create_virtual_bank_account for EUR -> USDC. In live environments this requires a VERIFIED account.
+6. Call get_virtual_bank_account to display IBAN/BIC/referenceCode where returned.
+7. Call create_fiat_transfer or create_crypto_transfer using one stable idempotency key.
+8. Call list_transfers/get_transfer to display status.
+9. Use reconcile_by_reference_code when observed incoming bank transactions are available.
+
+Do not collapse this workflow into an autonomous mega-tool. Each mutation remains visible, inspectable and separately confirmed outside mock mode.
+`,
+    },
+    {
+        name: "mock-to-staging-workflow",
+        uri: "venly://workflows/mock-to-staging",
+        title: "Mock-to-staging transition",
+        description: "Configuration and compliance checklist for leaving simulation.",
+        text: `# Mock to staging
+
+Application business logic should continue to use @venlyfinance/sdk on the server side.
+
+1. Keep the mock experience working and visibly labelled.
+2. Set VENLY_ENV=staging and provide the VENLY_CLIENT_ID/VENLY_CLIENT_SECRET credentials through server-side secret storage.
+3. Confirm the tenant's custody model, enabled chains/assets and regulated-partner coverage.
+4. Use a documented VERIFIED test party/account before provisioning a live EUR virtual bank account.
+5. Run read-only smoke checks first. Do not set VENLY_MCP_LIVE until those checks pass.
+6. Dry-run every intended write, review its normalized request, then explicitly confirm it.
+
+There is no implicit fallback to mock. Authentication or capability failures must remain visible rather than returning synthetic data.
+`,
+    },
+];
+export function registerBuilderResources(server) {
+    for (const resource of RESOURCES) {
+        server.registerResource(resource.name, resource.uri, {
+            title: resource.title,
+            description: resource.description,
+            mimeType: "text/markdown",
+        }, async () => ({
+            contents: [
+                {
+                    uri: resource.uri,
+                    mimeType: "text/markdown",
+                    text: resource.text,
+                },
+            ],
+        }));
+    }
+}

package/dist/results.d.ts

@@ -0,0 +1,18 @@
+export declare function jsonResult(data: unknown): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent: Record<string, unknown>;
+};
+export declare function sanitizeErrorMessage(message: string): string;
+export declare function errorResult(message: string): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent: {
+        error: string;
+    };
+    isError: boolean;
+};

package/dist/results.js

@@ -0,0 +1,25 @@
+function toStructured(data) {
+    if (data !== null && typeof data === "object" && !Array.isArray(data)) {
+        return data;
+    }
+    return { result: data };
+}
+export function jsonResult(data) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+        structuredContent: toStructured(data),
+    };
+}
+export function sanitizeErrorMessage(message) {
+    return message
+        .replace(/(Authorization\s*:\s*Bearer\s+)[^\s,;]+/gi, "$1[REDACTED]")
+        .replace(/(client_secret\s*[=:]\s*)[^\s,;]+/gi, "$1[REDACTED]");
+}
+export function errorResult(message) {
+    const safeMessage = sanitizeErrorMessage(message);
+    return {
+        content: [{ type: "text", text: `Error: ${safeMessage}` }],
+        structuredContent: { error: safeMessage },
+        isError: true,
+    };
+}

package/dist/safety.d.ts

@@ -9,12 +9,15 @@
  * 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 { type VenlyEnvironment } from "./constants.js";
 export type EnvLike = Record<string, string | undefined>;
 export interface GateDecision {
-    /** true only when confirm + armed env + creds all hold. */
+    /** True in explicit mock mode, or when every live environment gate holds. */
     armed: boolean;
+    environment: VenlyEnvironment;
     confirm: boolean;
     liveFlagArmed: boolean;
+    productionFlagArmed: boolean;
     credentialsPresent: boolean;
     /** Human-readable reasons a live call is blocked (empty when armed). */
     blockedReasons: string[];
@@ -23,6 +26,7 @@ export declare function credentialsPresent(env: EnvLike): boolean;
 export declare function evaluateWriteGate(confirm: boolean, env: EnvLike): GateDecision;
 export interface DryRunRequest {
     mode: "dry-run";
+    environment: VenlyEnvironment;
     tool: string;
     method: "GET" | "POST" | "PUT" | "DELETE";
     /** Which API this maps to. */

package/dist/safety.js

@@ -9,13 +9,26 @@
  * 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";
+import { LIVE_FLAG, PRODUCTION_FLAG, resolveVenlyEnvironment, } from "./constants.js";
 export function credentialsPresent(env) {
     return Boolean(env.VENLY_CLIENT_ID && env.VENLY_CLIENT_SECRET);
 }
 export function evaluateWriteGate(confirm, env) {
+    const environment = resolveVenlyEnvironment(env);
     const liveFlagArmed = env[LIVE_FLAG] === "1";
+    const productionFlagArmed = env[PRODUCTION_FLAG] === "1";
     const creds = credentialsPresent(env);
+    if (environment === "mock") {
+        return {
+            armed: true,
+            environment,
+            confirm,
+            liveFlagArmed,
+            productionFlagArmed,
+            credentialsPresent: creds,
+            blockedReasons: [],
+        };
+    }
     const blockedReasons = [];
     if (!confirm)
         blockedReasons.push("confirm arg is not true");
@@ -23,10 +36,18 @@ export function evaluateWriteGate(confirm, env) {
         blockedReasons.push(`${LIVE_FLAG} is not set to "1"`);
     if (!creds)
         blockedReasons.push("credentials are not present in env");
+    if (environment === "production" && !productionFlagArmed) {
+        blockedReasons.push(`${PRODUCTION_FLAG} is not set to "1"`);
+    }
     return {
-        armed: confirm && liveFlagArmed && creds,
+        armed: confirm &&
+            liveFlagArmed &&
+            creds &&
+            (environment !== "production" || productionFlagArmed),
+        environment,
         confirm,
         liveFlagArmed,
+        productionFlagArmed,
         credentialsPresent: creds,
         blockedReasons,
     };
@@ -34,13 +55,15 @@ export function evaluateWriteGate(confirm, env) {
 export function buildDryRun(tool, method, api, path, body, gate) {
     return {
         mode: "dry-run",
+        environment: gate.environment,
         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.",
+        note: "No live call was made. To execute outside mock mode, set confirm:true AND " +
+            "VENLY_MCP_LIVE=1 AND provide VENLY_CLIENT_ID / VENLY_CLIENT_SECRET. " +
+            "Production additionally requires VENLY_MCP_PRODUCTION=1.",
     };
 }

package/dist/server.js

@@ -4,12 +4,24 @@
  * mock client and no network.
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { SERVER_NAME, SERVER_VERSION } from "./constants.js";
+import { ENVIRONMENT_FLAG, SERVER_NAME, SERVER_VERSION, resolveVenlyEnvironment, } from "./constants.js";
 import { registerReadTools } from "./tools/read-tools.js";
 import { registerWriteTools } from "./tools/write-tools.js";
 import { registerX402Tools } from "./tools/x402-tools.js";
+import { registerBuilderResources } from "./resources.js";
+import { registerBuilderPrompts } from "./prompts.js";
 export function createServer(options) {
     const env = options.env ?? process.env;
+    // The write gate auto-arms every mutation in mock mode on the assumption
+    // that the injected client is also mock. Refuse to start when a client that
+    // declares its environment disagrees with the env the gate will read –
+    // otherwise a mock env over a live client would execute un-gated writes.
+    const gateEnvironment = resolveVenlyEnvironment(env);
+    if (options.client.environment !== undefined &&
+        options.client.environment !== gateEnvironment) {
+        throw new Error(`client targets "${options.client.environment}" but ${ENVIRONMENT_FLAG} resolves to ` +
+            `"${gateEnvironment}"; the write gate and client must agree on the environment`);
+    }
     const server = new McpServer({
         name: SERVER_NAME,
         version: SERVER_VERSION,
@@ -17,5 +29,7 @@ export function createServer(options) {
     registerReadTools(server, options.client);
     registerWriteTools(server, options.client, env);
     registerX402Tools(server);
+    registerBuilderResources(server);
+    registerBuilderPrompts(server);
     return server;
 }

package/dist/staging-smoke.d.ts

@@ -0,0 +1,17 @@
+export declare const EXPECTED_TOOLS: readonly ["list_ramp_requests", "get_ramp_request", "list_accounts", "get_account", "list_wallets", "list_virtual_bank_accounts", "get_virtual_bank_account", "reconcile_by_reference_code", "list_transfers", "get_transfer", "list_parties", "get_party", "get_reference_data", "create_party", "create_account", "create_virtual_bank_account", "create_fiat_transfer", "create_crypto_transfer", "stage_transfer", "approve_ramp_request", "reject_ramp_request", "create_payment_session", "quote_x402_payment"];
+export declare const EXPECTED_RESOURCE_URIS: readonly ["venly://capabilities", "venly://safety", "venly://workflows/international-account", "venly://workflows/mock-to-staging"];
+export declare const EXPECTED_PROMPTS: readonly ["build_international_account"];
+export interface DiscoveryNames {
+    tools: string[];
+    resources: string[];
+    prompts: string[];
+}
+export declare function assertExpectedDiscovery(actual: DiscoveryNames): void;
+export declare function assertDryRunResult(result: unknown): void;
+export interface StagingSmokeOptions {
+    env?: NodeJS.ProcessEnv;
+    serverEntry?: string;
+    log?: (line: string) => void;
+}
+export declare function buildStagingChildEnv(env: NodeJS.ProcessEnv): Record<string, string>;
+export declare function runStagingSmoke(options?: StagingSmokeOptions): Promise<void>;

package/dist/staging-smoke.js

@@ -0,0 +1,199 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport, getDefaultEnvironment, } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { fileURLToPath } from "node:url";
+import { SERVER_VERSION } from "./constants.js";
+import { sanitizeErrorMessage } from "./results.js";
+export const EXPECTED_TOOLS = [
+    "list_ramp_requests",
+    "get_ramp_request",
+    "list_accounts",
+    "get_account",
+    "list_wallets",
+    "list_virtual_bank_accounts",
+    "get_virtual_bank_account",
+    "reconcile_by_reference_code",
+    "list_transfers",
+    "get_transfer",
+    "list_parties",
+    "get_party",
+    "get_reference_data",
+    "create_party",
+    "create_account",
+    "create_virtual_bank_account",
+    "create_fiat_transfer",
+    "create_crypto_transfer",
+    "stage_transfer",
+    "approve_ramp_request",
+    "reject_ramp_request",
+    "create_payment_session",
+    "quote_x402_payment",
+];
+export const EXPECTED_RESOURCE_URIS = [
+    "venly://capabilities",
+    "venly://safety",
+    "venly://workflows/international-account",
+    "venly://workflows/mock-to-staging",
+];
+export const EXPECTED_PROMPTS = ["build_international_account"];
+function assertExactMembers(label, expected, actual) {
+    const actualSet = new Set(actual);
+    const expectedSet = new Set(expected);
+    for (const name of expected) {
+        if (!actualSet.has(name))
+            throw new Error(`missing ${label}: ${name}`);
+    }
+    for (const name of actual) {
+        if (!expectedSet.has(name))
+            throw new Error(`unexpected ${label}: ${name}`);
+    }
+}
+export function assertExpectedDiscovery(actual) {
+    assertExactMembers("tool", EXPECTED_TOOLS, actual.tools);
+    assertExactMembers("resource", EXPECTED_RESOURCE_URIS, actual.resources);
+    assertExactMembers("prompt", EXPECTED_PROMPTS, actual.prompts);
+}
+function asRecord(value, label) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error(`${label} must be an object`);
+    }
+    return value;
+}
+export function assertDryRunResult(result) {
+    const record = asRecord(result, "write result");
+    const gate = asRecord(record.gate, "write gate");
+    if (record.mode !== "dry-run" ||
+        record.environment !== "staging" ||
+        gate.armed !== false ||
+        gate.liveFlagArmed !== false) {
+        throw new Error("expected a staging dry-run with both write gates disarmed");
+    }
+}
+function requireCredentials(env) {
+    const clientId = env.VENLY_CLIENT_ID;
+    const clientSecret = env.VENLY_CLIENT_SECRET;
+    if (!clientId || !clientSecret) {
+        throw new Error("Set VENLY_CLIENT_ID and VENLY_CLIENT_SECRET for the staging tenant.");
+    }
+    return { clientId, clientSecret };
+}
+function optionalEnvironment(env) {
+    const keys = [
+        "VENLY_FINANCE_BASE_URL",
+        "VENLY_FUNDFLOW_BASE_URL",
+        "VENLY_TOKEN_URL",
+    ];
+    const out = {};
+    for (const key of keys) {
+        if (env[key])
+            out[key] = env[key];
+    }
+    return out;
+}
+function structuredContent(result, label) {
+    const record = asRecord(result, label);
+    if (record.isError === true) {
+        const detail = Array.isArray(record.content)
+            ? record.content
+                .map((item) => item && typeof item === "object" && "text" in item
+                ? String(item.text)
+                : "")
+                .filter(Boolean)
+                .join("; ")
+            : "";
+        throw new Error(`${label} returned an MCP error${detail ? `: ${sanitizeErrorMessage(detail)}` : ""}`);
+    }
+    return asRecord(record.structuredContent, `${label} structuredContent`);
+}
+function countFrom(result, label) {
+    const content = structuredContent(result, label);
+    if (typeof content.count !== "number") {
+        throw new Error(`${label} did not return a numeric count`);
+    }
+    return content.count;
+}
+function referenceCounts(result) {
+    const content = structuredContent(result, "get_reference_data");
+    const counts = [];
+    for (const key of ["chains", "fiatCurrencies", "cryptocurrencies", "fees"]) {
+        const value = content[key];
+        if (!Array.isArray(value))
+            throw new Error(`get_reference_data missing ${key} array`);
+        counts.push(`${key}=${value.length}`);
+    }
+    return counts.join(", ");
+}
+export function buildStagingChildEnv(env) {
+    const { clientId, clientSecret } = requireCredentials(env);
+    return {
+        ...getDefaultEnvironment(),
+        ...optionalEnvironment(env),
+        VENLY_ENV: "staging",
+        VENLY_CLIENT_ID: clientId,
+        VENLY_CLIENT_SECRET: clientSecret,
+    };
+}
+export async function runStagingSmoke(options = {}) {
+    const env = options.env ?? process.env;
+    const log = options.log ?? console.log;
+    const serverEntry = options.serverEntry ?? fileURLToPath(new URL("./index.js", import.meta.url));
+    // The builder allowlists inherited variables and never copies live-write flags.
+    const childEnv = buildStagingChildEnv(env);
+    const transport = new StdioClientTransport({
+        command: process.execPath,
+        args: [serverEntry],
+        env: childEnv,
+        stderr: "inherit",
+    });
+    const client = new Client({
+        name: "venly-staging-smoke",
+        version: SERVER_VERSION,
+    });
+    try {
+        await client.connect(transport);
+        const [toolResult, resourceResult, promptResult] = await Promise.all([
+            client.listTools(),
+            client.listResources(),
+            client.listPrompts(),
+        ]);
+        assertExpectedDiscovery({
+            tools: toolResult.tools.map((tool) => tool.name),
+            resources: resourceResult.resources.map((resource) => resource.uri),
+            prompts: promptResult.prompts.map((prompt) => prompt.name),
+        });
+        log(`OK   discovery - tools=${toolResult.tools.length}, resources=${resourceResult.resources.length}, prompts=${promptResult.prompts.length}`);
+        const parties = await client.callTool({ name: "list_parties", arguments: { size: 1 } });
+        log(`OK   list_parties - count=${countFrom(parties, "list_parties")}`);
+        const accounts = await client.callTool({ name: "list_accounts", arguments: { size: 1 } });
+        log(`OK   list_accounts - count=${countFrom(accounts, "list_accounts")}`);
+        try {
+            const referenceData = await client.callTool({
+                name: "get_reference_data",
+                arguments: { dataset: "all" },
+            });
+            log(`OK   get_reference_data - ${referenceCounts(referenceData)}`);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            const isScopeError = /\b(401|403)\b/.test(message);
+            if (isScopeError && env.VENLY_SMOKE_ALLOW_FUNDFLOW_SKIP === "1") {
+                log("SKIP get_reference_data - credential lacks Fundflow scope (tolerated via VENLY_SMOKE_ALLOW_FUNDFLOW_SKIP=1); fundflow validated by spec-diff only");
+            }
+            else {
+                throw error;
+            }
+        }
+        const dryRun = await client.callTool({
+            name: "create_party",
+            arguments: {
+                partyType: "ORGANISATION",
+                name: "Venly staging smoke dry-run",
+                confirm: true,
+            },
+        });
+        assertDryRunResult(structuredContent(dryRun, "create_party"));
+        log("OK   create_party - confirmed request remained dry-run; zero mutation");
+    }
+    finally {
+        await client.close();
+    }
+}