@venlyfinance/settlement-mcp 0.1.1 → 0.3.0

package/dist/tools/read-tools.js

@@ -3,18 +3,7 @@
  */
 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,
-    };
-}
+import { errorResult, jsonResult } from "../results.js";
 const READ_ONLY = {
     readOnlyHint: true,
     destructiveHint: false,
@@ -71,6 +60,23 @@ export function registerReadTools(server, client) {
             return errorResult(e.message);
         }
     });
+    server.registerTool("list_accounts", {
+        title: "List accounts",
+        description: "List Venly Finance accounts before creating duplicates (finance GET /accounts). 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.listAccounts(params);
+            return jsonResult({ count: result.length, accounts: result });
+        }
+        catch (e) {
+            return errorResult(e.message);
+        }
+    });
     server.registerTool("get_account", {
         title: "Get account",
         description: "Fetch a settlement account (finance GET /accounts/{accountId}). Read-only.",
@@ -84,6 +90,24 @@ export function registerReadTools(server, client) {
             return errorResult(e.message);
         }
     });
+    server.registerTool("list_wallets", {
+        title: "List account wallets",
+        description: "List wallets auto-provisioned for a Finance account (finance GET /accounts/{accountId}/wallets). Read-only.",
+        inputSchema: {
+            accountId: z.string().describe("Account UUID"),
+            page: z.number().int().min(1).optional(),
+            size: z.number().int().min(1).max(200).optional(),
+        },
+        annotations: READ_ONLY,
+    }, async ({ accountId, page, size }) => {
+        try {
+            const result = await client.listWallets(accountId, { page, size });
+            return jsonResult({ count: result.length, wallets: result });
+        }
+        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 " +
@@ -99,19 +123,41 @@ export function registerReadTools(server, client) {
             return errorResult(e.message);
         }
     });
+    server.registerTool("get_virtual_bank_account", {
+        title: "Get virtual bank account",
+        description: "Fetch receiving-account details including status, IBAN/BIC and referenceCode. Read-only.",
+        inputSchema: {
+            accountId: z.string().describe("Account UUID"),
+            virtualBankAccountId: z.string().describe("Virtual bank account UUID"),
+        },
+        annotations: READ_ONLY,
+    }, async ({ accountId, virtualBankAccountId }) => {
+        try {
+            return jsonResult(await client.getVirtualBankAccount(accountId, virtualBankAccountId));
+        }
+        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. Matching is remittance-text tolerant: case- and " +
+            "separator-insensitive, and a transaction matches when its normalized " +
+            "reference CONTAINS the normalized code (real payers type 'invoice ref " +
+            "abc 123 ty'). Codes under 4 alphanumeric characters are refused. " +
+            "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(),
+                referenceCode: z
+                    .string()
+                    .describe("Remittance text as received - free-form is fine; matching normalizes it"),
                 amount: z.number(),
                 currency: z.string(),
                 remitterName: z.string().optional(),
@@ -132,6 +178,24 @@ export function registerReadTools(server, client) {
             return errorResult(e.message);
         }
     });
+    server.registerTool("list_transfers", {
+        title: "List transfers",
+        description: "List transfer history for an account (finance GET /accounts/{accountId}/transfers). Read-only.",
+        inputSchema: {
+            accountId: z.string().describe("Account UUID"),
+            page: z.number().int().min(1).optional(),
+            size: z.number().int().min(1).max(200).optional(),
+        },
+        annotations: READ_ONLY,
+    }, async ({ accountId, page, size }) => {
+        try {
+            const result = await client.listTransfers(accountId, { page, size });
+            return jsonResult({ count: result.length, transfers: 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.",
@@ -165,6 +229,19 @@ export function registerReadTools(server, client) {
             return errorResult(e.message);
         }
     });
+    server.registerTool("get_party", {
+        title: "Get party",
+        description: "Fetch an individual or organisation party, including KYC/KYB state when present. Read-only.",
+        inputSchema: { partyId: z.string().describe("Party UUID") },
+        annotations: READ_ONLY,
+    }, async ({ partyId }) => {
+        try {
+            return jsonResult(await client.getParty(partyId));
+        }
+        catch (e) {
+            return errorResult(e.message);
+        }
+    });
     server.registerTool("get_reference_data", {
         title: "Get reference data",
         description: "Fetch settlement reference data: supported chains, fiat currencies, " +

package/dist/tools/write-tools.js

@@ -8,16 +8,17 @@
  */
 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,
-    };
+import { errorResult, jsonResult } from "../results.js";
+import { normalizeLegacyFiatTransfer } from "../client/sdk-client.js";
+function executionResult(gate, result) {
+    return jsonResult({
+        mode: gate.environment === "mock" ? "mock" : "live",
+        // Explicit on every mutation result: this call DID execute (against local
+        // fixtures in mock, against the real API when armed).
+        dryRun: false,
+        environment: gate.environment,
+        result,
+    });
 }
 const WRITE_ANNOTATIONS = {
     readOnlyHint: false,
@@ -30,18 +31,230 @@ const confirmField = z
     .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.");
+const addressSchema = z
+    .object({
+    addressLine1: z.string().optional(),
+    addressLine2: z.string().optional(),
+    city: z.string().optional(),
+    state: z.string().optional(),
+    postalCode: z.string().optional(),
+    country: z.string().regex(/^[A-Z]{2}$/).optional(),
+})
+    .optional();
+const partySchema = z.object({
+    partyType: z.enum(["INDIVIDUAL", "ORGANISATION"]),
+    externalId: z.string().optional(),
+    firstName: z.string().optional(),
+    lastName: z.string().optional(),
+    name: z.string().optional(),
+    vatNumber: z.string().optional(),
+    address: addressSchema,
+});
+function partyValidationError(party) {
+    if (party.partyType === "INDIVIDUAL" && (!party.firstName || !party.lastName)) {
+        return "INDIVIDUAL parties require firstName and lastName";
+    }
+    if (party.partyType === "ORGANISATION" && !party.name) {
+        return "ORGANISATION parties require name";
+    }
+    return undefined;
+}
 export function registerWriteTools(server, client, env) {
+    server.registerTool("create_party", {
+        title: "Create a customer or organisation party",
+        description: "Create a Finance party. This creates the party record; it does not complete KYC/KYB. Dry-run by default outside explicit mock mode.",
+        inputSchema: {
+            partyType: z.enum(["INDIVIDUAL", "ORGANISATION"]),
+            externalId: z.string().optional(),
+            firstName: z.string().optional(),
+            lastName: z.string().optional(),
+            name: z.string().optional(),
+            vatNumber: z.string().optional(),
+            address: addressSchema,
+            confirm: confirmField,
+        },
+        annotations: WRITE_ANNOTATIONS,
+    }, async ({ confirm, ...party }) => {
+        const validationError = partyValidationError(party);
+        if (validationError)
+            return errorResult(validationError);
+        const gate = evaluateWriteGate(confirm, env);
+        if (!gate.armed) {
+            return jsonResult(buildDryRun("create_party", "POST", "finance", "/parties", party, gate));
+        }
+        try {
+            return executionResult(gate, await client.createParty(party));
+        }
+        catch (e) {
+            return errorResult(e.message);
+        }
+    });
+    server.registerTool("create_account", {
+        title: "Create an account and provision its wallet",
+        description: "Create a Finance account. Venly auto-provisions its wallet on the selected chain. Supply partyId or an inline party. Dry-run by default.",
+        inputSchema: {
+            externalId: z.string().min(1),
+            name: z.string().optional(),
+            chain: z.enum(["AVALANCHE", "BASE", "POLYGON"]),
+            address: z.string().optional().describe("Required for SELF_CUSTODY tenants"),
+            partyId: z.string().optional(),
+            party: partySchema.optional(),
+            confirm: confirmField,
+        },
+        annotations: WRITE_ANNOTATIONS,
+    }, async ({ confirm, ...body }) => {
+        if (!body.partyId && !body.party) {
+            return errorResult("create_account requires partyId or an inline party");
+        }
+        if (body.party) {
+            const validationError = partyValidationError(body.party);
+            if (validationError)
+                return errorResult(validationError);
+        }
+        const gate = evaluateWriteGate(confirm, env);
+        if (!gate.armed) {
+            return jsonResult(buildDryRun("create_account", "POST", "finance", "/accounts", body, gate));
+        }
+        try {
+            return executionResult(gate, await client.createAccount(body));
+        }
+        catch (e) {
+            return errorResult(e.message);
+        }
+    });
+    server.registerTool("create_virtual_bank_account", {
+        title: "Create a EUR receiving account",
+        description: "Provision a EUR SEPA virtual bank account and conversion target. Outside mock mode the Finance account must have KYC status VERIFIED. Dry-run by default.",
+        inputSchema: {
+            accountId: z.string(),
+            name: z.string().min(1),
+            inCurrency: z.literal("EUR"),
+            targetCryptocurrency: z.enum(["USDC", "EURC", "USDT", "USDS"]),
+            idempotencyKey: z.string().min(1).optional(),
+            confirm: confirmField,
+        },
+        annotations: WRITE_ANNOTATIONS,
+    }, async ({ accountId, confirm, ...input }) => {
+        const body = {
+            ...input,
+            idempotencyKey: input.idempotencyKey ?? crypto.randomUUID(),
+        };
+        const gate = evaluateWriteGate(confirm, env);
+        if (!gate.armed) {
+            const dryRun = buildDryRun("create_virtual_bank_account", "POST", "finance", `/accounts/${accountId}/virtual-bank-accounts`, body, gate);
+            dryRun.note += " The account must have KYC status VERIFIED before live provisioning.";
+            return jsonResult(dryRun);
+        }
+        try {
+            return executionResult(gate, await client.createVirtualBankAccount(accountId, body));
+        }
+        catch (e) {
+            return errorResult(e.message);
+        }
+    });
+    server.registerTool("create_fiat_transfer", {
+        title: "Create a fiat-denominated internal transfer",
+        description: "Create an account-to-account transfer using the current Finance OpenAPI fields. Dry-run by default outside explicit mock mode.",
+        inputSchema: {
+            senderAccountId: z.string(),
+            receiverAccountId: z
+                .string()
+                .optional()
+                .describe("Receiver's Venly account id. Exactly one of receiverAccountId / receiverExternalId is required."),
+            receiverExternalId: z
+                .string()
+                .optional()
+                .describe("Receiver's integrator-assigned externalId. Exactly one of receiverAccountId / receiverExternalId is required."),
+            currency: z.enum(["EUR", "GBP", "USD"]),
+            amount: z.number(),
+            description: z.string().optional(),
+            merchantReference: z.string().optional(),
+            idempotencyKey: z.string().min(1).optional(),
+            confirm: confirmField,
+        },
+        annotations: WRITE_ANNOTATIONS,
+    }, async ({ senderAccountId, confirm, ...input }) => {
+        if (!input.receiverAccountId === !input.receiverExternalId) {
+            return errorResult("Provide exactly one of receiverAccountId or receiverExternalId - a transfer needs one receiver, addressed one way.");
+        }
+        const body = {
+            ...input,
+            idempotencyKey: input.idempotencyKey ?? crypto.randomUUID(),
+        };
+        const gate = evaluateWriteGate(confirm, env);
+        if (!gate.armed) {
+            return jsonResult(buildDryRun("create_fiat_transfer", "POST", "finance", `/accounts/${senderAccountId}/transfers/fiat`, body, gate));
+        }
+        try {
+            return executionResult(gate, await client.createCurrentFiatTransfer(senderAccountId, body));
+        }
+        catch (e) {
+            return errorResult(e.message);
+        }
+    });
+    server.registerTool("create_crypto_transfer", {
+        title: "Create a crypto-denominated internal transfer",
+        description: "Create an account-to-account asset transfer using the current Finance OpenAPI fields. Dry-run by default outside explicit mock mode.",
+        inputSchema: {
+            senderAccountId: z.string(),
+            receiverAccountId: z
+                .string()
+                .optional()
+                .describe("Receiver's Venly account id. Exactly one of receiverAccountId / receiverExternalId is required."),
+            receiverExternalId: z
+                .string()
+                .optional()
+                .describe("Receiver's integrator-assigned externalId. Exactly one of receiverAccountId / receiverExternalId is required."),
+            chain: z.enum(["AVALANCHE", "BASE", "POLYGON"]),
+            asset: z.string().min(1),
+            amount: z.number(),
+            description: z.string().optional(),
+            merchantReference: z.string().optional(),
+            idempotencyKey: z.string().min(1).optional(),
+            confirm: confirmField,
+        },
+        annotations: WRITE_ANNOTATIONS,
+    }, async ({ senderAccountId, confirm, ...input }) => {
+        if (!input.receiverAccountId === !input.receiverExternalId) {
+            return errorResult("Provide exactly one of receiverAccountId or receiverExternalId - a transfer needs one receiver, addressed one way.");
+        }
+        const body = {
+            ...input,
+            idempotencyKey: input.idempotencyKey ?? crypto.randomUUID(),
+        };
+        const gate = evaluateWriteGate(confirm, env);
+        if (!gate.armed) {
+            return jsonResult(buildDryRun("create_crypto_transfer", "POST", "finance", `/accounts/${senderAccountId}/transfers/crypto`, body, gate));
+        }
+        try {
+            return executionResult(gate, await client.createCryptoTransfer(senderAccountId, body));
+        }
+        catch (e) {
+            return errorResult(e.message);
+        }
+    });
     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.",
+        title: "DEPRECATED - use create_fiat_transfer",
+        description: "DEPRECATED: legacy alias of create_fiat_transfer kept for 0.1.x compatibility; " +
+            "it will be removed in 0.4.0. Prefer create_fiat_transfer, whose inputs match the " +
+            "current OpenAPI contract directly. " +
+            "Stages a fiat-to-crypto transfer (finance POST /accounts/{senderAccountId}/transfers/fiat). " +
+            "Legacy fiatAmount/fiatCurrency inputs are normalized to the current OpenAPI fields; " +
+            "the dry-run shows the exact normalized request. DISARMED by default: returns that " +
+            "request without sending 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\""),
+            fiatAmount: z
+                .string()
+                .refine((value) => value.trim() !== "" && Number.isFinite(Number(value)), "fiatAmount must be a numeric decimal string")
+                .describe("Decimal string, e.g. \"1000.00\""),
             fiatCurrency: z.string().describe("e.g. EUR"),
-            cryptocurrency: z.string().optional(),
+            cryptocurrency: z
+                .string()
+                .optional()
+                .describe("Retired: rejected with guidance. The current contract resolves the fiat " +
+                "amount to the account's settlement asset; use create_crypto_transfer instead."),
             description: z.string().optional(),
             merchantReference: z.string().optional(),
             confirm: confirmField,
@@ -49,20 +262,31 @@ export function registerWriteTools(server, client, env) {
         annotations: WRITE_ANNOTATIONS,
     }, async ({ senderAccountId, confirm, ...rest }) => {
         const gate = evaluateWriteGate(confirm, env);
-        const body = {
+        const legacyInput = {
             receiverAccountId: rest.receiverAccountId,
             fiatAmount: rest.fiatAmount,
             fiatCurrency: rest.fiatCurrency,
             cryptocurrency: rest.cryptocurrency,
             description: rest.description,
             merchantReference: rest.merchantReference,
+            idempotencyKey: crypto.randomUUID(),
         };
+        // Normalize BEFORE the gate branch so the dry-run preview is byte-for-byte
+        // the request a live call would send (and the retired cryptocurrency field
+        // is rejected instead of silently dropped).
+        let body;
+        try {
+            body = normalizeLegacyFiatTransfer(legacyInput);
+        }
+        catch (e) {
+            return errorResult(e.message);
+        }
         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 });
+            const result = await client.createFiatTransfer(senderAccountId, legacyInput);
+            return executionResult(gate, result);
         }
         catch (e) {
             return errorResult(e.message);
@@ -91,7 +315,7 @@ export function registerWriteTools(server, client, env) {
         }
         try {
             const result = await client.approveRampRequest(id, body);
-            return jsonResult({ mode: "live", result });
+            return executionResult(gate, result);
         }
         catch (e) {
             return errorResult(e.message);
@@ -118,7 +342,7 @@ export function registerWriteTools(server, client, env) {
         }
         try {
             const result = await client.rejectRampRequest(id, body);
-            return jsonResult({ mode: "live", result });
+            return executionResult(gate, result);
         }
         catch (e) {
             return errorResult(e.message);
@@ -162,7 +386,7 @@ export function registerWriteTools(server, client, env) {
         }
         try {
             const result = await client.createPayInSession(accountId, body);
-            return jsonResult({ mode: "live", result });
+            return executionResult(gate, result);
         }
         catch (e) {
             return errorResult(e.message);