@finrock/mcp 0.0.0-stage → 1.0.0

package/dist/http.js

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+/**
+ * Hosted entry point (mcp.finrock.io): stateless Streamable HTTP on POST / (and POST /mcp, the
+ * original path, kept so existing client configs keep working).
+ * No Finrock credentials are held here; every tool is read-only.
+ */
+import express from "express";
+import { hostHeaderValidation } from "@modelcontextprotocol/sdk/server/middleware/hostHeaderValidation.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { pathToFileURL } from "node:url";
+import { DocsClient } from "./docs.js";
+import { createServer, SERVER_NAME, SERVER_VERSION } from "./server.js";
+/** Hostnames accepted in the Host header when MCP_ALLOWED_HOSTS is unset. */
+export const DEFAULT_ALLOWED_HOSTS = ["mcp.finrock.io", "localhost", "127.0.0.1", "[::1]"];
+/** Parses MCP_ALLOWED_HOSTS: comma-separated hostnames (no ports), or "*" to accept any Host. */
+export function parseAllowedHosts(value) {
+    if (value === undefined || value.trim() === "")
+        return DEFAULT_ALLOWED_HOSTS;
+    const hosts = value.split(",").map((h) => h.trim().toLowerCase()).filter(Boolean);
+    return hosts.includes("*") ? undefined : hosts;
+}
+/**
+ * @param opts.allowedHosts Host header allowlist (DNS rebinding protection); undefined accepts any Host.
+ */
+export function createHttpApp(opts = {}) {
+    const docs = opts.docs ?? new DocsClient({ baseUrl: process.env.FINROCK_DOCS_URL });
+    const app = express();
+    // Health probes (Docker, Azure, load balancers) often send an IP or internal name as Host,
+    // so /healthz is answered before the Host allowlist.
+    app.get("/healthz", (_req, res) => void res.json({ ok: true }));
+    if (opts.allowedHosts)
+        app.use(hostHeaderValidation(opts.allowedHosts));
+    app.use(express.json());
+    // Browser-based MCP clients need CORS; the server holds no user data, so any origin is fine.
+    app.use((req, res, next) => {
+        res.setHeader("Access-Control-Allow-Origin", "*");
+        res.setHeader("Access-Control-Allow-Methods", "GET, POST, DELETE, OPTIONS");
+        res.setHeader("Access-Control-Allow-Headers", "Content-Type, Accept, Authorization, Mcp-Session-Id, Mcp-Protocol-Version, Last-Event-ID");
+        res.setHeader("Access-Control-Expose-Headers", "Mcp-Session-Id, Mcp-Protocol-Version");
+        if (req.method === "OPTIONS")
+            return void res.sendStatus(204);
+        next();
+    });
+    const handleMcp = async (req, res) => {
+        // Stateless: a fresh server and transport per request, sharing the docs cache.
+        const server = createServer({ docs });
+        const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined, enableJsonResponse: true });
+        res.on("close", () => {
+            void transport.close();
+            void server.close();
+        });
+        try {
+            await server.connect(transport);
+            await transport.handleRequest(req, res, req.body);
+        }
+        catch (err) {
+            console.error("MCP request failed", err);
+            if (!res.headersSent) {
+                res.status(500).json({ jsonrpc: "2.0", error: { code: -32603, message: "Internal server error" }, id: null });
+            }
+        }
+    };
+    app.post(["/", "/mcp"], handleMcp);
+    const notAllowed = (_req, res) => void res
+        .status(405)
+        .set("Allow", "POST")
+        .json({ jsonrpc: "2.0", error: { code: -32000, message: "Method not allowed: this server is stateless" }, id: null });
+    // A browser or curl hitting the root gets a short description; an MCP client opening an SSE
+    // stream (Accept: text/event-stream) gets 405 like on /mcp, since there is no stream to open.
+    app.get("/", (req, res, next) => {
+        if (req.accepts(["application/json", "text/event-stream"]) === "text/event-stream")
+            return next();
+        res.json({
+            name: SERVER_NAME,
+            version: SERVER_VERSION,
+            mcp: "/",
+            transport: "streamable-http",
+            docs: "https://apidocs.finrock.io",
+        });
+    });
+    app.get(["/", "/mcp"], notAllowed);
+    app.delete(["/", "/mcp"], notAllowed);
+    return app;
+}
+const isMain = process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isMain) {
+    const port = Number(process.env.PORT ?? 3000);
+    // ALLOWED_HOSTS is the older name, still honoured.
+    const allowedHosts = parseAllowedHosts(process.env.MCP_ALLOWED_HOSTS ?? process.env.ALLOWED_HOSTS);
+    createHttpApp({ allowedHosts }).listen(port, () => {
+        console.log(`Finrock MCP server listening on :${port} (POST / and /mcp)`);
+        console.log(allowedHosts ? `Allowed Host headers: ${allowedHosts.join(", ")}` : "Warning: any Host header accepted (MCP_ALLOWED_HOSTS=*)");
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { createServer, SERVER_NAME, SERVER_VERSION } from "./server.js";
+export { createHttpApp } from "./http.js";
+export { DocsClient, parseLlmsTxt } from "./docs.js";
+export { buildGuide, listGuides, STACKS } from "./guides.js";
+export { verifyWebhookSignature, FINROCK_WEBHOOK_PUBLIC_KEY } from "./webhook.js";
+export { FinrockClient, FinrockApiError } from "./api/client.js";
+export { registerApiTools, apiToolMode } from "./api/tools.js";

package/dist/index.js

@@ -0,0 +1,7 @@
+export { createServer, SERVER_NAME, SERVER_VERSION } from "./server.js";
+export { createHttpApp } from "./http.js";
+export { DocsClient, parseLlmsTxt } from "./docs.js";
+export { buildGuide, listGuides, STACKS } from "./guides.js";
+export { verifyWebhookSignature, FINROCK_WEBHOOK_PUBLIC_KEY } from "./webhook.js";
+export { FinrockClient, FinrockApiError } from "./api/client.js";
+export { registerApiTools, apiToolMode } from "./api/tools.js";

package/dist/server.d.ts

@@ -0,0 +1,17 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { DocsClient } from "./docs.js";
+import { type FinrockClient } from "./api/client.js";
+import { type ApiToolOptions } from "./api/tools.js";
+export declare const SERVER_NAME = "finrock";
+export declare const SERVER_VERSION = "1.0.0";
+export interface ServerDeps {
+    docs?: DocsClient;
+    guidesDir?: string;
+    /** Signed API client built from the user's own credentials (local package only). */
+    api?: FinrockClient;
+    apiOptions?: ApiToolOptions;
+    /** Base URL for Finrock's public endpoints when no API client is given. */
+    apiBaseUrl?: string;
+    fetch?: typeof fetch;
+}
+export declare function createServer(deps?: ServerDeps): McpServer;

package/dist/server.js

@@ -0,0 +1,229 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { DocsClient } from "./docs.js";
+import { STACKS, STACK_LABELS, buildGuide, listGuides } from "./guides.js";
+import { SETUP_CLIENTS, SETUP_OS, buildAccountSetup } from "./setup.js";
+import { verifyWebhookSignature } from "./webhook.js";
+import { DEFAULT_API_URL, errorMessage, publicGet, withQuery } from "./api/client.js";
+import { describeMode, registerApiTools } from "./api/tools.js";
+export const SERVER_NAME = "finrock";
+export const SERVER_VERSION = "1.0.0";
+const INSTRUCTIONS = `Finrock (https://finrock.io) is a non-custodial MPC wallet platform for accepting, holding and sending crypto. This server helps you add Finrock payments to an application. It reads the live Finrock docs and returns working integration code; it never touches anyone's Finrock account.
+
+Suggested workflow:
+1. Pick the integration that fits: call list_integration_guides. Hosted invoices (accept-payments) or the payment widget suit checkouts; deposit-addresses suit balances and top-ups; withdrawals suit payouts; webhooks are needed by almost every integration.
+2. Call get_integration_guide with that goal and the app's stack, and adapt the code to the app's framework, data layer and conventions.
+3. Use search_docs and read_doc for exact request fields, response shapes, asset tickers and edge cases.
+
+Rules for any code you write:
+- Finrock API calls must run server-side only. The API key and RSA private key must never reach browser or mobile code, logs, or source control.
+- Sign every request with a fresh RS256 JWT (unique nonce, exp at most 30s after iat, bodyHash of the exact body sent).
+- Verify webhook x-signature against the raw body before parsing, and make handlers idempotent.
+- Only treat a payment as complete after a server-side check (a verified webhook or a fresh API read), never from a browser redirect or callback.`;
+const ACCOUNT_OFF = `
+
+Account tools are not enabled on this connection, so you cannot read or change anyone's Finrock account here. To let an agent manage a Finrock account directly (create invoices and addresses, check balances and transactions), run the local package with the account's own credentials. When the user asks for that, offer to set it up and call setup_account_access for their OS and client: it keeps the API key and private key in the OS keychain instead of plain config. Never ask the user to paste either key into the chat.`;
+const accountOn = (mode) => `
+
+Account tools are enabled with the user's own Finrock credentials (mode: ${mode}). They act on a real account: confirm with the user before creating anything, and always before any tool that moves funds. Use validate_address before sending to an external address, give every create_transaction a unique sequence_id, and never resubmit a pending transaction with a new sequence_id.`;
+const text = (t) => ({ content: [{ type: "text", text: t }] });
+const fail = (t) => ({ content: [{ type: "text", text: t }], isError: true });
+export function createServer(deps = {}) {
+    const docs = deps.docs ?? new DocsClient();
+    const guides = listGuides(deps.guidesDir);
+    const goals = guides.map((g) => g.goal);
+    const server = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION, title: "Finrock" }, { instructions: INSTRUCTIONS + (deps.api ? accountOn(describeMode(deps.apiOptions ?? {})) : ACCOUNT_OFF) });
+    server.registerTool("search_docs", {
+        title: "Search Finrock docs",
+        description: "Full-text search over the live Finrock API documentation (guides, concepts, API reference). Returns the best-matching pages with a snippet; read one in full with read_doc.",
+        inputSchema: {
+            query: z.string().min(1).describe("What to look for, e.g. 'create invoice fields' or 'XRP destination tag'"),
+            limit: z.number().int().min(1).max(20).optional().describe("Maximum results (default 8)"),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, async ({ query, limit }) => {
+        try {
+            const hits = await docs.search(query, { limit });
+            if (hits.length === 0)
+                return text(`No Finrock docs pages matched "${query}". Try list_docs to browse.`);
+            return text(hits
+                .map((h, i) => `${i + 1}. **${h.title}** (\`${h.path}\`)\n   ${h.url}\n   ${h.snippet}`)
+                .join("\n\n"));
+        }
+        catch (err) {
+            return fail(`Could not search the Finrock docs: ${errorMessage(err)}`);
+        }
+    });
+    server.registerTool("read_doc", {
+        title: "Read a Finrock docs page",
+        description: "Return one Finrock documentation page as Markdown, including request/response examples. Accepts a path such as 'api-reference/invoicing/create-invoice' or a full apidocs.finrock.io URL.",
+        inputSchema: {
+            page: z.string().min(1).describe("Page path from search_docs/list_docs, or a full docs URL"),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, async ({ page }) => {
+        try {
+            const { url, markdown } = await docs.readPage(page);
+            return text(`Source: ${url.replace(/\.md$/, "")}\n\n${markdown}`);
+        }
+        catch (err) {
+            return fail(`Could not read "${page}": ${errorMessage(err)}. Use search_docs or list_docs to find valid paths.`);
+        }
+    });
+    server.registerTool("list_docs", {
+        title: "List Finrock docs pages",
+        description: "List every page of the Finrock documentation with its path and one-line description, grouped by section.",
+        inputSchema: {
+            section: z
+                .string()
+                .optional()
+                .describe("Only this section, e.g. 'guides', 'concepts', 'reference', 'api-reference'"),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, async ({ section }) => {
+        try {
+            const pages = (await docs.listPages()).filter((p) => !section || p.section === section);
+            if (pages.length === 0)
+                return text(`No pages in section "${section}".`);
+            const bySection = new Map();
+            for (const p of pages)
+                bySection.set(p.section, [...(bySection.get(p.section) ?? []), p]);
+            return text([...bySection]
+                .map(([s, ps]) => `## ${s}\n` + ps.map((p) => `- \`${p.path}\`: ${p.title}${p.description ? `. ${p.description}` : ""}`).join("\n"))
+                .join("\n\n"));
+        }
+        catch (err) {
+            return fail(`Could not load the Finrock docs index: ${errorMessage(err)}`);
+        }
+    });
+    server.registerTool("list_integration_guides", {
+        title: "List Finrock integration guides",
+        description: "List the ready-made Finrock integration recipes (accept payments, payment widget, deposit addresses, webhooks, withdrawals, authentication) and the stacks they support.",
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async () => text(guides.map((g) => `- **${g.goal}**: ${g.title}. ${g.summary}`).join("\n") +
+        `\n\nStacks: ${STACKS.map((s) => `\`${s}\` (${STACK_LABELS[s]})`).join(", ")}.` +
+        "\nCall get_integration_guide with a goal and stack."));
+    server.registerTool("get_integration_guide", {
+        title: "Get a Finrock integration guide",
+        description: "Step-by-step instructions plus production-ready code to add a Finrock capability to an app in a given stack, including the request-signing client where needed. Adapt names and data access to the target codebase.",
+        inputSchema: {
+            goal: z.enum(goals).describe("Which integration to build; see list_integration_guides"),
+            stack: z.enum(STACKS).default("node").describe("Target stack of the app"),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async ({ goal, stack }) => {
+        try {
+            return text(buildGuide(goal, stack, docs.baseUrl, deps.guidesDir));
+        }
+        catch (err) {
+            return fail(errorMessage(err));
+        }
+    });
+    server.registerTool("verify_webhook_signature", {
+        title: "Verify a Finrock webhook signature",
+        description: "Check whether a captured Finrock webhook body and its x-signature header verify against Finrock's published webhook key. Use it to debug a webhook handler that rejects deliveries.",
+        inputSchema: {
+            raw_body: z.string().describe("The exact raw request body as received, before any JSON parsing"),
+            signature: z.string().describe("The x-signature header value (base64)"),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async ({ raw_body, signature }) => {
+        const r = verifyWebhookSignature(raw_body, signature);
+        return text(r.valid ? "Valid: this body was signed by Finrock." : `Invalid. ${r.reason}`);
+    });
+    server.registerTool("setup_account_access", {
+        title: "Set up Finrock account access securely",
+        description: "Step-by-step setup for the local package's account tools with the Finrock API key and RSA private key stored in the OS keychain (macOS Keychain, Linux Secret Service, Windows DPAPI) rather than in plain MCP config. Use it when the user wants the agent to work with their own Finrock account.",
+        inputSchema: {
+            os: z.enum(SETUP_OS).describe("The user's operating system"),
+            client: z
+                .enum(SETUP_CLIENTS)
+                .default("json-config")
+                .describe("claude-code for the `claude mcp add` CLI; json-config for Claude Desktop, Cursor and other clients with an mcpServers JSON file"),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async ({ os, client }) => text(buildAccountSetup(os, client)));
+    const apiBase = deps.api?.baseUrl ?? deps.apiBaseUrl ?? DEFAULT_API_URL;
+    const getPublic = (path, query) => publicGet(apiBase, withQuery(path, query), deps.fetch);
+    server.registerTool("list_supported_assets", {
+        title: "List supported assets",
+        description: "Finrock's supported coins and tokens with the exact asset name to use in API calls (e.g. USDT_TRX), network, decimals, confirmations and whether a destination tag is needed.",
+        inputSchema: {
+            search: z.string().optional().describe("Filter by name, ticker or network, e.g. 'usdt' or 'tron'"),
+            network: z.enum(["live", "testnet"]).default("live"),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, async ({ search, network }) => {
+        try {
+            const data = await getPublic("/assets");
+            const list = (network === "testnet" ? data.testNetAssets : data.liveNetAssets) ?? [];
+            const q = search?.toLowerCase();
+            const rows = list
+                .filter((a) => !q || ["asset_name", "ticker", "network", "parent_blockchain", "blockchain_type"].some((k) => String(a[k] ?? "").toLowerCase().includes(q)))
+                .map((a) => ({
+                asset_name: a.asset_name,
+                ticker: a.ticker,
+                network: a.network,
+                blockchain: a.parent_blockchain,
+                decimals: a.divisibility,
+                contract_address: a.contract_address || undefined,
+                required_confirmations: a.required_confirmations,
+                needs_address_tag: a.address_tag,
+                price_in_usd: a.price_in_usd,
+            }));
+            return text(rows.length ? JSON.stringify(rows, null, 2) : `No ${network} assets matched "${search}".`);
+        }
+        catch (err) {
+            return fail(`Could not load supported assets: ${errorMessage(err)}`);
+        }
+    });
+    server.registerTool("get_asset_price", {
+        title: "Get a crypto spot price",
+        description: "USD spot price and 24h change from Finrock. Pass a ticker (e.g. 'btc', 'usdt') for every network it trades on, or an asset name (e.g. 'USDT_TRX') for one.",
+        inputSchema: {
+            crypto: z.string().min(1).default("btc").describe("Ticker or asset name"),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, async ({ crypto }) => {
+        try {
+            // /prices ignores query parameters and returns every asset, keyed by lower-case asset name, in USD only.
+            const data = await getPublic("/prices");
+            const q = crypto.toLowerCase();
+            const rows = Object.entries(data?.usd ?? {})
+                .filter(([id, p]) => id === q || p.ticker?.toLowerCase() === q)
+                .map(([id, { sparkline_in_7d: _, ...p }]) => ({ asset: id.toUpperCase(), ...p }));
+            if (!rows.length)
+                return fail(`No price for "${crypto}". Use list_supported_assets for valid tickers and asset names.`);
+            return text(JSON.stringify(rows, null, 2));
+        }
+        catch (err) {
+            return fail(`Could not get the price: ${errorMessage(err)}`);
+        }
+    });
+    if (deps.api)
+        registerApiTools(server, deps.api, deps.apiOptions);
+    server.registerPrompt("integrate_finrock", {
+        title: "Add Finrock crypto payments to this app",
+        description: "Plan and implement a Finrock integration in the current codebase.",
+        argsSchema: {
+            use_case: z.string().optional().describe("What the app needs, e.g. 'checkout for a SaaS plan' or 'user wallet top-ups'"),
+        },
+    }, ({ use_case }) => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: `Add Finrock crypto payments to this application${use_case ? ` for: ${use_case}` : ""}.
+
+1. Inspect the codebase to identify its stack, framework, data layer and where payments belong.
+2. Call list_integration_guides, choose the right goal(s) (almost always including webhooks), and call get_integration_guide for this stack.
+3. Use search_docs/read_doc to confirm exact fields for every endpoint you call.
+4. Implement it following the codebase's conventions: server-side API client, environment variables (FINROCK_API_KEY, FINROCK_PRIVATE_KEY), routes, persistence and an idempotent webhook handler.
+5. List the manual steps I must do in the Finrock dashboard (API user and public key upload, webhook URL, widget ID) and how to test end to end.`,
+                },
+            },
+        ],
+    }));
+    return server;
+}

package/dist/setup.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Step-by-step setup for the local package's account tools, with the API key and private key
+ * kept in the OS keychain (or a secret manager) and read through FINROCK_*_COMMAND. Nothing
+ * here touches credentials: it only returns instructions for the user's own machine.
+ */
+export declare const SETUP_OS: readonly ["macos", "linux", "windows"];
+export type SetupOs = (typeof SETUP_OS)[number];
+export declare const SETUP_CLIENTS: readonly ["claude-code", "json-config"];
+export type SetupClient = (typeof SETUP_CLIENTS)[number];
+export declare function buildAccountSetup(os: SetupOs, client: SetupClient): string;

package/dist/setup.js

@@ -0,0 +1,123 @@
+/**
+ * Step-by-step setup for the local package's account tools, with the API key and private key
+ * kept in the OS keychain (or a secret manager) and read through FINROCK_*_COMMAND. Nothing
+ * here touches credentials: it only returns instructions for the user's own machine.
+ */
+export const SETUP_OS = ["macos", "linux", "windows"];
+export const SETUP_CLIENTS = ["claude-code", "json-config"];
+const KEYGEN = `openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:4096 -out finrock_private.pem
+openssl pkey -in finrock_private.pem -pubout -out finrock_public.pem`;
+/**
+ * PowerShell that decrypts a DPAPI file under %USERPROFILE%\.finrock, passed as -EncodedCommand
+ * so the command needs no quoting in cmd.exe, PowerShell or JSON.
+ */
+function dpapiRead(name) {
+    const script = `[Net.NetworkCredential]::new('', (Get-Content (Join-Path $env:USERPROFILE '.finrock\\${name}') | ConvertTo-SecureString)).Password`;
+    return `powershell -NoProfile -NonInteractive -EncodedCommand ${Buffer.from(script, "utf16le").toString("base64")}`;
+}
+const STEPS = {
+    macos: {
+        label: "macOS (Keychain)",
+        shell: "bash",
+        // `security -w` hex-encodes values containing newlines, so store the PEM as one line with \n escapes.
+        storeKey: `security add-generic-password -U -s finrock-private-key -a finrock -w "$(awk '{printf "%s\\\\n", $0}' finrock_private.pem)"
+rm finrock_private.pem`,
+        storeApiKey: `security add-generic-password -U -s finrock-api-key -a finrock -w`,
+        apiKeyCommand: `/usr/bin/security find-generic-password -s finrock-api-key -w`,
+        privateKeyCommand: `/usr/bin/security find-generic-password -s finrock-private-key -w`,
+        notes: "The first time the server starts, macOS asks whether `security` may read each item. Choose **Always Allow**, or **Allow** to be asked again on every start.",
+    },
+    linux: {
+        label: "Linux (Secret Service: GNOME Keyring or KWallet)",
+        shell: "bash",
+        storeKey: `secret-tool store --label="Finrock private key" service finrock-mcp key private-key < finrock_private.pem
+rm finrock_private.pem`,
+        storeApiKey: `secret-tool store --label="Finrock API key" service finrock-mcp key api-key`,
+        apiKeyCommand: `secret-tool lookup service finrock-mcp key api-key`,
+        privateKeyCommand: `secret-tool lookup service finrock-mcp key private-key`,
+        notes: "`secret-tool` comes with libsecret (`sudo apt install libsecret-tools` or `sudo dnf install libsecret`) and needs an unlocked desktop keyring. On a headless machine without one, keep the key file instead: `chmod 600 finrock_private.pem` and set `FINROCK_PRIVATE_KEY_PATH` to its absolute path.",
+    },
+    windows: {
+        label: "Windows (DPAPI, encrypted to your Windows account)",
+        shell: "powershell",
+        storeKey: `New-Item -ItemType Directory -Force "$env:USERPROFILE\\.finrock" | Out-Null
+Get-Content -Raw finrock_private.pem | ConvertTo-SecureString -AsPlainText -Force | ConvertFrom-SecureString | Set-Content "$env:USERPROFILE\\.finrock\\private-key"
+Remove-Item finrock_private.pem`,
+        storeApiKey: `Read-Host "Finrock API Key UUID" -AsSecureString | ConvertFrom-SecureString | Set-Content "$env:USERPROFILE\\.finrock\\api-key"`,
+        apiKeyCommand: dpapiRead("api-key"),
+        privateKeyCommand: dpapiRead("private-key"),
+        notes: "The files under `%USERPROFILE%\\.finrock` are encrypted with Windows DPAPI and can only be decrypted by your Windows account on this machine. The two read commands are PowerShell passed with `-EncodedCommand` so they need no quoting; each decodes to `[Net.NetworkCredential]::new('', (Get-Content (Join-Path $env:USERPROFILE '.finrock\\<name>') | ConvertTo-SecureString)).Password`. `openssl` ships with Git for Windows (run step 1 in Git Bash if PowerShell can't find it).",
+    },
+};
+const json = (v) => JSON.stringify(v, null, 2);
+/** Single-quote for a POSIX shell; also valid in PowerShell for text without quotes. */
+const sq = (s) => `'${s.replace(/'/g, `'\\''`)}'`;
+function clientConfig(os, client, s) {
+    if (client === "claude-code") {
+        const shell = os === "windows" ? "powershell" : "bash";
+        const nl = os === "windows" ? " `" : " \\";
+        return `\`\`\`${shell}
+claude mcp add finrock --scope user${nl}
+  -e FINROCK_API_KEY_COMMAND=${sq(s.apiKeyCommand)}${nl}
+  -e FINROCK_PRIVATE_KEY_COMMAND=${sq(s.privateKeyCommand)}${nl}
+  -- npx -y @finrock/mcp
+\`\`\``;
+    }
+    const config = {
+        mcpServers: {
+            finrock: {
+                command: "npx",
+                args: ["-y", "@finrock/mcp"],
+                env: { FINROCK_API_KEY_COMMAND: s.apiKeyCommand, FINROCK_PRIVATE_KEY_COMMAND: s.privateKeyCommand },
+            },
+        },
+    };
+    return `Add this to the client's MCP config (for Claude Desktop: Settings, Developer, Edit Config), then restart the client:
+
+\`\`\`json
+${json(config)}
+\`\`\``;
+}
+export function buildAccountSetup(os, client) {
+    const s = STEPS[os];
+    const fence = (code) => `\`\`\`${s.shell}\n${code}\n\`\`\``;
+    return `# Connect a Finrock account, keys in ${s.label}
+
+The account tools run in the local package (\`npx @finrock/mcp\`) on the user's machine, which signs every request there. The hosted server at mcp.finrock.io never receives credentials. With this setup, neither key sits in plain text in the MCP config: the package reads each one from the keychain when it starts and keeps it only in memory.
+
+**Rules for the agent:** never ask the user to paste the private key or the API key into the chat, and never print, log or commit either one. You may run step 1 for the user if you have a terminal, but step 3 prompts for a secret, so the user must run it in their own terminal (in Claude Code, prefix it with \`!\`).
+
+## 1. Generate the key pair
+
+Run this in a private directory. Keep \`finrock_public.pem\`; the private key goes into the keychain in step 2.
+
+${fence(KEYGEN)}
+
+## 2. Store the private key and delete the file
+
+${fence(s.storeKey)}
+
+## 3. Create the API user and store its key
+
+In the Finrock Dashboard, open **API Users**, create a dedicated user for the agent, upload \`finrock_public.pem\`, restrict it to your IP, and copy the **API Key UUID** (shown only once). Then run this and paste the UUID at the prompt, not in the chat:
+
+${fence(s.storeApiKey)}
+
+## 4. Point the MCP client at the keychain
+
+${clientConfig(os, client, s)}
+
+Add \`FINROCK_READ_ONLY=true\` to expose read tools only, or \`FINROCK_ENABLE_SENSITIVE_TOOLS=true\` to also allow tools that move funds. Leave both out for read and create tools.
+
+## 5. Check it
+
+Restart the client. The server's log should say \`finrock-mcp: account tools on\`; ask the agent to call \`list_wallets\`. On HTTP 401, check that the uploaded public key matches the stored private key and that the machine's clock is correct.
+
+## Notes
+
+- ${s.notes}
+- With a password manager CLI, set the same variables to its read command instead, for example \`FINROCK_PRIVATE_KEY_COMMAND="op read op://Private/Finrock/private_key"\` for 1Password.
+- To rotate, generate a new pair, upload the new public key, and repeat steps 2 and 3 (they overwrite the stored items).
+- Claude on the web and mobile can't run local servers; use Claude Code, Claude Desktop or another client that supports stdio servers.
+- In the user's own application, store the same kind of credentials in that app's server-side secret store (environment variables, a cloud secret manager or KMS), never in browser code or the repository.`;
+}

package/dist/stdio.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/stdio.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+/**
+ * Local entry point: `npx @finrock/mcp` speaks MCP over stdio. With FINROCK_API_KEY and
+ * FINROCK_PRIVATE_KEY (or FINROCK_PRIVATE_KEY_PATH, or *_COMMAND variants that read them from a
+ * keychain) set, it also exposes account tools
+ * that sign requests on this machine; the key never leaves it.
+ */
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { DocsClient } from "./docs.js";
+import { FinrockClient } from "./api/client.js";
+import { apiToolMode, describeMode } from "./api/tools.js";
+import { createServer } from "./server.js";
+let api;
+try {
+    api = FinrockClient.fromEnv();
+}
+catch (err) {
+    console.error(`finrock-mcp: account tools disabled: ${err.message}`);
+}
+const apiOptions = apiToolMode();
+console.error(api ? `finrock-mcp: account tools on, ${describeMode(apiOptions)}` : "finrock-mcp: docs and guides only (no FINROCK_API_KEY)");
+const server = createServer({
+    docs: new DocsClient({ baseUrl: process.env.FINROCK_DOCS_URL }),
+    api,
+    apiOptions,
+    apiBaseUrl: process.env.FINROCK_API_URL,
+});
+await server.connect(new StdioServerTransport());

package/dist/webhook.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Finrock's public key for webhook signatures, as published at
+ * https://apidocs.finrock.io/guides/webhooks. Each delivery carries an
+ * `x-signature` header: base64 RSA-SHA512 (PKCS#1 v1.5) over the raw body.
+ */
+export declare const FINROCK_WEBHOOK_PUBLIC_KEY = "-----BEGIN PUBLIC KEY-----\nMIIBnzANBgkqhkiG9w0BAQEFAAOCAYwAMIIBhwKCAX4Aq1O7ztZxzkgDCFlUnHvs\nEBffqmlng9uEmNMCGbCpxB7991WiR4TRRVaTUrLxIzPWl79xT6R2Xzba1GqN2bin\nsPBU/cmHEF5v1bDopZ7oHnU43tnlpH1kSOjtvTBORf6v6+9xh87OYtg4wXuwVzCq\nykXDRPIIzgPCSpA7l7DtPqhOpm0OVpUnVJQ5DgnsMfJMPkrrPTjRkpFZ1RbtqoLW\nUI+bMWZAAKLEsh4Q+SRO7xiHj26gToD+/ZrEAbC/SOcy2ChDfpQ39XN/bYTu52j8\nndAS/R4qnffLGpmTcxr19UC+BPs5Wb5kx2ZJsGPQPpoPHaTBC1n3YwQlksgeHEvX\nZBsDoAvIXpGfBjUPzd8bvz5vyxbLYA4lSqp/Fw48NYgRRgfOWjmtqVI07jnXKxU2\nkcQc7QkoFVDYw45DS14tkrsCOJjMF0qux2dL9Gr1z/Xdaod+SyeRqsTDYhbzaD+v\nUkO6chtsIHmQwAF8jYajAR7uKROX+6f8ZIwYDco3AgMBAAE=\n-----END PUBLIC KEY-----";
+export interface WebhookCheck {
+    valid: boolean;
+    reason?: string;
+}
+export declare function verifyWebhookSignature(rawBody: string, signatureB64: string, publicKeyPem?: string): WebhookCheck;

package/dist/webhook.js

@@ -0,0 +1,39 @@
+import { createPublicKey, verify, constants } from "node:crypto";
+/**
+ * Finrock's public key for webhook signatures, as published at
+ * https://apidocs.finrock.io/guides/webhooks. Each delivery carries an
+ * `x-signature` header: base64 RSA-SHA512 (PKCS#1 v1.5) over the raw body.
+ */
+export const FINROCK_WEBHOOK_PUBLIC_KEY = `-----BEGIN PUBLIC KEY-----
+MIIBnzANBgkqhkiG9w0BAQEFAAOCAYwAMIIBhwKCAX4Aq1O7ztZxzkgDCFlUnHvs
+EBffqmlng9uEmNMCGbCpxB7991WiR4TRRVaTUrLxIzPWl79xT6R2Xzba1GqN2bin
+sPBU/cmHEF5v1bDopZ7oHnU43tnlpH1kSOjtvTBORf6v6+9xh87OYtg4wXuwVzCq
+ykXDRPIIzgPCSpA7l7DtPqhOpm0OVpUnVJQ5DgnsMfJMPkrrPTjRkpFZ1RbtqoLW
+UI+bMWZAAKLEsh4Q+SRO7xiHj26gToD+/ZrEAbC/SOcy2ChDfpQ39XN/bYTu52j8
+ndAS/R4qnffLGpmTcxr19UC+BPs5Wb5kx2ZJsGPQPpoPHaTBC1n3YwQlksgeHEvX
+ZBsDoAvIXpGfBjUPzd8bvz5vyxbLYA4lSqp/Fw48NYgRRgfOWjmtqVI07jnXKxU2
+kcQc7QkoFVDYw45DS14tkrsCOJjMF0qux2dL9Gr1z/Xdaod+SyeRqsTDYhbzaD+v
+UkO6chtsIHmQwAF8jYajAR7uKROX+6f8ZIwYDco3AgMBAAE=
+-----END PUBLIC KEY-----`;
+export function verifyWebhookSignature(rawBody, signatureB64, publicKeyPem = FINROCK_WEBHOOK_PUBLIC_KEY) {
+    const sig = signatureB64.trim();
+    if (!sig)
+        return { valid: false, reason: "The x-signature value is empty." };
+    if (!/^[A-Za-z0-9+/]+=*$/.test(sig)) {
+        return { valid: false, reason: "The x-signature value is not base64." };
+    }
+    let key;
+    try {
+        key = createPublicKey(publicKeyPem);
+    }
+    catch (err) {
+        return { valid: false, reason: `Could not load the public key: ${err.message}` };
+    }
+    const ok = verify("sha512", Buffer.from(rawBody, "utf8"), { key, padding: constants.RSA_PKCS1_PADDING }, Buffer.from(sig, "base64"));
+    if (ok)
+        return { valid: true };
+    return {
+        valid: false,
+        reason: "Signature does not match this body. Verify against the exact raw bytes Finrock sent, captured before any JSON parsing (for example express.raw(), not express.json()), and pass the x-signature header unchanged.",
+    };
+}

package/guides/_client/nextjs.md

@@ -0,0 +1,57 @@
+### Finrock API client (`lib/finrock.ts`)
+
+No SDK needed: this signs each request with Node's built-in `crypto`. Use it only from
+Route Handlers, Server Actions or Server Components on the Node.js runtime.
+
+```ts
+// lib/finrock.ts
+import "server-only"; // npm i server-only — fails the build if imported client-side
+import { createHash, createSign, randomUUID } from "node:crypto";
+
+const API_BASE = "https://api.finrock.io";
+const API_KEY = process.env.FINROCK_API_KEY!; // API Key UUID from Finrock Dashboard → API Users
+// PEM of the RSA-4096 private key whose public half you uploaded. Env vars often
+// store newlines as "\n", so restore them.
+const PRIVATE_KEY = process.env.FINROCK_PRIVATE_KEY!.replace(/\\n/g, "\n");
+
+const b64url = (b: Buffer | string) => Buffer.from(b).toString("base64url");
+
+/** A fresh RS256 JWT for one request. Finrock rejects reused nonces and exp > iat + 30s. */
+function signJwt(uri: string, rawBody: string): string {
+  const now = Math.floor(Date.now() / 1000);
+  const header = { alg: "RS256", typ: "JWT" };
+  const payload = {
+    uri, // request path, e.g. /dac/v1/invoice
+    nonce: randomUUID(),
+    iat: now,
+    exp: now + 25,
+    sub: API_KEY,
+    bodyHash: createHash("sha256").update(rawBody).digest("hex"),
+  };
+  const input = `${b64url(JSON.stringify(header))}.${b64url(JSON.stringify(payload))}`;
+  const signature = createSign("RSA-SHA256").update(input).sign(PRIVATE_KEY);
+  return `${input}.${b64url(signature)}`;
+}
+
+export async function finrock<T = any>(
+  method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE",
+  path: string,
+  body?: unknown,
+): Promise<T> {
+  const rawBody = body === undefined ? "" : JSON.stringify(body);
+  const res = await fetch(API_BASE + path, {
+    method,
+    headers: {
+      authorization: `Bearer ${signJwt(path, rawBody)}`,
+      "x-api-key": API_KEY,
+      accept: "application/json",
+      ...(rawBody ? { "content-type": "application/json" } : {}),
+    },
+    body: rawBody || undefined,
+    cache: "no-store",
+  });
+  const text = await res.text();
+  if (!res.ok) throw new Error(`Finrock ${method} ${path} -> HTTP ${res.status}: ${text}`);
+  return (text ? JSON.parse(text) : null) as T;
+}
+```