@venlyfinance/settlement-mcp 0.1.1 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,89 @@
+# 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
+its package name and compatibility binary throughout the 0.x line.
+
+### Added
+
+- 23 atomic read, write, reconciliation, and quote tools covering the first
+  international-account builder journey.
+- Explicit `mock`, `staging`, and `production` environments with synthetic mock writes
+  and a separate production-write flag.
+- Discoverable capability, safety, international-account, and mock-to-staging
+  resources.
+- The `build_international_account` MCP prompt and matching portable workflow skills.
+- Machine-readable structured tool results with credential and token redaction.
+- `createServer` refuses to start when an injected client declares an environment that
+  disagrees with `VENLY_ENV`: the mock gate auto-arms writes, so the two must never
+  diverge.
+- A zero-network golden journey covering party, account, wallet, EUR receiving account,
+  transfer, history, and reconciliation behavior.
+- Compile-time assertions that MCP payload types remain exact aliases of the generated
+  Finance and Fundflow SDK contracts.
+
+### Changed
+
+- Finance and Fundflow execution now uses `@venlyfinance/sdk`; the duplicate HTTP,
+  OAuth, retry, and hand-written API type implementation was removed.
+- `venly-finance-mcp` is the preferred binary. `venly-settlement-mcp` remains an alias
+  to the same server.
+- The minimum Node.js version is 20.
+- The official MCP SDK is upgraded to 1.30.0 and resolves Hono 2.0.12.
+
+### Deprecated
+
+- `stage_transfer` remains available for 0.x compatibility but normalizes its legacy
+  fields into the current Finance transfer contract. Its dry-run now previews the exact
+  normalized request a live call sends, a caller-supplied idempotency key survives
+  normalization, and the retired `cryptocurrency` field is rejected with guidance
+  instead of silently dropped. New integrations should use `create_fiat_transfer`.
+
+### Safety and product boundaries
+
+- Live writes remain dry-run unless confirmation, credentials, and the environment
+  flags are present; production requires an additional explicit flag.
+- Creating a party does not complete KYC/KYB. Live EUR receiving-account provisioning
+  requires an eligible verified account.
+- The MCP does not imply universal bank-account coverage, a bank charter, card issuing,
+  external-bank payouts, or autonomous production money movement.
+
+### Security
+
+- Runtime dependency audits report zero findings after the MCP SDK/Hono upgrade.

package/README.md

@@ -1,39 +1,63 @@
-# Venly Settlement MCP server
+# Venly Finance MCP
 
-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.
+Build and operate international money-product experiences over the Venly Finance
+and Fundflow APIs. The server exposes atomic financial tools, contract-backed
+product resources and a `build_international_account` prompt to MCP clients and
+coding agents.
 
-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.
+**Tools expose financial capabilities. Prompts and skills assemble products. The
+host coding agent builds the interface.** This is one expanded implementation of
+the original Settlement MCP, not a second server.
 
-Status: v0.1.1 (realigned to the live published OpenAPI specs: staging base URL
-and auth host corrected, `create_payment_link` became `create_payment_session`
-to match the live API). 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.
+Start in explicit mock mode with no credentials or network. Move the same SDK
+business logic to staging only after reviewing capabilities, compliance state and
+the normalized write requests. Staging and production writes fail closed.
+
+The Venly Finance builder surface documented here is the v0.2.0 release line.
 
 ## What it is
 
 - Built on the official MCP TypeScript SDK (`@modelcontextprotocol/sdk`), Node
-  >= 18, stdio transport.
+  >= 20, stdio transport.
 - A thin layer over the Venly Finance API (`finance.yaml`, servers
   `https://api.venlyfinance.com/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.
+  `SdkVenlyClient` delegates to the published `@venlyfinance/sdk`; tests inject
+  a lightweight mock.
+
+### Transport
+
+The MCP uses [`@venlyfinance/sdk`](../) for OAuth2 client credentials, token
+caching/refresh, retries, idempotency and normalized API errors. It does not
+maintain a second HTTP or authentication implementation.
+
+## Try the builder in mock mode
+
+```json
+{
+  "mcpServers": {
+    "venly-finance": {
+      "command": "npx",
+      "args": ["-y", "@venlyfinance/settlement-mcp"],
+      "env": { "VENLY_ENV": "mock" }
+    }
+  }
+}
+```
 
-### Transport note
+Then select the `build_international_account` prompt or ask the agent to read:
 
-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.
+- `venly://capabilities`
+- `venly://safety`
+- `venly://workflows/international-account`
+- `venly://workflows/mock-to-staging`
 
-## The three tool tiers
+Mock mutations execute against SDK fixtures, are labelled `mode: "mock"`, use no
+credentials and make no network requests.
+
+## Tool tiers
 
 ### 1. Read tools (always on)
 
@@ -43,11 +67,16 @@ Call GETs only. No mutation, safe by default.
 |---|---|
 | `list_ramp_requests` | fundflow `GET /v1/ramp-requests` |
 | `get_ramp_request` | fundflow `GET /v1/ramp-requests/{id}` |
+| `list_accounts` | finance `GET /accounts` |
 | `get_account` | finance `GET /accounts/{accountId}` |
+| `list_wallets` | finance `GET /accounts/{accountId}/wallets` (including token balances) |
 | `list_virtual_bank_accounts` | finance `GET /accounts/{accountId}/virtual-bank-accounts` |
+| `get_virtual_bank_account` | finance `GET /accounts/{accountId}/virtual-bank-accounts/{id}` |
 | `reconcile_by_reference_code` | composite: lists vIBANs, matches supplied transactions by referenceCode |
+| `list_transfers` | finance `GET /accounts/{accountId}/transfers` |
 | `get_transfer` | finance `GET /accounts/{accountId}/transfers/{transferId}` |
 | `list_parties` | finance `GET /parties` |
+| `get_party` | finance `GET /parties/{partyId}` |
 | `get_reference_data` | fundflow chains / fiat-currencies / crypto-currencies / fees |
 
 `reconcile_by_reference_code` is the EUR vIBAN reconciliation: a customer sends
@@ -58,8 +87,13 @@ 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_session`.
+Builder writes: `create_party`, `create_account`,
+`create_virtual_bank_account`, `create_fiat_transfer`,
+`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
+`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
 safety model below.
@@ -74,8 +108,8 @@ 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:
+Outside explicit mock mode, read-only/dry-run is the default posture. A staging
+write 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
@@ -86,6 +120,10 @@ 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.
 
+Production additionally requires `VENLY_ENV=production` and
+`VENLY_MCP_PRODUCTION=1`. There is no implicit fallback from a live environment
+to mock data.
+
 Other invariants:
 
 - Credentials are read from env, never logged, never returned in tool output.
@@ -110,7 +148,7 @@ The fastest path once published to npm - one line in any MCP client config:
 ```json
 {
   "mcpServers": {
-    "venly-settlement": {
+    "venly-finance": {
       "command": "npx",
       "args": ["-y", "@venlyfinance/settlement-mcp"]
     }
@@ -132,10 +170,11 @@ MCP client config example:
 ```json
 {
   "mcpServers": {
-    "venly-settlement": {
+    "venly-finance": {
       "command": "node",
       "args": ["/absolute/path/to/settlement-mcp/dist/index.js"],
       "env": {
+        "VENLY_ENV": "staging",
         "VENLY_FINANCE_BASE_URL": "https://api-staging.venlyfinance.com/v1",
         "VENLY_FUNDFLOW_BASE_URL": "https://api-fundflow-staging.venly.io"
       }
@@ -151,16 +190,34 @@ Override via env:
 
 | Env var | Default (staging) |
 |---|---|
+| `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) |
 | `VENLY_CLIENT_ID` | unset (read-only until set) |
 | `VENLY_CLIENT_SECRET` | unset |
 | `VENLY_MCP_LIVE` | unset (writes disarmed) |
+| `VENLY_MCP_PRODUCTION` | unset (production 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.
 
+## Safe staging smoke
+
+Build the server and verify its complete discovery surface, credentialled staging
+reads, and fail-closed write gate without mutating staging:
+
+```bash
+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.
+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
+contains counts and status only – not party/account payloads, credentials, or tokens.
+
 ## Enabling live writes (a deliberate operator decision)
 
 Live writes are OFF. To arm them, the operator must:
@@ -172,6 +229,10 @@ Live writes are OFF. To arm them, the operator must:
 Until all three are set, every write tool dry-runs. Arming the flag and
 provisioning credentials is a deliberate, human decision, not a default.
 
+Production also requires `VENLY_MCP_PRODUCTION=1` on the server. Mock mode does
+not use these flags because it cannot reach the network; results remain clearly
+labelled synthetic.
+
 ## x402 position
 
 The machine-to-machine agent-payments rail is consolidating on x402 (Cloudflare
@@ -190,6 +251,8 @@ MCP-consumable workflow docs under `skills/`:
 - `stage-and-confirm-transfer.md`
 - `payment-session-lifecycle.md`
 - `x402-quote-walkthrough.md`
+- `build-international-account.md`
+- `mock-to-staging.md`
 
 ## Layout
 
@@ -202,11 +265,15 @@ settlement-mcp/
     index.ts              entry, stdio transport
     server.ts             createServer(client, env), registers all tiers
     constants.ts
-    types.ts              VenlyClient interface + domain types
+    types.ts              Generated SDK aliases + MCP-owned compatibility types
     safety.ts             the write-gate (confirm + env + creds)
     reconcile.ts          pure reconciliation logic
+    resources.ts          capability, safety and workflow resources
+    prompts.ts            build_international_account prompt
+    results.ts            text + structured output and error redaction
+    staging-smoke.ts      safe discovery/read/dry-run staging verification
     client/
-      http-client.ts      HttpVenlyClient (fetch, OAuth, vendored transport)
+      sdk-client.ts       Adapter over @venlyfinance/sdk
     tools/
       read-tools.ts       tier 1
       write-tools.ts      tier 2 (fail closed)
@@ -217,8 +284,8 @@ settlement-mcp/
     stage-and-confirm-transfer.md
     payment-session-lifecycle.md
     x402-quote-walkthrough.md
-    four-eyes-approval.md
-    stage-and-confirm-transfer.md
+    build-international-account.md
+    mock-to-staging.md
   test/
     helpers.ts            in-memory MCP harness + mock client
     read-tools.test.ts

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

@@ -0,0 +1,67 @@
+import { FundflowClient, VenlyFinanceClient, type MockCall } from "@venlyfinance/sdk";
+import { type VenlyEnvironment } from "../constants.js";
+import type { Account, CryptoCurrency, CreateAccountInput, CreateCryptoTransferInput, CreateFiatTransferInput, CreatePartyInput, CreatePayInSessionRequest, CreateVirtualBankAccountInput, CurrentCreateFiatTransferInput, FiatCurrency, ListRampRequestsParams, OptimisticLockingBody, Party, PaymentSession, RampRequestDto, RampRequestListItem, SupportedChains, Transfer, VenlyClient, VirtualBankAccount, VenlyFee, Wallet } from "../types.js";
+/**
+ * Normalize the legacy stage_transfer input to the current Finance
+ * CreateFiatTransferInput wire shape. Exported so the write tool can show the
+ * exact normalized request in its dry-run preview – the preview and the live
+ * call must never diverge. The retired `cryptocurrency` field is rejected
+ * rather than silently dropped: the current contract resolves the fiat amount
+ * to the account's settlement asset itself.
+ */
+export declare function normalizeLegacyFiatTransfer(body: CreateFiatTransferInput): CurrentCreateFiatTransferInput;
+/**
+ * Adapter from the generated Venly Finance SDK surface to the stable MCP
+ * client contract. This keeps tools transport-agnostic while ensuring auth,
+ * retries, idempotency and endpoint schemas come from the published SDK.
+ */
+export declare class SdkVenlyClient implements VenlyClient {
+    private readonly finance;
+    private readonly fundflow;
+    readonly environment: VenlyEnvironment;
+    private readonly hasCredentials;
+    constructor(finance: VenlyFinanceClient, fundflow: FundflowClient, environment: VenlyEnvironment, hasCredentials?: boolean);
+    static mock(): SdkVenlyClient;
+    static fromEnv(env: Record<string, string | undefined>): SdkVenlyClient;
+    /** Exposed for deterministic zero-network adapter and journey tests. */
+    get financeMockCalls(): readonly MockCall[];
+    /** Exposed for deterministic zero-network adapter and journey tests. */
+    get fundflowMockCalls(): readonly MockCall[];
+    private assertReady;
+    listRampRequests(params?: ListRampRequestsParams): Promise<RampRequestListItem[]>;
+    getRampRequest(id: string): Promise<RampRequestDto>;
+    getAccount(accountId: string): Promise<Account>;
+    listAccounts(params?: {
+        page?: number;
+        size?: number;
+    }): Promise<Account[]>;
+    listWallets(accountId: string, params?: {
+        page?: number;
+        size?: number;
+    }): Promise<Wallet[]>;
+    listVirtualBankAccounts(accountId: string): Promise<VirtualBankAccount[]>;
+    getVirtualBankAccount(accountId: string, virtualBankAccountId: string): Promise<VirtualBankAccount>;
+    listTransfers(accountId: string, params?: {
+        page?: number;
+        size?: number;
+    }): Promise<Transfer[]>;
+    getTransfer(accountId: string, transferId: string): Promise<Transfer>;
+    listParties(params?: {
+        page?: number;
+        size?: number;
+    }): Promise<Party[]>;
+    getParty(partyId: string): Promise<Party>;
+    getSupportedChains(): Promise<SupportedChains[]>;
+    getFiatCurrencies(): Promise<FiatCurrency[]>;
+    getCryptocurrencies(): Promise<CryptoCurrency[]>;
+    getCompanyFees(): Promise<VenlyFee[]>;
+    createFiatTransfer(senderAccountId: string, body: CreateFiatTransferInput): Promise<Transfer>;
+    createParty(body: CreatePartyInput): Promise<Party>;
+    createAccount(body: CreateAccountInput): Promise<Account>;
+    createVirtualBankAccount(accountId: string, body: CreateVirtualBankAccountInput): Promise<VirtualBankAccount>;
+    createCurrentFiatTransfer(senderAccountId: string, body: CurrentCreateFiatTransferInput): Promise<Transfer>;
+    createCryptoTransfer(senderAccountId: string, body: CreateCryptoTransferInput): Promise<Transfer>;
+    approveRampRequest(id: string, body: OptimisticLockingBody): Promise<RampRequestDto>;
+    rejectRampRequest(id: string, body: OptimisticLockingBody): Promise<RampRequestDto>;
+    createPayInSession(accountId: string, body: CreatePayInSessionRequest): Promise<PaymentSession>;
+}

package/dist/client/sdk-client.js

@@ -0,0 +1,183 @@
+import { FundflowClient, VenlyFinanceClient, } from "@venlyfinance/sdk";
+import { resolveVenlyEnvironment, } from "../constants.js";
+/**
+ * Normalize the legacy stage_transfer input to the current Finance
+ * CreateFiatTransferInput wire shape. Exported so the write tool can show the
+ * exact normalized request in its dry-run preview – the preview and the live
+ * call must never diverge. The retired `cryptocurrency` field is rejected
+ * rather than silently dropped: the current contract resolves the fiat amount
+ * to the account's settlement asset itself.
+ */
+export function normalizeLegacyFiatTransfer(body) {
+    if (body.cryptocurrency !== undefined) {
+        throw new Error("cryptocurrency is not part of the current fiat-transfer contract and would be ignored; " +
+            "omit it (the fiat amount is resolved to the account's settlement asset) or use " +
+            "create_crypto_transfer for an asset-denominated transfer.");
+    }
+    return {
+        receiverAccountId: body.receiverAccountId,
+        ...(body.receiverExternalId === undefined
+            ? {}
+            : { receiverExternalId: body.receiverExternalId }),
+        currency: body.fiatCurrency,
+        amount: Number(body.fiatAmount),
+        description: body.description,
+        merchantReference: body.merchantReference,
+        idempotencyKey: body.idempotencyKey ?? crypto.randomUUID(),
+    };
+}
+/**
+ * Adapter from the generated Venly Finance SDK surface to the stable MCP
+ * client contract. This keeps tools transport-agnostic while ensuring auth,
+ * retries, idempotency and endpoint schemas come from the published SDK.
+ */
+export class SdkVenlyClient {
+    finance;
+    fundflow;
+    environment;
+    hasCredentials;
+    constructor(finance, fundflow, environment, hasCredentials = true) {
+        this.finance = finance;
+        this.fundflow = fundflow;
+        this.environment = environment;
+        this.hasCredentials = hasCredentials;
+    }
+    static mock() {
+        return new SdkVenlyClient(new VenlyFinanceClient({ environment: "mock" }), new FundflowClient({ environment: "mock" }), "mock", true);
+    }
+    static fromEnv(env) {
+        const environment = resolveVenlyEnvironment(env);
+        if (environment === "mock")
+            return SdkVenlyClient.mock();
+        const clientId = env.VENLY_CLIENT_ID ?? "";
+        const clientSecret = env.VENLY_CLIENT_SECRET ?? "";
+        return new SdkVenlyClient(new VenlyFinanceClient({
+            clientId,
+            clientSecret,
+            environment,
+            baseUrl: env.VENLY_FINANCE_BASE_URL,
+            tokenUrl: env.VENLY_TOKEN_URL,
+        }), new FundflowClient({
+            clientId,
+            clientSecret,
+            environment,
+            baseUrl: env.VENLY_FUNDFLOW_BASE_URL,
+            tokenUrl: env.VENLY_TOKEN_URL,
+        }), environment, Boolean(env.VENLY_CLIENT_ID && env.VENLY_CLIENT_SECRET));
+    }
+    /** Exposed for deterministic zero-network adapter and journey tests. */
+    get financeMockCalls() {
+        return this.finance.mock?.calls ?? [];
+    }
+    /** Exposed for deterministic zero-network adapter and journey tests. */
+    get fundflowMockCalls() {
+        return this.fundflow.mock?.calls ?? [];
+    }
+    assertReady() {
+        if (this.environment !== "mock" && !this.hasCredentials) {
+            throw new Error("Missing Venly credentials. Set VENLY_CLIENT_ID and VENLY_CLIENT_SECRET.");
+        }
+    }
+    async listRampRequests(params) {
+        this.assertReady();
+        const page = await this.fundflow.rampRequests.list(params);
+        return page.items;
+    }
+    async getRampRequest(id) {
+        this.assertReady();
+        return this.fundflow.rampRequests.get(id);
+    }
+    async getAccount(accountId) {
+        this.assertReady();
+        return this.finance.accounts.get(accountId);
+    }
+    async listAccounts(params) {
+        this.assertReady();
+        const page = await this.finance.accounts.list(params);
+        return page.items;
+    }
+    async listWallets(accountId, params) {
+        this.assertReady();
+        const page = await this.finance.wallets.list(accountId, params);
+        return page.items;
+    }
+    async listVirtualBankAccounts(accountId) {
+        this.assertReady();
+        const page = await this.finance.virtualBankAccounts.list(accountId);
+        return page.items;
+    }
+    async getVirtualBankAccount(accountId, virtualBankAccountId) {
+        this.assertReady();
+        return this.finance.virtualBankAccounts.get(accountId, virtualBankAccountId);
+    }
+    async listTransfers(accountId, params) {
+        this.assertReady();
+        const page = await this.finance.transfers.list(accountId, params);
+        return page.items;
+    }
+    async getTransfer(accountId, transferId) {
+        this.assertReady();
+        return this.finance.transfers.get(accountId, transferId);
+    }
+    async listParties(params) {
+        this.assertReady();
+        const page = await this.finance.parties.list(params);
+        return page.items;
+    }
+    async getParty(partyId) {
+        this.assertReady();
+        return this.finance.parties.get(partyId);
+    }
+    async getSupportedChains() {
+        this.assertReady();
+        return this.fundflow.referenceData.chains();
+    }
+    async getFiatCurrencies() {
+        this.assertReady();
+        return this.fundflow.referenceData.fiatCurrencies();
+    }
+    async getCryptocurrencies() {
+        this.assertReady();
+        return this.fundflow.referenceData.cryptoCurrencies();
+    }
+    async getCompanyFees() {
+        this.assertReady();
+        return this.fundflow.fees.listCompanyFees();
+    }
+    async createFiatTransfer(senderAccountId, body) {
+        this.assertReady();
+        return this.finance.transfers.createFiat(senderAccountId, normalizeLegacyFiatTransfer(body));
+    }
+    async createParty(body) {
+        this.assertReady();
+        return this.finance.parties.create(body);
+    }
+    async createAccount(body) {
+        this.assertReady();
+        return this.finance.accounts.create(body);
+    }
+    async createVirtualBankAccount(accountId, body) {
+        this.assertReady();
+        return this.finance.virtualBankAccounts.create(accountId, body);
+    }
+    async createCurrentFiatTransfer(senderAccountId, body) {
+        this.assertReady();
+        return this.finance.transfers.createFiat(senderAccountId, body);
+    }
+    async createCryptoTransfer(senderAccountId, body) {
+        this.assertReady();
+        return this.finance.transfers.createCrypto(senderAccountId, body);
+    }
+    async approveRampRequest(id, body) {
+        this.assertReady();
+        return this.fundflow.rampRequests.approve(id, body);
+    }
+    async rejectRampRequest(id, body) {
+        this.assertReady();
+        return this.fundflow.rampRequests.reject(id, body);
+    }
+    async createPayInSession(accountId, body) {
+        this.assertReady();
+        return this.finance.paymentSessions.create(accountId, body);
+    }
+}

package/dist/constants.d.ts

@@ -1,9 +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.1";
+/** 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 ENVIRONMENT_FLAG = "VENLY_ENV";
+export type VenlyEnvironment = "mock" | "staging" | "production";
+export declare function resolveVenlyEnvironment(env: Record<string, string | undefined>): VenlyEnvironment;
 /** The env flag that must equal "1" for any write tool to execute live. */
 export declare const LIVE_FLAG = "VENLY_MCP_LIVE";
+export declare const PRODUCTION_FLAG = "VENLY_MCP_PRODUCTION";
 /** Default base URLs (STAGING). Production values live in the vendored specs:
  * finance https://api.venlyfinance.com/v1, fundflow https://api-fundflow.venly.io */
 export declare const DEFAULT_FINANCE_BASE_URL = "https://api-staging.venlyfinance.com/v1";

package/dist/constants.js

@@ -1,9 +1,21 @@
-/** 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.1";
+/** 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 ENVIRONMENT_FLAG = "VENLY_ENV";
+export function resolveVenlyEnvironment(env) {
+    // 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;
+    }
+    throw new Error(`${ENVIRONMENT_FLAG} must be one of mock, staging, production; received ${JSON.stringify(value)}`);
+}
 /** The env flag that must equal "1" for any write tool to execute live. */
 export const LIVE_FLAG = "VENLY_MCP_LIVE";
+export const PRODUCTION_FLAG = "VENLY_MCP_PRODUCTION";
 /** Default base URLs (STAGING). Production values live in the vendored specs:
  * finance https://api.venlyfinance.com/v1, fundflow https://api-fundflow.venly.io */
 export const DEFAULT_FINANCE_BASE_URL = "https://api-staging.venlyfinance.com/v1";

package/dist/index.d.ts

@@ -1,9 +1,10 @@
 #!/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.
+ * Entry point. Builds the server over the official Venly Finance SDK and
+ * connects it over stdio. Read-only by default outside explicit mock mode;
+ * staging/production write tools stay disarmed unless VENLY_MCP_LIVE=1 and
+ * credentials are set.
  *
- * Credentials are read from env inside HttpVenlyClient and never logged.
+ * Credentials are read from env inside SdkVenlyClient and never logged.
  */
 export {};