@venlyfinance/settlement-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2026 Venly NV
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OF THE SOFTWARE.

package/README.md

@@ -0,0 +1,226 @@
+# Venly Settlement MCP server
+
+A human-gated operator surface for Venly settlement, exposed as a Model Context
+Protocol (MCP) server over stdio. An operator, or a supervised agent, can check a
+ramp's four-eyes approval state, reconcile a EUR vIBAN by referenceCode, or stage
+a transfer, without hand-writing API calls. It pairs that with a position on
+x402, the machine-to-machine agent-payments rail.
+
+The differentiator: the MCP is the human-gated operator surface; x402 is the
+machine-to-machine rail. Read-only by default, write tools fail closed.
+
+Status: v0.1.0. Read tools work against staging out of the box once credentials
+are set; write tools are shipped disarmed and fail closed (see the safety model).
+The x402 tool is a stub that states a position, it moves no funds.
+
+## What it is
+
+- Built on the official MCP TypeScript SDK (`@modelcontextprotocol/sdk`), Node
+  >= 18, stdio transport.
+- A thin layer over the Venly Finance API (`finance.yaml`, servers
+  `https://api.venlyfinance.com/api/v1`) and the Fundflow API (`fundflow.yaml`,
+  servers `https://api-fundflow.venly.io`). Endpoint truth is the published API
+  reference at [docs.venlyfinance.com](https://docs.venlyfinance.com/api-reference).
+- Transport is injected through the `VenlyClient` interface (`src/types.ts`).
+  `HttpVenlyClient` is a minimal fetch-based implementation; tests inject a mock.
+
+### Transport note
+
+The built-in HTTP transport is minimal by design (OAuth2 client credentials,
+lazy token fetch, no logging of secrets) and is fully covered by the test
+suite. A future release adopts [`@venlyfinance/sdk`](../) as the transport
+layer, with no change to the tool interface.
+
+## The three tool tiers
+
+### 1. Read tools (always on)
+
+Call GETs only. No mutation, safe by default.
+
+| Tool | Maps to |
+|---|---|
+| `list_ramp_requests` | fundflow `GET /v1/ramp-requests` |
+| `get_ramp_request` | fundflow `GET /v1/ramp-requests/{id}` |
+| `get_account` | finance `GET /accounts/{accountId}` |
+| `list_virtual_bank_accounts` | finance `GET /accounts/{accountId}/virtual-bank-accounts` |
+| `reconcile_by_reference_code` | composite: lists vIBANs, matches supplied transactions by referenceCode |
+| `get_transfer` | finance `GET /accounts/{accountId}/transfers/{transferId}` |
+| `list_parties` | finance `GET /parties` |
+| `get_reference_data` | fundflow chains / fiat-currencies / crypto-currencies / fees |
+
+`reconcile_by_reference_code` is the EUR vIBAN reconciliation: a customer sends
+EUR to a vIBAN including a reference code in the payment; this tool fetches the
+account's vIBANs and matches the observed incoming bank transactions (operator-
+or feed-supplied) to the vIBAN carrying that referenceCode. It returns the
+matched vIBAN, the matched transactions, and the total amount.
+
+### 2. Write tools (present, DISARMED by default)
+
+`stage_transfer`, `approve_ramp_request`, `reject_ramp_request`,
+`create_payment_link`.
+
+Each is dry-run by default and returns the exact request it would send. See the
+safety model below.
+
+### 3. x402 tool (position + stub)
+
+`quote_x402_payment` returns an HTTP-402-shaped quote (price, asset, payTo,
+chain) for a settlement action, following the x402 `PaymentRequirements` model.
+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.
+
+## Safety model (fail closed)
+
+Read-only is the default posture. A write tool executes a live call ONLY when
+ALL THREE hold:
+
+1. the tool argument `confirm === true`, and
+2. the environment flag `VENLY_MCP_LIVE === "1"`, and
+3. credentials are present (`VENLY_CLIENT_ID` and `VENLY_CLIENT_SECRET`).
+
+If any leg is missing, the tool returns a dry-run object describing the request
+it would have sent and never touches the transport. This is proven by
+`test/write-tools.test.ts`, including the critical case: `confirm:true` with
+`VENLY_MCP_LIVE` unset still dry-runs and does not call the live client.
+
+Other invariants:
+
+- Credentials are read from env, never logged, never returned in tool output.
+- No tool broadens an allowlist, changes credentials, or deletes production data.
+- Four-eyes approval semantics are preserved. The Fundflow API enforces that an
+  identity cannot approve a request it created; this server surfaces that state,
+  it does not bypass it. `approve_ramp_request` / `reject_ramp_request` carry the
+  optimistic-locking `version` (read it from `get_ramp_request`).
+
+## Install, build, test
+
+```bash
+npm install
+npm run build     # tsc -> dist/, entry dist/index.js
+npm test          # node:test via tsx, mocked client, no network
+```
+
+## Run
+
+The fastest path once published to npm - one line in any MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "venly-settlement": {
+      "command": "npx",
+      "args": ["-y", "@venlyfinance/settlement-mcp"]
+    }
+  }
+}
+```
+
+Or from a clone:
+
+```bash
+node dist/index.js
+```
+
+The server speaks MCP over stdio. On start it logs to stderr whether writes are
+armed or disarmed (stdout is the MCP channel, no credentials are logged).
+
+MCP client config example:
+
+```json
+{
+  "mcpServers": {
+    "venly-settlement": {
+      "command": "node",
+      "args": ["/absolute/path/to/settlement-mcp/dist/index.js"],
+      "env": {
+        "VENLY_FINANCE_BASE_URL": "https://api-staging.venlyfinance.com/api/v1",
+        "VENLY_FUNDFLOW_BASE_URL": "https://api-fundflow-staging.venly.io"
+      }
+    }
+  }
+}
+```
+
+## Point it at sandbox
+
+Defaults already point at STAGING so an accidental run never touches production.
+Override via env:
+
+| Env var | Default (staging) |
+|---|---|
+| `VENLY_FINANCE_BASE_URL` | `https://api-staging.venlyfinance.com/api/v1` |
+| `VENLY_FUNDFLOW_BASE_URL` | `https://api-fundflow-staging.venly.io` |
+| `VENLY_TOKEN_URL` | `https://login.venly.io/auth/realms/VenlyFinance/protocol/openid-connect/token` |
+| `VENLY_CLIENT_ID` | unset (read-only until set) |
+| `VENLY_CLIENT_SECRET` | unset |
+| `VENLY_MCP_LIVE` | unset (writes disarmed) |
+
+Fundflow also exposes a QA sandbox (`https://api-fundflow-qa.venly.io`). If your
+tenant uses different endpoints, override them via the env vars above.
+
+## Enabling live writes (a deliberate operator decision)
+
+Live writes are OFF. To arm them, the operator must:
+
+1. set `VENLY_MCP_LIVE=1`, and
+2. provide sandbox credentials `VENLY_CLIENT_ID` and `VENLY_CLIENT_SECRET`, and
+3. pass `confirm: true` on the specific write tool call.
+
+Until all three are set, every write tool dry-runs. Arming the flag and
+provisioning credentials is a deliberate, human decision, not a default.
+
+## x402 position
+
+The machine-to-machine agent-payments rail is consolidating on x402 (Cloudflare
+plus the Coinbase x402 Foundation; MCP tools return HTTP 402). Venly's stance:
+the MCP is the human-gated operator surface; x402 is the machine-to-machine rail.
+This ship states the position and ships a well-formed 402 quote stub. It does not
+ship a production x402 settlement engine, that needs a facilitator decision and
+live rails.
+
+## Skills pack
+
+MCP-consumable workflow docs under `skills/`:
+
+- `reconcile-by-reference-code.md`
+- `four-eyes-approval.md`
+- `stage-and-confirm-transfer.md`
+- `payment-link-lifecycle.md`
+- `x402-quote-walkthrough.md`
+
+## Layout
+
+```
+settlement-mcp/
+  package.json
+  tsconfig.json
+  README.md
+  src/
+    index.ts              entry, stdio transport
+    server.ts             createServer(client, env), registers all tiers
+    constants.ts
+    types.ts              VenlyClient interface + domain types
+    safety.ts             the write-gate (confirm + env + creds)
+    reconcile.ts          pure reconciliation logic
+    client/
+      http-client.ts      HttpVenlyClient (fetch, OAuth, vendored transport)
+    tools/
+      read-tools.ts       tier 1
+      write-tools.ts      tier 2 (fail closed)
+      x402-tools.ts       tier 3 (stub)
+  skills/
+    reconcile-by-reference-code.md
+    four-eyes-approval.md
+    stage-and-confirm-transfer.md
+    payment-link-lifecycle.md
+    x402-quote-walkthrough.md
+    four-eyes-approval.md
+    stage-and-confirm-transfer.md
+  test/
+    helpers.ts            in-memory MCP harness + mock client
+    read-tools.test.ts
+    write-tools.test.ts   includes the critical fail-closed test
+    reconcile.test.ts
+    x402.test.ts
+```

package/dist/client/http-client.d.ts

@@ -0,0 +1,58 @@
+/**
+ * HttpVenlyClient: a minimal fetch-based transport implementing VenlyClient.
+ *
+ * TRANSPORT NOTE
+ * --------------
+ * Minimal by design: OAuth2 client credentials, lazy token fetch, staging
+ * defaults. A future release replaces this with a thin adapter over
+ * `@venlyfinance/sdk` (single-flight token refresh, automatic idempotency
+ * keys, retry/backoff, richer errors) with no change to the tool interface.
+ *
+ * Safety invariants honored here:
+ *  - credentials are read from env ONLY, never logged, never returned in output.
+ *  - no request is issued at construction time; tokens are fetched lazily.
+ *  - this class does not know about the write gate. It only issues a live call
+ *    when a write method is invoked, and write methods are invoked only after
+ *    the gate in safety.ts is armed. Read-only by default is enforced upstream.
+ */
+import type { Account, CreateFiatTransferInput, CreatePaymentLinkRequest, ListRampRequestsParams, OptimisticLockingBody, Party, PaymentLink, RampRequestDto, RampRequestListItem, Transfer, VenlyClient, VirtualBankAccount } from "../types.js";
+export interface HttpVenlyClientConfig {
+    financeBaseUrl?: string;
+    fundflowBaseUrl?: string;
+    tokenUrl?: string;
+    clientId?: string;
+    clientSecret?: string;
+    /** Injectable for tests; defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+}
+export declare class HttpVenlyClient implements VenlyClient {
+    private readonly financeBaseUrl;
+    private readonly fundflowBaseUrl;
+    private readonly tokenUrl;
+    private readonly clientId?;
+    private readonly clientSecret?;
+    private readonly fetchImpl;
+    private token;
+    constructor(config?: HttpVenlyClientConfig);
+    /** Build a client from environment variables. Never logs credentials. */
+    static fromEnv(env?: NodeJS.ProcessEnv): HttpVenlyClient;
+    private getAccessToken;
+    private request;
+    getAccount(accountId: string): Promise<Account>;
+    listVirtualBankAccounts(accountId: string): Promise<VirtualBankAccount[]>;
+    getTransfer(accountId: string, transferId: string): Promise<Transfer>;
+    listParties(params?: {
+        page?: number;
+        size?: number;
+    }): Promise<Party[]>;
+    listRampRequests(params?: ListRampRequestsParams): Promise<RampRequestListItem[]>;
+    getRampRequest(id: string): Promise<RampRequestDto>;
+    getSupportedChains(): Promise<unknown[]>;
+    getFiatCurrencies(): Promise<unknown[]>;
+    getCryptocurrencies(): Promise<unknown[]>;
+    getCompanyFees(): Promise<unknown>;
+    createFiatTransfer(senderAccountId: string, body: CreateFiatTransferInput): Promise<Transfer>;
+    approveRampRequest(id: string, body: OptimisticLockingBody): Promise<RampRequestDto>;
+    rejectRampRequest(id: string, body: OptimisticLockingBody): Promise<RampRequestDto>;
+    createPaymentLink(accountId: string, body: CreatePaymentLinkRequest): Promise<PaymentLink>;
+}

package/dist/client/http-client.js

@@ -0,0 +1,163 @@
+/**
+ * HttpVenlyClient: a minimal fetch-based transport implementing VenlyClient.
+ *
+ * TRANSPORT NOTE
+ * --------------
+ * Minimal by design: OAuth2 client credentials, lazy token fetch, staging
+ * defaults. A future release replaces this with a thin adapter over
+ * `@venlyfinance/sdk` (single-flight token refresh, automatic idempotency
+ * keys, retry/backoff, richer errors) with no change to the tool interface.
+ *
+ * Safety invariants honored here:
+ *  - credentials are read from env ONLY, never logged, never returned in output.
+ *  - no request is issued at construction time; tokens are fetched lazily.
+ *  - this class does not know about the write gate. It only issues a live call
+ *    when a write method is invoked, and write methods are invoked only after
+ *    the gate in safety.ts is armed. Read-only by default is enforced upstream.
+ */
+import { DEFAULT_FINANCE_BASE_URL, DEFAULT_FUNDFLOW_BASE_URL, DEFAULT_TOKEN_URL, } from "../constants.js";
+/** Unwrap the Venly `{ success, result, pagination }` envelope. */
+function unwrap(payload) {
+    if (payload && typeof payload === "object" && "result" in payload) {
+        return payload.result;
+    }
+    return payload;
+}
+export class HttpVenlyClient {
+    financeBaseUrl;
+    fundflowBaseUrl;
+    tokenUrl;
+    clientId;
+    clientSecret;
+    fetchImpl;
+    token = null;
+    constructor(config = {}) {
+        this.financeBaseUrl = config.financeBaseUrl ?? DEFAULT_FINANCE_BASE_URL;
+        this.fundflowBaseUrl = config.fundflowBaseUrl ?? DEFAULT_FUNDFLOW_BASE_URL;
+        this.tokenUrl = config.tokenUrl ?? DEFAULT_TOKEN_URL;
+        this.clientId = config.clientId;
+        this.clientSecret = config.clientSecret;
+        this.fetchImpl = config.fetchImpl ?? fetch;
+    }
+    /** Build a client from environment variables. Never logs credentials. */
+    static fromEnv(env = process.env) {
+        return new HttpVenlyClient({
+            financeBaseUrl: env.VENLY_FINANCE_BASE_URL,
+            fundflowBaseUrl: env.VENLY_FUNDFLOW_BASE_URL,
+            tokenUrl: env.VENLY_TOKEN_URL,
+            clientId: env.VENLY_CLIENT_ID,
+            clientSecret: env.VENLY_CLIENT_SECRET,
+        });
+    }
+    async getAccessToken() {
+        const now = Date.now();
+        if (this.token && this.token.expiresAt > now + 5_000) {
+            return this.token.accessToken;
+        }
+        if (!this.clientId || !this.clientSecret) {
+            // Do not include any credential material in the error.
+            throw new Error("Missing Venly credentials. Set VENLY_CLIENT_ID and VENLY_CLIENT_SECRET.");
+        }
+        const body = new URLSearchParams({
+            grant_type: "client_credentials",
+            client_id: this.clientId,
+            client_secret: this.clientSecret,
+        });
+        const res = await this.fetchImpl(this.tokenUrl, {
+            method: "POST",
+            headers: { "Content-Type": "application/x-www-form-urlencoded" },
+            body,
+        });
+        if (!res.ok) {
+            // Never echo the request body (contains the secret).
+            throw new Error(`Token request failed with status ${res.status}`);
+        }
+        const json = (await res.json());
+        const expiresInMs = (json.expires_in ?? 300) * 1000;
+        this.token = {
+            accessToken: json.access_token,
+            expiresAt: now + expiresInMs,
+        };
+        return json.access_token;
+    }
+    async request(base, method, path, opts = {}) {
+        const token = await this.getAccessToken();
+        const url = new URL(path.replace(/^\//, ""), base.endsWith("/") ? base : base + "/");
+        if (opts.query) {
+            for (const [k, v] of Object.entries(opts.query)) {
+                if (v !== undefined && v !== null)
+                    url.searchParams.set(k, String(v));
+            }
+        }
+        const headers = {
+            Authorization: `Bearer ${token}`,
+            Accept: "application/json",
+        };
+        if (opts.body !== undefined) {
+            headers["Content-Type"] = "application/json";
+            // Idempotency for writes. Production SDK does this automatically.
+            headers["Idempotency-Key"] = crypto.randomUUID();
+        }
+        const res = await this.fetchImpl(url.toString(), {
+            method,
+            headers,
+            body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
+        });
+        if (!res.ok) {
+            throw new Error(`Venly API ${method} ${path} failed with status ${res.status}`);
+        }
+        const json = await res.json();
+        return unwrap(json);
+    }
+    // ----- READ (finance) -----
+    getAccount(accountId) {
+        return this.request(this.financeBaseUrl, "GET", `/accounts/${accountId}`);
+    }
+    listVirtualBankAccounts(accountId) {
+        return this.request(this.financeBaseUrl, "GET", `/accounts/${accountId}/virtual-bank-accounts`);
+    }
+    getTransfer(accountId, transferId) {
+        return this.request(this.financeBaseUrl, "GET", `/accounts/${accountId}/transfers/${transferId}`);
+    }
+    listParties(params = {}) {
+        return this.request(this.financeBaseUrl, "GET", "/parties", { query: params });
+    }
+    // ----- READ (fundflow) -----
+    listRampRequests(params = {}) {
+        return this.request(this.fundflowBaseUrl, "GET", "/v1/ramp-requests", {
+            query: params,
+        });
+    }
+    getRampRequest(id) {
+        return this.request(this.fundflowBaseUrl, "GET", `/v1/ramp-requests/${id}`);
+    }
+    getSupportedChains() {
+        return this.request(this.fundflowBaseUrl, "GET", "/v1/chains");
+    }
+    getFiatCurrencies() {
+        return this.request(this.fundflowBaseUrl, "GET", "/v1/fiat-currencies");
+    }
+    getCryptocurrencies() {
+        return this.request(this.fundflowBaseUrl, "GET", "/v1/crypto-currencies");
+    }
+    getCompanyFees() {
+        return this.request(this.fundflowBaseUrl, "GET", "/v1/fees");
+    }
+    // ----- WRITE -----
+    createFiatTransfer(senderAccountId, body) {
+        return this.request(this.financeBaseUrl, "POST", `/accounts/${senderAccountId}/transfers/fiat`, { body });
+    }
+    approveRampRequest(id, body) {
+        return this.request(this.fundflowBaseUrl, "POST", `/v1/ramp-requests/${id}/approve`, {
+            body,
+        });
+    }
+    rejectRampRequest(id, body) {
+        return this.request(this.fundflowBaseUrl, "POST", `/v1/ramp-requests/${id}/reject`, {
+            body,
+        });
+    }
+    createPaymentLink(accountId, body) {
+        return this.request(this.financeBaseUrl, "POST", `/accounts/${accountId}/fiat-to-crypto/payment-links`, { body });
+    }
+}

package/dist/constants.d.ts

@@ -0,0 +1,13 @@
+/** Shared constants. Defaults point at STAGING so an accidental run never
+ * touches production. Override via env for a real sandbox test. */
+export declare const SERVER_NAME = "venly-settlement-mcp-server";
+export declare const SERVER_VERSION = "0.1.0";
+/** The env flag that must equal "1" for any write tool to execute live. */
+export declare const LIVE_FLAG = "VENLY_MCP_LIVE";
+/** Default base URLs (STAGING). Production values live in the vendored specs:
+ * finance https://api.venlyfinance.com/api/v1, fundflow https://api-fundflow.venly.io */
+export declare const DEFAULT_FINANCE_BASE_URL = "https://api-staging.venlyfinance.com/api/v1";
+export declare const DEFAULT_FUNDFLOW_BASE_URL = "https://api-fundflow-staging.venly.io";
+export declare const DEFAULT_TOKEN_URL = "https://login.venly.io/auth/realms/VenlyFinance/protocol/openid-connect/token";
+/** Cap on serialized tool output length to keep responses readable. */
+export declare const CHARACTER_LIMIT = 30000;

package/dist/constants.js

@@ -0,0 +1,13 @@
+/** Shared constants. Defaults point at STAGING so an accidental run never
+ * touches production. Override via env for a real sandbox test. */
+export const SERVER_NAME = "venly-settlement-mcp-server";
+export const SERVER_VERSION = "0.1.0";
+/** The env flag that must equal "1" for any write tool to execute live. */
+export const LIVE_FLAG = "VENLY_MCP_LIVE";
+/** Default base URLs (STAGING). Production values live in the vendored specs:
+ * finance https://api.venlyfinance.com/api/v1, fundflow https://api-fundflow.venly.io */
+export const DEFAULT_FINANCE_BASE_URL = "https://api-staging.venlyfinance.com/api/v1";
+export const DEFAULT_FUNDFLOW_BASE_URL = "https://api-fundflow-staging.venly.io";
+export const DEFAULT_TOKEN_URL = "https://login.venly.io/auth/realms/VenlyFinance/protocol/openid-connect/token";
+/** Cap on serialized tool output length to keep responses readable. */
+export const CHARACTER_LIMIT = 30_000;

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * Entry point. Builds the server over a real HttpVenlyClient (from env) and
+ * connects it over stdio. Read-only by default; write tools stay disarmed
+ * unless VENLY_MCP_LIVE=1 and credentials are set.
+ *
+ * Credentials are read from env inside HttpVenlyClient and never logged.
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+/**
+ * Entry point. Builds the server over a real HttpVenlyClient (from env) and
+ * connects it over stdio. Read-only by default; write tools stay disarmed
+ * unless VENLY_MCP_LIVE=1 and credentials are set.
+ *
+ * Credentials are read from env inside HttpVenlyClient and never logged.
+ */
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { createServer } from "./server.js";
+import { HttpVenlyClient } from "./client/http-client.js";
+import { LIVE_FLAG } from "./constants.js";
+async function main() {
+    const client = HttpVenlyClient.fromEnv();
+    const server = createServer({ client, env: process.env });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // Log to stderr only (stdout is the MCP channel). No credentials here.
+    const armed = process.env[LIVE_FLAG] === "1";
+    process.stderr.write(`venly-settlement-mcp started. write tools ${armed ? "ARMED (VENLY_MCP_LIVE=1)" : "DISARMED (read-only default)"}.\n`);
+}
+main().catch((err) => {
+    process.stderr.write(`Fatal: ${err.message}\n`);
+    process.exit(1);
+});

package/dist/reconcile.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Pure reconciliation logic: match observed incoming bank transactions on a
+ * EUR vIBAN to the vIBAN whose `referenceCode` they carry.
+ *
+ * Kept pure (no I/O) so it is trivially testable. The read tool fetches the
+ * vIBANs via the VenlyClient and passes them in alongside the operator- or
+ * bank-feed-supplied transactions.
+ */
+import type { ObservedBankTransaction, VirtualBankAccount } from "./types.js";
+export interface ReconcileResult {
+    referenceCode: string;
+    matched: boolean;
+    /** The vIBAN whose referenceCode equals the target, if any. */
+    virtualBankAccount: VirtualBankAccount | null;
+    /** Transactions carrying the target referenceCode. */
+    matchedTransactions: ObservedBankTransaction[];
+    /** Sum of matched transaction amounts. */
+    totalAmount: number;
+    /** Currency of the matched vIBAN (or first matched transaction). */
+    currency: string | null;
+    note: string;
+}
+export declare function reconcileByReferenceCode(referenceCode: string, virtualBankAccounts: VirtualBankAccount[], transactions: ObservedBankTransaction[]): ReconcileResult;

package/dist/reconcile.js

@@ -0,0 +1,38 @@
+/**
+ * Pure reconciliation logic: match observed incoming bank transactions on a
+ * EUR vIBAN to the vIBAN whose `referenceCode` they carry.
+ *
+ * Kept pure (no I/O) so it is trivially testable. The read tool fetches the
+ * vIBANs via the VenlyClient and passes them in alongside the operator- or
+ * bank-feed-supplied transactions.
+ */
+export function reconcileByReferenceCode(referenceCode, virtualBankAccounts, transactions) {
+    const target = referenceCode.trim();
+    const vban = virtualBankAccounts.find((v) => (v.referenceCode ?? "").trim() === target) ?? null;
+    const matchedTransactions = transactions.filter((t) => (t.referenceCode ?? "").trim() === target);
+    const totalAmount = matchedTransactions.reduce((sum, t) => sum + (Number.isFinite(t.amount) ? t.amount : 0), 0);
+    const currency = vban?.currency ?? matchedTransactions[0]?.currency ?? null;
+    const matched = vban !== null && matchedTransactions.length > 0;
+    let note;
+    if (matched) {
+        note = `Matched ${matchedTransactions.length} transaction(s) totalling ${totalAmount} ${currency ?? ""} to vIBAN ${vban?.id}.`;
+    }
+    else if (vban && matchedTransactions.length === 0) {
+        note = `vIBAN ${vban.id} carries referenceCode "${target}" but no supplied transaction references it. Awaiting funds.`;
+    }
+    else if (!vban && matchedTransactions.length > 0) {
+        note = `Transaction(s) reference "${target}" but no vIBAN on this account carries that referenceCode. Possible misdirected payment.`;
+    }
+    else {
+        note = `No vIBAN and no transaction match referenceCode "${target}".`;
+    }
+    return {
+        referenceCode: target,
+        matched,
+        virtualBankAccount: vban,
+        matchedTransactions,
+        totalAmount,
+        currency,
+        note,
+    };
+}

package/dist/safety.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The write-tool safety gate. This is the core safety property of the server.
+ *
+ * A write tool executes a live call ONLY when ALL THREE hold:
+ *   1. the tool arg `confirm === true`
+ *   2. the env flag VENLY_MCP_LIVE === "1"
+ *   3. credentials are present (client id + secret in env)
+ *
+ * If ANY is missing the tool returns a dry-run object describing the exact
+ * request it WOULD have sent, and never calls the transport. Fail closed.
+ */
+export type EnvLike = Record<string, string | undefined>;
+export interface GateDecision {
+    /** true only when confirm + armed env + creds all hold. */
+    armed: boolean;
+    confirm: boolean;
+    liveFlagArmed: boolean;
+    credentialsPresent: boolean;
+    /** Human-readable reasons a live call is blocked (empty when armed). */
+    blockedReasons: string[];
+}
+export declare function credentialsPresent(env: EnvLike): boolean;
+export declare function evaluateWriteGate(confirm: boolean, env: EnvLike): GateDecision;
+export interface DryRunRequest {
+    mode: "dry-run";
+    tool: string;
+    method: "GET" | "POST" | "PUT" | "DELETE";
+    /** Which API this maps to. */
+    api: "finance" | "fundflow";
+    path: string;
+    body?: unknown;
+    gate: GateDecision;
+    note: string;
+}
+export declare function buildDryRun(tool: string, method: DryRunRequest["method"], api: DryRunRequest["api"], path: string, body: unknown, gate: GateDecision): DryRunRequest;