@venlyfinance/settlement-mcp 0.2.0 → 0.3.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

package/README.md

@@ -190,7 +190,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) |

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.3.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.3.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/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/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/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

@@ -13,6 +13,9 @@ 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 +157,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 +174,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 +197,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 +215,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,
@@ -219,8 +234,11 @@ export function registerWriteTools(server, client, env) {
         }
     });
     server.registerTool("stage_transfer", {
-        title: "Stage a fiat transfer (dry-run by default)",
-        description: "Stage a fiat-to-crypto transfer (finance POST /accounts/{senderAccountId}/transfers/fiat). " +
+        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.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@venlyfinance/settlement-mcp",
-  "version": "0.2.0",
+  "version": "0.3.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"
   },