@venlyfinance/settlement-mcp 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Changelog
 
+## 0.3.0 – 2026-08-04
+
+Wording-is-the-safety-surface release. An outside integrator audit (Report 1,
+2026-08-04) found the server's words disagreeing with its behavior in three
+places; all fixed, plus the SDK under the mock now teaches the documented
+lifecycle (see @venlyfinance/sdk 0.2.0).
+
+### Changed
+
+- **Default environment is `mock`** (was `staging`). A mock-first product must
+  not point at real infrastructure when unconfigured. Set `VENLY_ENV=staging`
+  or `production` explicitly for real calls; the safety resource and README
+  say so.
+- **State-accurate startup banner.** Mock: "writes execute against local
+  fixtures - no network, no credentials, nothing real". Staging/production
+  disarmed: "mutations return dry-run previews". Armed: "confirmed writes hit
+  the live API". No more "DISARMED" next to a write that visibly executes.
+- **Explicit `dryRun: true|false` on every mutation result** - agents no longer
+  infer persistence from `mode`.
+- **`reconcile_by_reference_code` reads real remittance text**: matching is
+  case- and separator-insensitive, transactions match by containment
+  ("invoice ref abc 123 ty" finds REF-ABC-123), and codes under 4 alphanumeric
+  characters are refused.
+- **Receiver XOR enforced**: `create_fiat_transfer` / `create_crypto_transfer`
+  reject a transfer with zero or two receivers (exactly one of
+  `receiverAccountId` / `receiverExternalId`), stated in the tool schema.
+- Requires `@venlyfinance/sdk` ^0.2.0: in mock mode, created parties/accounts
+  start verification-pending (`mock.advanceVerification`), transfers start
+  `PENDING` (`mock.advanceTransfer`), and request bodies are spec-validated.
+
+### Deprecated
+
+- **`stage_transfer`** is now plainly marked deprecated (legacy alias of
+  `create_fiat_transfer`); it will be removed in 0.4.0.
+
 ## 0.2.0 – 2026-08-03
 
 The Settlement MCP becomes the SDK-backed **Venly Finance MCP** builder while retaining
@@ -52,3 +87,16 @@ 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.

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
@@ -190,7 +207,7 @@ Override via env:
 
 | Env var | Default (staging) |
 |---|---|
-| `VENLY_ENV` | `staging` for 0.x compatibility; set `mock` explicitly for fixtures |
+| `VENLY_ENV` | Defaults to `mock` (since 0.3.0): an unconfigured server never points at real infrastructure. Set `staging` or `production` explicitly |
 | `VENLY_FINANCE_BASE_URL` | `https://api-staging.venlyfinance.com/v1` |
 | `VENLY_FUNDFLOW_BASE_URL` | `https://api-fundflow-staging.venly.io` |
 | `VENLY_TOKEN_URL` | `https://login-staging.venly.io/auth/realms/VenlyFinance/protocol/openid-connect/token` (staging; use `login.venly.io` for production) |
@@ -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. Defaults point at STAGING so an accidental run never
- * touches production. Override via env for a real sandbox test. */
+/** 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.2.0";
+export declare const SERVER_VERSION = "0.4.0";
 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,10 +1,13 @@
-/** Shared constants. Defaults point at STAGING so an accidental run never
- * touches production. Override via env for a real sandbox test. */
+/** 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.2.0";
+export const SERVER_VERSION = "0.4.0";
 export const ENVIRONMENT_FLAG = "VENLY_ENV";
 export function resolveVenlyEnvironment(env) {
-    const value = env[ENVIRONMENT_FLAG] ?? "staging";
+    // Default is MOCK (since 0.3.0): the mock-first product must not point at
+    // real infrastructure when unconfigured. Set VENLY_ENV explicitly for
+    // staging or production.
+    const value = env[ENVIRONMENT_FLAG] ?? "mock";
     if (value === "mock" || value === "staging" || value === "production") {
         return value;
     }

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,163 @@
+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: add the registry once to components.json -
+  { "registries": { "@venlyfinance": "${REGISTRY_URL_TEMPLATE}" } }
+then install blocks with the shadcn CLI, e.g. \`npx shadcn@latest add @venlyfinance/receive\`.
+Each block auto-installs its components, the venly-tokens file and the
+@venlyfinance/react data layer. Import 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/index.js

@@ -17,8 +17,15 @@ async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
     // Log to stderr only (stdout is the MCP channel). No credentials here.
+    // The banner states what writes actually do in THIS environment - wording is
+    // the agent's safety surface, so it must match observed behavior exactly.
     const armed = process.env[LIVE_FLAG] === "1";
-    process.stderr.write(`venly-finance-mcp started in ${client.environment}. write tools ${armed ? "ARMED (VENLY_MCP_LIVE=1)" : "DISARMED (read-only default)"}.\n`);
+    const writeState = client.environment === "mock"
+        ? "writes execute against local fixtures - no network, no credentials, nothing real"
+        : armed
+            ? "writes ARMED (VENLY_MCP_LIVE=1): confirmed writes hit the live API"
+            : "writes DISARMED: mutations return dry-run previews (arming needs confirm:true + VENLY_MCP_LIVE=1 + credentials)";
+    process.stderr.write(`venly-finance-mcp started in ${client.environment}. ${writeState}.\n`);
 }
 main().catch((err) => {
     process.stderr.write(`Fatal: ${err.message}\n`);

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/reconcile.d.ts

@@ -20,4 +20,11 @@ export interface ReconcileResult {
     currency: string | null;
     note: string;
 }
+/**
+ * Normalize a payment reference the way bank remittance text must be read:
+ * uppercase, alphanumerics only. Payer banks freely re-case, strip or pad
+ * separators, so "ref-abc-123", "REF ABC 123" and "invoice REFABC123 thanks"
+ * must all find REF-ABC-123.
+ */
+export declare function normalizeReference(text: string): string;
 export declare function reconcileByReferenceCode(referenceCode: string, virtualBankAccounts: VirtualBankAccount[], transactions: ObservedBankTransaction[]): ReconcileResult;

package/dist/reconcile.js

@@ -6,16 +6,34 @@
  * vIBANs via the VenlyClient and passes them in alongside the operator- or
  * bank-feed-supplied transactions.
  */
+/**
+ * Normalize a payment reference the way bank remittance text must be read:
+ * uppercase, alphanumerics only. Payer banks freely re-case, strip or pad
+ * separators, so "ref-abc-123", "REF ABC 123" and "invoice REFABC123 thanks"
+ * must all find REF-ABC-123.
+ */
+export function normalizeReference(text) {
+    return text.toUpperCase().replace(/[^A-Z0-9]/g, "");
+}
 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;
+    const normalizedTarget = normalizeReference(target);
+    if (normalizedTarget.length < 4) {
+        throw new Error(`referenceCode "${target}" is too short after normalization ` +
+            `("${normalizedTarget}"): at least 4 alphanumeric characters are required ` +
+            "to match safely against free-form remittance text.");
+    }
+    // The vIBAN side is Venly-issued, so it matches exactly (after normalization).
+    const vban = virtualBankAccounts.find((v) => normalizeReference(v.referenceCode ?? "") === normalizedTarget) ?? null;
     if (vban && !(vban.id ?? "").trim()) {
         throw new Error("matching vIBAN is missing an id");
     }
-    const matchedTransactions = transactions.filter((t) => (t.referenceCode ?? "").trim() === target);
+    // The transaction side is free-form remittance text typed by a payer, so a
+    // containment test on the normalized text is the honest match.
+    const matchedTransactions = transactions.filter((t) => normalizeReference(t.referenceCode ?? "").includes(normalizedTarget));
     const totalAmount = matchedTransactions.reduce((sum, t) => sum + (Number.isFinite(t.amount) ? t.amount : 0), 0);
     const currency = vban?.currency ?? matchedTransactions[0]?.currency ?? null;
     const matched = vban !== null && matchedTransactions.length > 0;

package/dist/resources.js

@@ -33,7 +33,7 @@ Current boundaries:
         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.
+- Set VENLY_ENV explicitly to mock, staging or production. An absent value defaults to mock (since 0.3.0), so an unconfigured server never points at real infrastructure.
 - 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.

package/dist/safety.d.ts

@@ -26,6 +26,8 @@ export declare function credentialsPresent(env: EnvLike): boolean;
 export declare function evaluateWriteGate(confirm: boolean, env: EnvLike): GateDecision;
 export interface DryRunRequest {
     mode: "dry-run";
+    /** Explicit on every mutation result: nothing was persisted. */
+    dryRun: true;
     environment: VenlyEnvironment;
     tool: string;
     method: "GET" | "POST" | "PUT" | "DELETE";

package/dist/safety.js

@@ -55,6 +55,7 @@ export function evaluateWriteGate(confirm, env) {
 export function buildDryRun(tool, method, api, path, body, gate) {
     return {
         mode: "dry-run",
+        dryRun: true,
         environment: gate.environment,
         tool,
         method,

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/read-tools.js

@@ -144,14 +144,20 @@ export function registerReadTools(server, client) {
         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(),

package/dist/tools/write-tools.js

@@ -9,10 +9,12 @@
 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",
+        // 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,
     });
@@ -154,8 +156,14 @@ export function registerWriteTools(server, client, env) {
         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(),
-            receiverExternalId: z.string().optional(),
+            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(),
@@ -165,8 +173,8 @@ export function registerWriteTools(server, client, env) {
         },
         annotations: WRITE_ANNOTATIONS,
     }, async ({ senderAccountId, confirm, ...input }) => {
-        if (!input.receiverAccountId && !input.receiverExternalId) {
-            return errorResult("A receiverAccountId or receiverExternalId is required");
+        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,
@@ -188,8 +196,14 @@ export function registerWriteTools(server, client, env) {
         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(),
-            receiverExternalId: z.string().optional(),
+            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(),
@@ -200,8 +214,8 @@ export function registerWriteTools(server, client, env) {
         },
         annotations: WRITE_ANNOTATIONS,
     }, async ({ senderAccountId, confirm, ...input }) => {
-        if (!input.receiverAccountId && !input.receiverExternalId) {
-            return errorResult("A receiverAccountId or receiverExternalId is required");
+        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,
@@ -218,62 +232,6 @@ export function registerWriteTools(server, client, env) {
             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). " +
-            "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.2.0",
+  "version": "0.4.0",
   "description": "Venly Finance MCP: SDK-backed tools, resources and prompts for building international money products safely.",
   "type": "module",
   "bin": {
@@ -27,7 +27,7 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@venlyfinance/sdk": "^0.1.1",
+    "@venlyfinance/sdk": "^0.2.0",
     "@modelcontextprotocol/sdk": "^1.30.0",
     "zod": "^3.23.8"
   },

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).