@venlyfinance/settlement-mcp 0.1.1 → 0.2.0

package/dist/types.js

@@ -1,17 +1,9 @@
 /**
- * Domain types + the injectable VenlyClient interface.
+ * Generated API contracts + the injectable VenlyClient interface.
  *
- * These shapes are a minimal projection of the published OpenAPI specs
- * vendored in this repository under `specs/` – finance.yaml (servers:
- * https://api.venlyfinance.com/v1) and fundflow.yaml (servers:
- * https://api-fundflow.venly.io). Only the fields the tools actually read or
- * echo are modeled. Fields are intentionally loose (optional) because this is a
- * thin wrapper, not a full SDK.
- *
- * TRANSPORT NOTE: the bundled HttpVenlyClient is a deliberately minimal fetch
- * transport (see client/http-client.ts). A future release replaces it with a
- * thin adapter over `@venlyfinance/sdk` with no change to this interface;
- * until then the minimal transport is what ships. When that lands, replace
- * HttpVenlyClient with a thin adapter over it and delete the vendored transport.
+ * Finance and Fundflow resources and requests are aliases to the types exported
+ * by `@venlyfinance/sdk`. Only MCP-owned inputs and compatibility shapes are
+ * declared locally. This prevents the MCP from silently drifting away from the
+ * vendored OpenAPI specifications.
  */
 export {};

package/package.json

@@ -1,28 +1,34 @@
 {
   "name": "@venlyfinance/settlement-mcp",
-  "version": "0.1.1",
-  "description": "Venly Settlement MCP server. Human-gated operator surface over the Venly Finance and Fundflow APIs, plus an x402 machine-to-machine quote stub. Read-only by default, write tools fail closed.",
+  "version": "0.2.0",
+  "description": "Venly Finance MCP: SDK-backed tools, resources and prompts for building international money products safely.",
   "type": "module",
   "bin": {
+    "venly-finance-mcp": "dist/index.js",
     "venly-settlement-mcp": "dist/index.js"
   },
   "main": "dist/index.js",
   "files": [
     "dist",
+    "scripts",
     "skills",
-    "README.md"
+    "README.md",
+    "CHANGELOG.md"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.json",
+    "build": "rm -rf dist && tsc -p tsconfig.json",
     "start": "node dist/index.js",
+    "smoke:staging": "npm run build && node scripts/staging-smoke.mjs",
     "test": "node --import tsx --test test/*.test.ts",
-    "typecheck": "tsc -p tsconfig.json --noEmit"
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "typecheck:test": "tsc -p tsconfig.test.json"
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=20"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@venlyfinance/sdk": "^0.1.1",
+    "@modelcontextprotocol/sdk": "^1.30.0",
     "zod": "^3.23.8"
   },
   "devDependencies": {
@@ -33,12 +39,12 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/timdierckxsens/venly-sdk.git",
+    "url": "git+https://github.com/Venly/venly-settlement-sdk.git",
     "directory": "settlement-mcp"
   },
-  "homepage": "https://github.com/timdierckxsens/venly-sdk/tree/main/settlement-mcp#readme",
+  "homepage": "https://github.com/Venly/venly-settlement-sdk/tree/main/settlement-mcp#readme",
   "bugs": {
-    "url": "https://github.com/timdierckxsens/venly-sdk/issues"
+    "url": "https://github.com/Venly/venly-settlement-sdk/issues"
   },
   "keywords": [
     "mcp",
@@ -46,6 +52,8 @@
     "stablecoin",
     "settlement",
     "payments",
+    "finance-api",
+    "ai-agents",
     "x402",
     "venly",
     "fintech",

package/scripts/staging-smoke.mjs

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+
+import { sanitizeErrorMessage } from "../dist/results.js";
+import { runStagingSmoke } from "../dist/staging-smoke.js";
+
+try {
+  await runStagingSmoke();
+  console.log("\nSTAGING SMOKE PASSED: discovery and reads succeeded; writes stayed dry-run.");
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(`\nSTAGING SMOKE FAILED: ${sanitizeErrorMessage(message)}`);
+  process.exitCode = 1;
+}

package/skills/build-international-account.md

@@ -0,0 +1,26 @@
+# Build an international account experience
+
+Use this skill when a user asks an AI coding agent to build an international account,
+stablecoin account or neobank-like customer experience with Venly Finance.
+
+## Rules
+
+1. Read `venly://capabilities`, `venly://safety` and
+   `venly://workflows/international-account` when MCP resources are supported.
+2. Start with `VENLY_ENV=mock`; label every simulated state.
+3. Use `@venlyfinance/sdk` only in server-side application code. Never expose Venly
+   credentials or access tokens to the browser.
+4. Assemble atomic capabilities: party, account, auto-provisioned wallet/balances, EUR
+   receiving account, transfer, status and reconciliation.
+5. Creating a party does not complete KYC/KYB. Show returned compliance states.
+6. Venly provides infrastructure through regulated partners. Do not imply a bank
+   charter, deposit insurance or unsupported geographic/currency coverage.
+7. Card issuing is not exposed by the current Finance OpenAPI contract.
+8. Ask for an explicit decision before moving to staging or arming a write. Dry-run
+   live-environment mutations before confirmation.
+
+## Outcome
+
+Produce a credible customer-facing money-product experience and a README documenting
+the mock setup and explicit staging transition. Do not build a generic infrastructure
+dashboard or hide financial mutations inside one autonomous operation.

package/skills/mock-to-staging.md

@@ -0,0 +1,11 @@
+# Move a Venly Finance build from mock to staging
+
+1. Keep the working mock flow and its visible environment label.
+2. Set `VENLY_ENV=staging` and provide client credentials through server-side secret
+   storage.
+3. Confirm enabled custody model, chains, assets and regulated-partner coverage.
+4. Use a documented KYC-verified staging account before provisioning a EUR vIBAN.
+5. Run read-only smoke checks before setting `VENLY_MCP_LIVE=1`.
+6. Dry-run each intended write, review the normalized request, then explicitly confirm.
+7. Never fall back implicitly to mock when staging authentication or capability checks
+   fail.

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

@@ -1,58 +0,0 @@
-/**
- * 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, CreatePayInSessionRequest, ListRampRequestsParams, OptimisticLockingBody, Party, PaymentSession, 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>;
-    createPayInSession(accountId: string, body: CreatePayInSessionRequest): Promise<PaymentSession>;
-}

package/dist/client/http-client.js

@@ -1,163 +0,0 @@
-/**
- * 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,
-        });
-    }
-    createPayInSession(accountId, body) {
-        return this.request(this.financeBaseUrl, "POST", `/accounts/${accountId}/fiat-to-crypto/payment-sessions`, { body });
-    }
-}