@finrock/mcp 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) Finrock. All rights reserved.
+
+Use of this software, including the @finrock/mcp package and the hosted server at
+https://mcp.finrock.io, is subject to the Finrock Terms of Service:
+https://finrock.io/terms-of-service
+
+See also the Finrock Privacy Policy: https://finrock.io/privacy-policy

package/README.md

@@ -1,3 +1,215 @@
-# Temporary Holding Version
+# Finrock MCP server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Finrock-0098FF?logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=finrock&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.finrock.io%22%7D)
+[![Install in VS Code Insiders](https://img.shields.io/badge/VS_Code_Insiders-Install_Finrock-24bfa5?logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=finrock&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.finrock.io%22%7D&quality=insiders)
+[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.png)](https://cursor.com/en/install-mcp?name=finrock&config=eyJ1cmwiOiJodHRwczovL21jcC5maW5yb2NrLmlvIn0=)
+
+An [MCP](https://modelcontextprotocol.io) server that lets AI coding agents (Claude, Codex,
+Cursor, VS Code Copilot and others) add [Finrock](https://finrock.io) crypto payments to any
+application.
+
+The hosted server at **`https://mcp.finrock.io`** (the older `https://mcp.finrock.io/mcp` also works) needs no API key. It reads the live docs at
+[apidocs.finrock.io](https://apidocs.finrock.io) and returns tested integration code, so an agent
+can go from "accept USDT at checkout" to a working, secure implementation in your codebase. It
+never touches anyone's Finrock account: API calls are signed with your private key, which stays
+on your servers.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `list_integration_guides` | The ready-made recipes and supported stacks |
+| `get_integration_guide` | Steps plus code for a goal in a stack (`node`, `nextjs`, `python`, `php`) |
+| `search_docs` | Full-text search over the live Finrock docs |
+| `read_doc` | One docs page as Markdown, with request and response examples |
+| `list_docs` | Every docs page, grouped by section |
+| `verify_webhook_signature` | Check a captured webhook body and `x-signature` against Finrock's key |
+| `setup_account_access` | Walk through connecting a Finrock account with keys kept in the OS keychain |
+| `list_supported_assets` | Supported coins and tokens with the exact asset name to use in API calls |
+| `get_asset_price` | Spot price of a crypto in a fiat currency |
+
+There is also a prompt, `integrate_finrock`, that walks an agent through the whole integration.
+
+Integration goals: `accept-payments` (hosted invoices), `payment-widget`, `deposit-addresses`,
+`webhooks`, `withdrawals` and `authentication`.
+
+## Connect your agent
+
+**Claude Code**
+
+```bash
+claude mcp add --transport http finrock https://mcp.finrock.io
+```
+
+Or install it as a plugin, which keeps the server up to date:
+
+```bash
+claude plugin marketplace add gofinrock/mcp
+claude plugin install finrock@finrock
+```
+
+**Claude.ai / Claude Desktop**: Settings → Connectors → Add custom connector →
+`https://mcp.finrock.io`.
+
+**Cursor** (`~/.cursor/mcp.json` or `.cursor/mcp.json`)
+
+```json
+{ "mcpServers": { "finrock": { "url": "https://mcp.finrock.io" } } }
+```
+
+**VS Code** (`.vscode/mcp.json`)
+
+```json
+{ "servers": { "finrock": { "type": "http", "url": "https://mcp.finrock.io" } } }
+```
+
+**Codex** (`~/.codex/config.toml`)
+
+```toml
+[mcp_servers.finrock]
+url = "https://mcp.finrock.io"
+```
+
+Any client that only supports stdio can run the same server locally once the package is
+published: `npx -y @finrock/mcp`.
+
+Then ask your agent something like: *"Use Finrock to add a crypto checkout to this app."*
+
+## Manage a Finrock account (local package)
+
+The hosted server never sees anyone's credentials. To let an agent work with a real Finrock
+account (create invoices and deposit addresses, check balances and transactions, and
+optionally send payouts), run the package locally with your own keys. Requests are signed on
+your machine and the private key never leaves it.
+
+```bash
+claude mcp add finrock \
+  -e FINROCK_API_KEY=<API Key UUID> \
+  -e FINROCK_PRIVATE_KEY_PATH=/path/to/finrock_private.pem \
+  -- npx -y @finrock/mcp
+```
+
+Or in any client's JSON config:
+
+```json
+{
+  "mcpServers": {
+    "finrock": {
+      "command": "npx",
+      "args": ["-y", "@finrock/mcp"],
+      "env": {
+        "FINROCK_API_KEY": "<API Key UUID>",
+        "FINROCK_PRIVATE_KEY_PATH": "/path/to/finrock_private.pem"
+      }
+    }
+  }
+}
+```
+
+### Keep the keys in your keychain
+
+Instead of putting the keys in the config, `FINROCK_API_KEY_COMMAND` and
+`FINROCK_PRIVATE_KEY_COMMAND` can name a command whose output is the secret: the macOS Keychain,
+Linux Secret Service, a Windows DPAPI-encrypted file, or a password manager CLI such as
+1Password's `op read`. The package runs each command once at startup and keeps the result only in
+memory. Ask your agent to *"set up my Finrock account"* and it calls `setup_account_access`, which
+gives the exact commands for your OS and client. For example, on macOS:
+
+```bash
+claude mcp add finrock --scope user \
+  -e FINROCK_API_KEY_COMMAND='/usr/bin/security find-generic-password -s finrock-api-key -w' \
+  -e FINROCK_PRIVATE_KEY_COMMAND='/usr/bin/security find-generic-password -s finrock-private-key -w' \
+  -- npx -y @finrock/mcp
+```
+
+Never paste either key into a chat with an agent.
+
+Until `@finrock/mcp` is published to npm, run it from a clone instead: `npm ci && npm run build`,
+then use `node /path/to/mcp/dist/stdio.js` as the command.
+
+Create the API user and key pair as described in the `authentication` guide (or the
+[Quick Start](https://apidocs.finrock.io/quickstart)). Use a dedicated API user for the agent and
+restrict it to your IP.
+
+### Access levels
+
+| Level | Tools | Enabled |
+|---|---|---|
+| Read | `list_wallets`, `list_addresses`, `validate_address`, `list_invoices`, `list_transactions`, `estimate_fee`, `get_network_fee_rates`, `list_gas_tanks`, `get_gas_tank_balance`, `get_prepaid_fee`, `list_exchange_accounts`, `get_exchange_balance`, `get_aml_status`, `list_frozen_addresses` | Always |
+| Create | `create_invoice`, `create_wallet`, `create_address`, `update_address`, `generate_xrp_destination_tag` | Unless `FINROCK_READ_ONLY=true` |
+| Sensitive (moves funds or changes security) | `create_transaction`, `bump_fee`, `sweep_address`, `update_wallet`, `configure_aml`, `unfreeze_address`, `stake_trx`, `unstake_trx`, `release_unstaked_trx` | Only with `FINROCK_ENABLE_SENSITIVE_TOOLS=true` |
+
+Disabled tools are not shown to the agent at all. `create_transaction` requires a
+`sequence_id`, so a retried call returns the original transaction instead of paying twice.
+
+| Variable | Purpose |
+|---|---|
+| `FINROCK_API_KEY` | API Key UUID of the API user |
+| `FINROCK_PRIVATE_KEY_PATH` or `FINROCK_PRIVATE_KEY` | RSA private key (path, or PEM text with `\n` escapes allowed) |
+| `FINROCK_API_KEY_COMMAND` | Command that prints the API Key UUID, used when `FINROCK_API_KEY` is unset |
+| `FINROCK_PRIVATE_KEY_COMMAND` | Command that prints the PEM (`\n` escapes allowed), used when neither of the above is set |
+| `FINROCK_READ_ONLY` | `true` to expose read tools only |
+| `FINROCK_ENABLE_SENSITIVE_TOOLS` | `true` to expose tools that move funds or change AML settings |
+| `FINROCK_API_URL` | Override the API base URL (default `https://api.finrock.io`) |
+
+## Development
+
+```bash
+npm ci
+npm test          # unit tests plus an end-to-end MCP client test over HTTP
+npm run typecheck
+npm run dev       # HTTP server on :3000 in watch mode
+```
+
+Try it interactively with the MCP Inspector:
+
+```bash
+npx @modelcontextprotocol/inspector   # then connect to http://localhost:3000
+```
+
+Integration guides are plain Markdown in [`guides/`](guides): `overview.md` per goal (with
+frontmatter), one file per stack, and the request-signing client per stack in `guides/_client/`.
+Edit them without touching TypeScript; tests check that every goal renders for every stack.
+
+## Directory listings
+
+The repo carries the metadata each directory reads:
+
+| File | Used by |
+|---|---|
+| `server.json` | [Official MCP Registry](https://registry.modelcontextprotocol.io) as `io.finrock/mcp`, which feeds the VS Code / GitHub MCP gallery and other downstream registries |
+| `package.json` `mcpName` | Proves to the MCP Registry that `@finrock/mcp` on npm belongs to `io.finrock/mcp` |
+| `.claude-plugin/marketplace.json`, `plugins/finrock/` | Claude Code plugin marketplace (`claude plugin marketplace add gofinrock/mcp`) and the Claude plugin directory |
+| `glama.json` | [Glama](https://glama.ai/mcp/servers) maintainer claim |
+
+`npm test` checks that the name and version in `server.json`, `package.json`, the plugin and the
+server agree, so bump all of them together.
+
+**Publishing a release to the MCP Registry.** The `io.finrock/` namespace is proven with a DNS TXT
+record on `finrock.io` (one-time setup):
+
+```bash
+openssl genpkey -algorithm Ed25519 -out mcp-registry-key.pem     # keep this out of the repo
+PUBLIC_KEY="$(openssl pkey -in mcp-registry-key.pem -pubout -outform DER | tail -c 32 | base64)"
+echo "finrock.io. IN TXT \"v=MCPv1; k=ed25519; p=${PUBLIC_KEY}\""  # add this record to finrock.io
+```
+
+**Publishing to npm.** Bump the version everywhere (see above), commit to `main`, then push a
+matching tag: `git tag v0.1.1 && git push origin v0.1.1`. The `Release` workflow checks the tag
+against `package.json`, runs the tests and publishes `@finrock/mcp` with npm trusted publishing, so
+no npm token is stored in the repo. One-time setup on npmjs.com: package **Settings → Trusted
+Publisher → GitHub Actions**, organization `gofinrock`, repository `mcp`, workflow `release.yml`.
+
+Then for each release (after the npm publish, because the registry checks that the npm version
+exists):
+
+```bash
+brew install mcp-publisher        # or download it from github.com/modelcontextprotocol/registry/releases
+PRIVATE_KEY="$(openssl pkey -in mcp-registry-key.pem -noout -text | grep -A3 "priv:" | tail -n +2 | tr -d ' :\n')"
+mcp-publisher login dns --domain finrock.io --private-key "${PRIVATE_KEY}"
+mcp-publisher publish
+```
+
+## Roadmap
+
+- npm release of `@finrock/mcp`.

package/dist/api/client.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Signed client for the Finrock REST API. Each request carries the API key and a
+ * fresh RS256 JWT (unique nonce, exp <= iat + 30s, SHA-256 of the exact body).
+ * Credentials only ever exist in the process that runs this client, i.e. on the
+ * developer's own machine; the hosted server never constructs one.
+ */
+export declare const DEFAULT_API_URL = "https://api.finrock.io";
+export interface FinrockClientOptions {
+    apiKey: string;
+    /** PEM text of the RSA private key whose public half is uploaded to Finrock. */
+    privateKey: string;
+    baseUrl?: string;
+    fetch?: typeof fetch;
+    timeoutMs?: number;
+}
+export type Query = Record<string, string | number | boolean | undefined>;
+export declare class FinrockApiError extends Error {
+    readonly status: number;
+    readonly method: string;
+    readonly path: string;
+    readonly body: string;
+    readonly retryAfter?: string | undefined;
+    constructor(status: number, method: string, path: string, body: string, retryAfter?: string | undefined);
+}
+export declare class FinrockClient {
+    readonly baseUrl: string;
+    private readonly apiKey;
+    private readonly key;
+    private readonly fetchImpl;
+    private readonly timeoutMs;
+    constructor(opts: FinrockClientOptions);
+    /**
+     * Build a client from FINROCK_API_KEY plus FINROCK_PRIVATE_KEY (PEM, `\n` escapes
+     * allowed) or FINROCK_PRIVATE_KEY_PATH. Either secret can instead come from the stdout of
+     * FINROCK_API_KEY_COMMAND / FINROCK_PRIVATE_KEY_COMMAND, so it can live in the OS keychain
+     * or a secret manager rather than in the client's config. Returns undefined when no key is configured.
+     */
+    static fromEnv(env?: NodeJS.ProcessEnv): FinrockClient | undefined;
+    get<T = unknown>(path: string, query?: Query): Promise<T>;
+    post<T = unknown>(path: string, body?: unknown): Promise<T>;
+    patch<T = unknown>(path: string, body: unknown): Promise<T>;
+    /** Unauthenticated GET for Finrock's public endpoints (assets, prices). */
+    getPublic<T = unknown>(path: string, query?: Query): Promise<T>;
+    request<T>(method: string, pathWithQuery: string, body?: unknown): Promise<T>;
+    signJwt(uri: string, rawBody: string, now?: number): string;
+}
+export declare function publicGet<T>(baseUrl: string, pathWithQuery: string, fetchImpl?: typeof fetch, timeoutMs?: number): Promise<T>;
+export declare function withQuery(path: string, query?: Query): string;
+/** An error's message plus its cause: Node's fetch reports DNS, TLS and proxy failures as a bare "fetch failed". */
+export declare function errorMessage(err: unknown): string;

package/dist/api/client.js

@@ -0,0 +1,172 @@
+import { createHash, createPrivateKey, randomUUID, sign } from "node:crypto";
+import { execSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+/**
+ * Signed client for the Finrock REST API. Each request carries the API key and a
+ * fresh RS256 JWT (unique nonce, exp <= iat + 30s, SHA-256 of the exact body).
+ * Credentials only ever exist in the process that runs this client, i.e. on the
+ * developer's own machine; the hosted server never constructs one.
+ */
+export const DEFAULT_API_URL = "https://api.finrock.io";
+export class FinrockApiError extends Error {
+    status;
+    method;
+    path;
+    body;
+    retryAfter;
+    constructor(status, method, path, body, retryAfter) {
+        super(`Finrock ${method} ${path} failed with HTTP ${status}${body ? `: ${body}` : ""}`);
+        this.status = status;
+        this.method = method;
+        this.path = path;
+        this.body = body;
+        this.retryAfter = retryAfter;
+    }
+}
+export class FinrockClient {
+    baseUrl;
+    apiKey;
+    key;
+    fetchImpl;
+    timeoutMs;
+    constructor(opts) {
+        if (!opts.apiKey)
+            throw new Error("A Finrock API key is required");
+        this.apiKey = opts.apiKey;
+        this.key = createPrivateKey(opts.privateKey);
+        if (this.key.asymmetricKeyType !== "rsa")
+            throw new Error("The Finrock private key must be an RSA key");
+        this.baseUrl = (opts.baseUrl ?? DEFAULT_API_URL).replace(/\/+$/, "");
+        this.fetchImpl = opts.fetch ?? fetch;
+        this.timeoutMs = opts.timeoutMs ?? 30_000;
+    }
+    /**
+     * Build a client from FINROCK_API_KEY plus FINROCK_PRIVATE_KEY (PEM, `\n` escapes
+     * allowed) or FINROCK_PRIVATE_KEY_PATH. Either secret can instead come from the stdout of
+     * FINROCK_API_KEY_COMMAND / FINROCK_PRIVATE_KEY_COMMAND, so it can live in the OS keychain
+     * or a secret manager rather than in the client's config. Returns undefined when no key is configured.
+     */
+    static fromEnv(env = process.env) {
+        const apiKey = (env.FINROCK_API_KEY || secretFromCommand("FINROCK_API_KEY_COMMAND", env))?.trim();
+        if (!apiKey)
+            return undefined;
+        let pem = env.FINROCK_PRIVATE_KEY;
+        if (!pem && env.FINROCK_PRIVATE_KEY_PATH)
+            pem = readFileSync(env.FINROCK_PRIVATE_KEY_PATH, "utf8");
+        if (!pem)
+            pem = secretFromCommand("FINROCK_PRIVATE_KEY_COMMAND", env);
+        if (!pem) {
+            throw new Error("A Finrock API key is configured but no private key: set FINROCK_PRIVATE_KEY, FINROCK_PRIVATE_KEY_PATH or FINROCK_PRIVATE_KEY_COMMAND");
+        }
+        return new FinrockClient({ apiKey, privateKey: pem.replace(/\\n/g, "\n"), baseUrl: env.FINROCK_API_URL });
+    }
+    get(path, query) {
+        return this.request("GET", withQuery(path, query));
+    }
+    post(path, body = {}) {
+        return this.request("POST", path, body);
+    }
+    patch(path, body) {
+        return this.request("PATCH", path, body);
+    }
+    /** Unauthenticated GET for Finrock's public endpoints (assets, prices). */
+    async getPublic(path, query) {
+        return publicGet(this.baseUrl, withQuery(path, query), this.fetchImpl, this.timeoutMs);
+    }
+    async request(method, pathWithQuery, body) {
+        // Serialise once: the bytes hashed into the JWT must be the bytes sent.
+        const raw = body === undefined ? "" : JSON.stringify(body);
+        const headers = {
+            authorization: `Bearer ${this.signJwt(pathWithQuery, raw)}`,
+            "x-api-key": this.apiKey,
+            accept: "application/json",
+        };
+        if (raw)
+            headers["content-type"] = "application/json";
+        const res = await this.fetchImpl(this.baseUrl + pathWithQuery, {
+            method,
+            headers,
+            body: raw || undefined,
+            signal: AbortSignal.timeout(this.timeoutMs),
+        });
+        return parseResponse(res, method, pathWithQuery);
+    }
+    signJwt(uri, rawBody, now = Math.floor(Date.now() / 1000)) {
+        const header = { alg: "RS256", typ: "JWT" };
+        const bodyHash = createHash("sha256").update(rawBody).digest("hex");
+        const payload = {
+            uri,
+            nonce: randomUUID(),
+            iat: now,
+            exp: now + 25,
+            sub: this.apiKey,
+            bodyHash,
+            // api.finrock.io currently reads the lower-case claim; send both so either spelling verifies.
+            bodyhash: bodyHash,
+        };
+        const input = `${b64url(JSON.stringify(header))}.${b64url(JSON.stringify(payload))}`;
+        return `${input}.${b64url(sign("sha256", Buffer.from(input), this.key))}`;
+    }
+}
+export async function publicGet(baseUrl, pathWithQuery, fetchImpl = fetch, timeoutMs = 30_000) {
+    const res = await fetchImpl(baseUrl.replace(/\/+$/, "") + pathWithQuery, {
+        headers: { accept: "application/json" },
+        signal: AbortSignal.timeout(timeoutMs),
+    });
+    return parseResponse(res, "GET", pathWithQuery);
+}
+async function parseResponse(res, method, path) {
+    const text = await res.text();
+    if (!res.ok) {
+        const retry = res.headers.get("x-rate-limit-reset") ?? res.headers.get("retry-after") ?? undefined;
+        throw new FinrockApiError(res.status, method, path, text.slice(0, 2000), retry);
+    }
+    if (!text)
+        return null;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}
+export function withQuery(path, query) {
+    if (!query)
+        return path;
+    const params = new URLSearchParams();
+    for (const [k, v] of Object.entries(query))
+        if (v !== undefined && v !== "")
+            params.set(k, String(v));
+    const qs = params.toString();
+    return qs ? `${path}?${qs}` : path;
+}
+/** An error's message plus its cause: Node's fetch reports DNS, TLS and proxy failures as a bare "fetch failed". */
+export function errorMessage(err) {
+    const msg = err.message;
+    const cause = err.cause;
+    return cause?.message ? `${msg} (${cause.code ? `${cause.code}: ` : ""}${cause.message})` : msg;
+}
+const b64url = (b) => Buffer.from(b).toString("base64url");
+/**
+ * Run the shell command in env[name] and return its trimmed stdout. Its stdout is never
+ * logged (stdio MCP uses this process's stdout); stderr passes through so keychain or
+ * secret-manager prompts and errors stay visible in the client's MCP log.
+ */
+function secretFromCommand(name, env) {
+    const cmd = env[name]?.trim();
+    if (!cmd)
+        return undefined;
+    let out;
+    try {
+        out = execSync(cmd, { encoding: "utf8", env, stdio: ["ignore", "pipe", "inherit"], timeout: 60_000 });
+    }
+    catch (err) {
+        const e = err;
+        const why = e.signal ? `was stopped (${e.signal})` : `exited with status ${e.status ?? "unknown"}`;
+        throw new Error(`${name} ${why}`);
+    }
+    const value = out.trim();
+    if (!value)
+        throw new Error(`${name} printed nothing`);
+    return value;
+}

package/dist/api/tools.d.ts

@@ -0,0 +1,17 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type FinrockClient } from "./client.js";
+/**
+ * Account tools, registered only when the server runs with the user's own
+ * credentials (the local stdio package). Three tiers:
+ *   read       always on
+ *   write      creates records that move no money (invoices, wallets, addresses); off with FINROCK_READ_ONLY
+ *   sensitive  moves funds or changes security settings; on only with FINROCK_ENABLE_SENSITIVE_TOOLS
+ */
+export type Tier = "read" | "write" | "sensitive";
+export interface ApiToolOptions {
+    readOnly?: boolean;
+    enableSensitive?: boolean;
+}
+export declare function apiToolMode(env?: NodeJS.ProcessEnv): ApiToolOptions;
+export declare function describeMode(opts: ApiToolOptions): string;
+export declare function registerApiTools(server: McpServer, api: FinrockClient, opts?: ApiToolOptions): string[];