@venlyfinance/settlement-mcp 0.3.0 → 0.4.1

package/CHANGELOG.md

@@ -87,3 +87,20 @@ its package name and compatibility binary throughout the 0.x line.
 ### Security
 
 - Runtime dependency audits report zero findings after the MCP SDK/Hono upgrade.
+
+## 0.4.0 – 2026-08-07
+
+Frontend toolset: the judgment layer for interface assembly.
+
+- `get_journey_blueprint` – screen inventory, required states, registry items and binding hooks for eight money-product journeys.
+- `review_screen` – deterministic design audit (raw colours, hyphen-minus amounts, success styling on cancelled steps, masked review values, zebra striping, off-token shadows, gradients, colour-only state). Findings, not a score.
+- `venly://frontend/agents` resource – composition rules plus the @venlyfinance shadcn-registry wiring (delivery of UI source rides the registry standard; these tools carry what a registry cannot).
+- `build_international_account` prompt now assembles the interface from the registry and gates every screen on `review_screen`.
+
+### Removed
+
+- **`stage_transfer`**, as promised in 0.3.0's deprecation: use `create_fiat_transfer`, whose inputs match the OpenAPI contract directly. The skills pack is updated accordingly.
+
+## 0.4.1 – 2026-08-07
+
+- `venly://frontend/agents` now carries the full cold-start recipe, learned from a fresh-agent build run: Tailwind + path-alias prerequisites before `shadcn init`, the non-interactive `-y -b radix -p nova` flags, that blocks land under `components/venly/` at the project root (relative imports, not the `@/` alias), that `shadcn add` auto-installs the npm dependencies, and the `.js`-extension bundler note.

package/README.md

@@ -92,7 +92,7 @@ Builder writes: `create_party`, `create_account`,
 `create_crypto_transfer`, `create_payment_session`.
 
 Operator writes: `approve_ramp_request`, `reject_ramp_request`. The legacy
-`stage_transfer` name remains as a compatibility tool; new builds use
+`stage_transfer` alias was removed in 0.4.0 as deprecated in 0.3.0; use
 `create_fiat_transfer` and its current OpenAPI field names.
 
 Each is dry-run by default and returns the exact request it would send. See the
@@ -106,6 +106,23 @@ It documents the machine-to-machine rail. It never executes a payment, never
 calls a facilitator, and never moves funds. Production x402 settlement needs a
 facilitator decision and live rails.
 
+## Frontend toolset (interface assembly)
+
+Delivery of UI source rides the shadcn registry standard – add
+`{ "registries": { "@venlyfinance": "https://raw.githubusercontent.com/Venly/venly-settlement-sdk/main/ui/r/{name}.json" } }`
+to `components.json`, then `npx shadcn@latest add @venlyfinance/receive`. The MCP carries
+what a registry cannot:
+
+- `get_journey_blueprint` – screen inventory, required states, registry items and binding
+  hooks for eight money-product journeys.
+- `review_screen` – deterministic design audit of a screen's source (raw colours,
+  hyphen-minus amounts, success styling on cancelled steps, masked review values, zebra
+  striping, off-token shadows, colour-only state). Findings, not a score.
+- `venly://frontend/agents` – the composition rules an agent should read before building.
+
+The `build_international_account` prompt assembles the interface from the registry and
+gates every finished screen on `review_screen`. See [`ui/`](../ui/README.md) for the kit itself.
+
 ## Safety model (fail closed)
 
 Outside explicit mock mode, read-only/dry-run is the default posture. A staging
@@ -211,8 +228,8 @@ reads, and fail-closed write gate without mutating staging:
 VENLY_CLIENT_ID=... VENLY_CLIENT_SECRET=... npm run smoke:staging
 ```
 
-The command starts the MCP with `VENLY_ENV=staging`, lists the expected 23 tools,
-four resources, and builder prompt, then reads parties, accounts, and reference data.
+The command starts the MCP with `VENLY_ENV=staging`, lists the expected 24 tools,
+five resources, and builder prompt, then reads parties, accounts, and reference data.
 It deliberately removes `VENLY_MCP_LIVE` and `VENLY_MCP_PRODUCTION` from the child
 process before submitting one confirmed `create_party` request. Passing requires that
 request to return `mode: dry-run`, `environment: staging`, and an unarmed gate. Output

package/dist/constants.d.ts

@@ -1,7 +1,7 @@
 /** Shared constants. The default environment is MOCK so an unconfigured run
  * never touches real infrastructure; staging/production are explicit. */
 export declare const SERVER_NAME = "venly-finance-mcp-server";
-export declare const SERVER_VERSION = "0.3.0";
+export declare const SERVER_VERSION = "0.4.1";
 export declare const ENVIRONMENT_FLAG = "VENLY_ENV";
 export type VenlyEnvironment = "mock" | "staging" | "production";
 export declare function resolveVenlyEnvironment(env: Record<string, string | undefined>): VenlyEnvironment;

package/dist/constants.js

@@ -1,7 +1,7 @@
 /** Shared constants. The default environment is MOCK so an unconfigured run
  * never touches real infrastructure; staging/production are explicit. */
 export const SERVER_NAME = "venly-finance-mcp-server";
-export const SERVER_VERSION = "0.3.0";
+export const SERVER_VERSION = "0.4.1";
 export const ENVIRONMENT_FLAG = "VENLY_ENV";
 export function resolveVenlyEnvironment(env) {
     // Default is MOCK (since 0.3.0): the mock-first product must not point at

package/dist/frontend.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Frontend toolset: what no generic registry can provide.
+ *
+ * Delivery of UI source belongs to the shadcn registry standard (the
+ * @venlyfinance registry under ui/r/ in this repo); these tools carry the
+ * judgment layer instead – journey blueprints (what screens and states a
+ * money product needs) and a deterministic design audit that pushes back
+ * on the classic agent-built-dashboard failure modes.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare const REGISTRY_URL_TEMPLATE = "https://raw.githubusercontent.com/Venly/venly-settlement-sdk/main/ui/r/{name}.json";
+interface Finding {
+    rule: string;
+    severity: "error" | "warn";
+    evidence: string;
+    fix: string;
+}
+/** Deterministic design audit. Text in, findings out - no model, no taste. */
+export declare function reviewScreenSource(source: string): Finding[];
+export declare function registerFrontendTools(server: McpServer): void;
+export {};

package/dist/frontend.js

@@ -0,0 +1,179 @@
+import { z } from "zod";
+export const REGISTRY_URL_TEMPLATE = "https://raw.githubusercontent.com/Venly/venly-settlement-sdk/main/ui/r/{name}.json";
+const JOURNEYS = {
+    "home-balances": `# Home / balances
+Shell: left nav rail + thin top bar; full-width content.
+Registry items: venly-tokens, balance-card, data-table, status-pill.
+Hooks: useAccounts, useVirtualBankAccounts; balances rendered per account/currency.
+States that must exist: loading, zero accounts (first-run guidance), balances with reserved buckets.
+Rules that must hold: available is the emphasised figure and the only one above the rule; reserved is demoted by position and scale, never colour; unspendable buckets carry the padlock; never assume stablecoin parity - render the quoted rate.`,
+    receive: `# Receive
+Shell: content column - a warning callout, the field card, an advisory below.
+Registry items: venly-tokens, field-list; block: receive.
+Hooks: useVirtualBankAccounts (first active EUR account).
+States that must exist: no virtual bank account yet (offer creation), details present, reference not yet assigned ("Not assigned yet" + Required pill - never "(not required)").
+Rules that must hold: the payment reference is enforced as mandatory (amber Required pill, warning above the fields); per-field copy names the field it copied and only confirms on a successful write; rows never vanish - render the "(not required)" variant.`,
+    send: `# Send
+Shell: full page; form clamped ~600px; review step replaces the form.
+Registry items: venly-tokens, arithmetic-ladder, timeline; block: send.
+Hooks: useStagedTransfer (the machine IS the flow), useFeeQuote when fees apply.
+States that must exist: draft (validation issues listed), staged review, submitting, pending (polling), completed, failed (reason shown, terminal).
+Rules that must hold: money movement is stage-then-confirm - the review renders the exact staged request as an arithmetic ladder (working before the answer, uncertainty attached to the number); the commit button restates the amount and never carries a countdown; values are never masked on review; execution is single-shot on an idempotency key pinned at staging.`,
+    activity: `# Activity
+Shell: full-width table + side panel.
+Registry items: venly-tokens, data-table, status-pill, side-panel, timeline; block: activity.
+Hooks: useTransfers (and useRampRequests where ramps are in scope).
+States that must exist: loading, empty ledger, rows with pending/failed pills, open detail panel that stays in sync with refetches.
+Rules that must hold: a row click opens the panel, never navigates; no scrim - the source row stays tinted; settled rows stay quiet (colour is a budget; pills only where action or failure lives); the panel's hero is the amount; the failure reason rides the terminal timeline node.`,
+    "onboarding-status": `# Onboarding / verification status
+Shell: full page, form clamped ~600px; a status home once submitted.
+Registry items: venly-tokens, timeline, status-pill, field-list.
+Hooks: useParties, useCreateParty; verification status from the party/account records.
+States that must exist: collecting (per-section progress), submitted/waiting (say who acts next, on which channel, what still works meanwhile), approved, declined (humane copy + what to do next), re-verification on a live account.
+Rules that must hold: never render a fake progress percentage - use real per-item status; a waiting state answers how long / who acts / what still works; a decline explains and offers a next step, not a dead end; creating a party is NOT completed verification - show the honest state.`,
+    reconciliation: `# Reconciliation
+Shell: split pane (roughly one-third list, two-thirds evidence) - not a drawer.
+Registry items: venly-tokens, data-table, side-panel, status-pill, field-list.
+Hooks: reconcile_by_reference_code (MCP composite) or useVirtualBankAccounts + useTransfers joined on referenceCode.
+States that must exist: matched, unmatched with candidate expectations, partial/many-to-one with a live shortfall figure, resolved.
+Rules that must hold: show per-signal match rationale (which fields agree), never a bare score; keep zero-counts visible - an empty exception queue is information; keyboard row-stepping for review throughput.`,
+    "proof-of-segregation": `# Proof of segregation
+Shell: content column, single card.
+Registry items: venly-tokens, field-list, balance-card.
+Hooks: useWallets, useAccount; on-chain balance beside the ledger figure.
+States that must exist: reconciled (figures agree, timestamped), reconciling, source unavailable (say so - never render a stale figure as current).
+Rules that must hold: the wallet address renders monospace with copy; the on-chain figure and ledger figure sit side by side with their as-of times; discrepancies are stated, not smoothed.`,
+    approvals: `# Approvals
+Shell: full-width queue + side panel tailored to the approver.
+Registry items: venly-tokens, data-table, status-pill, side-panel, timeline.
+Hooks: useRampRequests, useFourEyesApproval (capability decides what renders), useRampLifecycle.
+States that must exist: queue with awaiting-approval items, detail with the decision context beside the figures, applied, stale-version (someone acted first - refetch and re-decide), creator-view (cannot approve own request - render the rule, not a disabled mystery button).
+Rules that must hold: the optimistic-locking version travels with every decision; a 409 means re-decide against fresh state, never auto-retry; reject requires a reason; the creator sees why they cannot approve.`,
+};
+const JOURNEY_KEYS = Object.keys(JOURNEYS);
+/** Deterministic design audit. Text in, findings out - no model, no taste. */
+export function reviewScreenSource(source) {
+    const findings = [];
+    const push = (rule, severity, evidence, fix) => findings.push({ rule, severity, evidence: evidence.slice(0, 120), fix });
+    for (const match of source.matchAll(/#[0-9a-fA-F]{3,8}\b|rgba?\([^)]*\)/g)) {
+        push("raw-colour", "error", match[0], "Read colours from the venly-tokens custom properties; a reskin must be tokens.css and nothing else.");
+    }
+    for (const match of source.matchAll(/-\d[\d,]*\.\d{2}\s*(?:[A-Z]{3}|€|\$|£)/g)) {
+        push("hyphen-minus-amount", "error", match[0], "Use the true minus sign − before negative amounts (the Money primitive does this).");
+    }
+    // Only a RENDERED cancelled state counts (a quoted/JSX label or a state
+    // value), never the verb "cancel" in prose or a token file's comment; and
+    // only the ✓ glyph counts as the violation, never the mere NAME of a
+    // success token nearby.
+    for (const match of source.matchAll(/(?:["'>`]|\bstate\s*[:=]\s*["'])\s*cancell?ed\b/gi)) {
+        const idx = match.index ?? 0;
+        const around = source.slice(Math.max(0, idx - 150), idx + 150);
+        if (/✓/.test(around)) {
+            push("success-on-cancelled", "error", around.trim().slice(0, 80), "A cancelled or failed terminal step must never carry a success check - grey ↺ or red ✕.");
+            break;
+        }
+    }
+    if (/review|confirm/i.test(source) && /[•*]{3,}/.test(source)) {
+        push("masked-review-value", "error", source.match(/[•*]{3,}/)[0], "Never mask values on a review screen; its only job is legibility of what is about to happen.");
+    }
+    if (/nth-child\(\s*(?:even|odd|2n)/.test(source)) {
+        push("zebra-striping", "warn", "nth-child(even/odd) background", "No finance reference uses zebra striping - separate rows with hairlines and spacing.");
+    }
+    if (/box-shadow/.test(source) && !/var\(--shadow-overlay\)/.test(source)) {
+        push("shadow-outside-overlay", "warn", source.match(/box-shadow[^;"}]*/)?.[0] ?? "box-shadow", "Elevation is only for overlays, and only via the --shadow-overlay token; the base layer is flat.");
+    }
+    if (/linear-gradient|radial-gradient/.test(source)) {
+        push("gradient-surface", "warn", source.match(/\w+-gradient\([^)]*\)/)?.[0] ?? "gradient", "Gradient balance heroes read as template, not product; surfaces are flat neutrals with one accent.");
+    }
+    if (/(?:status|state)/i.test(source) && /var\(--state-/.test(source)) {
+        if (!/[✓✕↺⚠●○]|aria-hidden/.test(source)) {
+            push("colour-only-state", "warn", "state colours present without any glyph", "Pair every state hue with a glyph or word so status survives greyscale.");
+        }
+    }
+    return findings;
+}
+const AGENTS_TEXT = `# Composition rules for coding agents building on the Venly UI registry
+
+Delivery: the shadcn CLI expects a working shadcn environment BEFORE any
+registry install. On a fresh Vite/React app that means, in order:
+1. Install Tailwind (\`npm i tailwindcss @tailwindcss/vite\`) and wire the
+   \`@/\` path alias in tsconfig + vite config - \`shadcn init\` refuses to
+   run without both.
+2. \`npx shadcn@latest init -y -b radix -p nova\` (the -b/-p flags keep it
+   non-interactive; the kit is plain React + Radix-compatible, so any base
+   works - it never imports base-library components itself).
+3. Add the registry once to components.json -
+  { "registries": { "@venlyfinance": "${REGISTRY_URL_TEMPLATE}" } }
+4. \`npx shadcn@latest add @venlyfinance/receive @venlyfinance/send @venlyfinance/activity -y -o\`.
+   Each block auto-installs its components, the venly-tokens file AND its
+   npm dependencies (@venlyfinance/react, @venlyfinance/sdk, TanStack
+   Query) - no separate npm install step is needed.
+
+Install layout: files land under \`components/venly/\` at the PROJECT ROOT
+(not src/), preserving their relative imports - import them with a relative
+path (e.g. \`../components/venly/blocks/receive.js\`), not the \`@/\` alias.
+The sources use TypeScript-style \`.js\` extensions on .tsx imports: fine
+under Vite/esbuild/Next; webpack needs \`extensionAlias\`. Import the
+installed venly-tokens css once at the app root.
+
+1. Never hand-roll API calls, auth, retries, or transfer state - every read
+   is a hook, every regulated lifecycle is a flow machine from
+   @venlyfinance/react. Wrap the tree once in <VenlyProvider environment="mock">.
+2. Mock mode is the default for any demo or first build: zero credentials,
+   zero network. Never place a clientSecret in browser code - the provider
+   throws; use proxyClientOptions() against your own backend for production.
+3. Money movement is stage-then-confirm: render the review, restate the
+   amount on the commit button, execute once.
+4. Approval UIs render the rule, not the error: use the capability object;
+   on "stale-version" refetch and let the operator re-decide.
+5. Theme by editing the installed venly-tokens css file and nothing else.
+6. Before declaring a screen done, run the review_screen tool on its source
+   and fix every error-severity finding. Consult get_journey_blueprint
+   before designing a screen the registry has no block for.
+`;
+export function registerFrontendTools(server) {
+    server.registerTool("get_journey_blueprint", {
+        title: "Get a journey blueprint",
+        description: "Screen inventory, required states, registry items and binding hooks for one money-product journey. Consult before designing any screen.",
+        inputSchema: {
+            journey: z.enum(JOURNEY_KEYS).describe("Which journey to blueprint"),
+        },
+    }, async ({ journey }) => ({
+        content: [{ type: "text", text: JOURNEYS[journey] }],
+    }));
+    server.registerTool("review_screen", {
+        title: "Design-audit a screen",
+        description: "Deterministic audit of component/markup source against the kit's design contract: raw colours, hyphen-minus amounts, success styling on cancelled steps, masked review values, zebra striping, off-token shadows, gradients, colour-only state. Returns findings, not a score.",
+        inputSchema: {
+            source: z.string().min(1).describe("The component/markup/CSS source to audit"),
+        },
+    }, async ({ source }) => {
+        const findings = reviewScreenSource(source);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        findings,
+                        summary: findings.length === 0
+                            ? "No contract violations detected."
+                            : `${findings.filter((f) => f.severity === "error").length} error(s), ${findings.filter((f) => f.severity === "warn").length} warning(s). Fix every error before declaring the screen done.`,
+                    }, null, 2),
+                },
+            ],
+        };
+    });
+    server.registerResource("frontend-agents", "venly://frontend/agents", {
+        title: "UI composition rules for coding agents",
+        description: "How to assemble a money-product frontend from the @venlyfinance registry and react package.",
+        mimeType: "text/markdown",
+    }, async () => ({
+        contents: [
+            {
+                uri: "venly://frontend/agents",
+                mimeType: "text/markdown",
+                text: AGENTS_TEXT,
+            },
+        ],
+    }));
+}

package/dist/prompts.js

@@ -24,16 +24,17 @@ export function registerBuilderPrompts(server) {
 
 Use this operating brief:
 
-1. Read venly://capabilities, venly://safety and venly://workflows/international-account before writing code.
+1. Read venly://capabilities, venly://safety, venly://workflows/international-account and venly://frontend/agents 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.
+4. Assemble the interface instead of inventing it: register the @venlyfinance registry in components.json (URL template in venly://frontend/agents), install the receive/send/activity blocks with the shadcn CLI, wrap the tree in <VenlyProvider environment="mock"> from @venlyfinance/react, and import the installed venly-tokens css once at the app root. Consult get_journey_blueprint before designing any screen the registry has no block for, and run every finished screen through review_screen, fixing all error-severity findings.
+5. Build the customer experience around atomic Finance capabilities: party, account, auto-provisioned wallet and balances, EUR receiving account, transfer and status/reconciliation.
+6. Do not claim that creating a party completes KYC/KYB. Display verification and pending states honestly.
+7. Venly supplies financial infrastructure through regulated partners. Do not describe the application or its customer as a licensed bank unless separately verified.
+8. EUR/SEPA virtual bank accounts are documented. Validate ${targetGeography ?? "the requested geography"} and any broader currency/coverage requirement instead of inferring support.
+9. Card issuing is not exposed by the current Finance contract; do not invent a card feature.
+10. Require an explicit user decision before switching to staging, adding credentials or arming writes. Dry-run staging mutations before confirmation.
+11. 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/server.js

@@ -10,6 +10,7 @@ import { registerWriteTools } from "./tools/write-tools.js";
 import { registerX402Tools } from "./tools/x402-tools.js";
 import { registerBuilderResources } from "./resources.js";
 import { registerBuilderPrompts } from "./prompts.js";
+import { registerFrontendTools } from "./frontend.js";
 export function createServer(options) {
     const env = options.env ?? process.env;
     // The write gate auto-arms every mutation in mock mode on the assumption
@@ -29,6 +30,7 @@ export function createServer(options) {
     registerReadTools(server, options.client);
     registerWriteTools(server, options.client, env);
     registerX402Tools(server);
+    registerFrontendTools(server);
     registerBuilderResources(server);
     registerBuilderPrompts(server);
     return server;

package/dist/staging-smoke.d.ts

@@ -1,5 +1,5 @@
-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_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", "approve_ramp_request", "reject_ramp_request", "create_payment_session", "quote_x402_payment", "get_journey_blueprint", "review_screen"];
+export declare const EXPECTED_RESOURCE_URIS: readonly ["venly://capabilities", "venly://safety", "venly://workflows/international-account", "venly://workflows/mock-to-staging", "venly://frontend/agents"];
 export declare const EXPECTED_PROMPTS: readonly ["build_international_account"];
 export interface DiscoveryNames {
     tools: string[];

package/dist/staging-smoke.js

@@ -22,17 +22,19 @@ export const EXPECTED_TOOLS = [
     "create_virtual_bank_account",
     "create_fiat_transfer",
     "create_crypto_transfer",
-    "stage_transfer",
     "approve_ramp_request",
     "reject_ramp_request",
     "create_payment_session",
     "quote_x402_payment",
+    "get_journey_blueprint",
+    "review_screen",
 ];
 export const EXPECTED_RESOURCE_URIS = [
     "venly://capabilities",
     "venly://safety",
     "venly://workflows/international-account",
     "venly://workflows/mock-to-staging",
+    "venly://frontend/agents",
 ];
 export const EXPECTED_PROMPTS = ["build_international_account"];
 function assertExactMembers(label, expected, actual) {

package/dist/tools/write-tools.js

@@ -9,7 +9,6 @@
 import { z } from "zod";
 import { buildDryRun, evaluateWriteGate } from "../safety.js";
 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",
@@ -233,65 +232,6 @@ export function registerWriteTools(server, client, env) {
             return errorResult(e.message);
         }
     });
-    server.registerTool("stage_transfer", {
-        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()
-                .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()
-                .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,
-        },
-        annotations: WRITE_ANNOTATIONS,
-    }, async ({ senderAccountId, confirm, ...rest }) => {
-        const gate = evaluateWriteGate(confirm, env);
-        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, legacyInput);
-            return executionResult(gate, 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). " +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@venlyfinance/settlement-mcp",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "Venly Finance MCP: SDK-backed tools, resources and prompts for building international money products safely.",
   "type": "module",
   "bin": {

package/skills/stage-and-confirm-transfer.md

@@ -11,13 +11,13 @@ fiat to crypto.
 ## Tools
 
 - `get_account` (read)
-- `stage_transfer` (write, disarmed by default)
+- `create_fiat_transfer` (write, disarmed by default)
 - `get_transfer` (read)
 
 ## Steps
 
 1. `get_account` for the `senderAccountId` to confirm it is active.
-2. Stage the transfer: call `stage_transfer` with `senderAccountId`,
+2. Stage the transfer: call `create_fiat_transfer` with `senderAccountId`,
    `receiverAccountId`, `fiatAmount` (decimal string), `fiatCurrency`, and
    optionally `cryptocurrency`, `description`, `merchantReference`. Omit
    `confirm` (or set it false).