@coinvello/mcp 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,197 @@
-# Temporary Holding Version
+# @coinvello/mcp
 
-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.
+Model Context Protocol server for the [CoinVello](https://coinvello.com) API, the non-custodial crypto
+payment processor (no KYC, merchant keeps the keys, fees as prepaid credits, 11 networks).
+
+Give Claude, Cursor, Windsurf, ChatGPT or any MCP client the ability to create checkout sessions,
+inspect invoices and payments, register webhooks, verify webhook signatures, manage credits and
+simulate test payments while it writes your integration.
+
+```bash
+npx -y https://coinvello.com/downloads/sdk/coinvello-mcp-0.1.0.tgz            # stdio (what every desktop client uses)
+npx -y https://coinvello.com/downloads/sdk/coinvello-mcp-0.1.0.tgz --http 3333  # Streamable HTTP on http://127.0.0.1:3333/mcp
+```
+
+Not on the npm registry yet: the package is hosted on coinvello.com (checksums in https://coinvello.com/downloads/SHA256SUMS).
+
+```bash
+# from a checkout of this repo instead
+npm install && npm run build && node dist/index.js
+```
+
+## Configuration
+
+| Variable | Required | Meaning |
+|----------|----------|---------|
+| `COINVELLO_API_KEY` | yes | `cv_test_...` from https://coinvello.com/app/settings.php (Settings -> API keys). Any `cv_test_` string works against the local mock. |
+| `COINVELLO_API_BASE` | no | Default `https://api.coinvello.com/v1`. Use `http://localhost:4242/v1` for the reference mock server. |
+| `COINVELLO_ALLOW_LIVE` | no | The server **refuses to start with a `cv_live_` key** unless this is `1`. Agents should develop against test mode. |
+| `COINVELLO_API_VERSION` | no | Pins `CoinVello-Version` (default: account version, currently `2026-10-01`). |
+
+## Client setup
+
+### Claude Desktop
+
+`claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/`, Windows: `%APPDATA%\Claude\`):
+
+```json
+{
+  "mcpServers": {
+    "coinvello": {
+      "command": "npx",
+      "args": ["-y", "https://coinvello.com/downloads/sdk/coinvello-mcp-0.1.0.tgz"],
+      "env": { "COINVELLO_API_KEY": "cv_test_..." }
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add coinvello -e COINVELLO_API_KEY=cv_test_... -- npx -y https://coinvello.com/downloads/sdk/coinvello-mcp-0.1.0.tgz
+```
+
+or in `.mcp.json` at the project root (shared with the team, key via env):
+
+```json
+{
+  "mcpServers": {
+    "coinvello": {
+      "command": "npx",
+      "args": ["-y", "https://coinvello.com/downloads/sdk/coinvello-mcp-0.1.0.tgz"],
+      "env": { "COINVELLO_API_KEY": "${COINVELLO_API_KEY}" }
+    }
+  }
+}
+```
+
+### Cursor
+
+`.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):
+
+```json
+{
+  "mcpServers": {
+    "coinvello": {
+      "command": "npx",
+      "args": ["-y", "https://coinvello.com/downloads/sdk/coinvello-mcp-0.1.0.tgz"],
+      "env": { "COINVELLO_API_KEY": "cv_test_..." }
+    }
+  }
+}
+```
+
+### Windsurf
+
+`~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "coinvello": {
+      "command": "npx",
+      "args": ["-y", "https://coinvello.com/downloads/sdk/coinvello-mcp-0.1.0.tgz"],
+      "env": { "COINVELLO_API_KEY": "cv_test_..." }
+    }
+  }
+}
+```
+
+### VS Code (Copilot agent mode)
+
+`.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "coinvello": { "type": "stdio", "command": "npx", "args": ["-y", "https://coinvello.com/downloads/sdk/coinvello-mcp-0.1.0.tgz"], "env": { "COINVELLO_API_KEY": "cv_test_..." } }
+  }
+}
+```
+
+### Remote / HTTP clients (ChatGPT connectors, hosted agents)
+
+Run `coinvello-mcp --http 3333` behind your own HTTPS reverse proxy and point the client at
+`https://your-host/mcp`. The HTTP mode is stateless (one server instance per request) and binds to
+`127.0.0.1` by default (`MCP_HTTP_HOST=0.0.0.0` to change). It uses the key from the environment,
+so put it behind authentication: it is meant for your own agents, not the public.
+
+## Tools
+
+| Tool | Does |
+|------|------|
+| `create_checkout_session` | `POST /checkout-sessions`: hosted payment page; returns `url` to redirect to and `invoice_id` |
+| `get_invoice` | `GET /invoices/{id}` (or `GET /checkout-sessions/{cs_id}?expand=invoice`) |
+| `list_invoices` | `GET /invoices` with status / order_id / email filters |
+| `list_payments` | `GET /payments` with invoice_id / status / chain / tx_hash filters |
+| `create_wallet` | `POST /wallets` (xpub for BTC, address for EVM/Solana/Tron). Refuses xprv locally. |
+| `list_wallets` | `GET /wallets` |
+| `create_webhook` | `POST /webhooks`; returns the `whsec_` secret once |
+| `verify_webhook_signature` | Local HMAC check of a `CoinVello-Signature` header against a raw body (no API call) |
+| `get_credits_balance` | `GET /credits/balance` |
+| `list_credit_bundles` | `GET /credits/bundles` |
+| `create_credit_purchase` | `POST /credits/purchases`; returns payment options + `checkout_url` |
+| `get_rates` | `GET /rates` |
+| `list_assets` | `GET /assets` (optional chain filter) |
+| `simulate_test_payment` | `POST /test/simulate_payment` (test keys only) |
+| `list_records` | `GET /records`: the book of record (payments, fees, credit purchases) valued when they happened; filters type / asset / chain / invoice / order / tx / dates / currency |
+| `get_records_summary` | `GET /records/summary`: sales, market value received, refunds, fees, net received for a period, optionally grouped |
+| `create_export` | `POST /exports`: CSV, Excel or JSON file of records or any dataset (QuickBooks, Xero, Koinly, CoinTracker, CoinLedger presets); returns the export with `download_url` |
+| `get_export` | `GET /exports/{id}`: poll status until `ready`, read `file.sha256` and `download_url` |
+
+Every tool returns the raw API JSON (also as `structuredContent`). API errors come back as tool errors
+containing `http_status`, the CoinVello `error` envelope (`type`, `code`, `message`, `request_id`) and a `hint`.
+
+## Resources
+
+| URI | Content |
+|-----|---------|
+| `coinvello://docs/llms-full.txt` | Complete single-file integration guide (auth, checkout, redirect, webhook verification, polling, credits, errors, examples in curl/Node/Python/PHP) |
+| `coinvello://docs/llms.txt` | Short llms.txt index |
+| `coinvello://openapi.yaml` | OpenAPI 3.1 specification |
+
+Documents are bundled at build time; if missing they are fetched from coinvello.com.
+
+## Prompts
+
+`integrate-coinvello-into-<framework>` for `nextjs`, `express`, `fastapi`, `flask`, `django`,
+`laravel`, `rails`, `sinatra`, `go`, `woocommerce`, `shopify`, `generic`, plus
+`integrate-coinvello-into-framework` with a free-form `framework` argument. Optional arguments:
+`currency`, `assets`. Each prompt tells the agent to read the guide resource, add a checkout route, a
+raw-body webhook route with signature verification and `event.id` dedupe, and to verify end to end
+with `simulate_test_payment`.
+
+## Typical agent session
+
+1. `list_assets` -> pick assets the merchant can accept.
+2. `create_webhook` with the app's `/webhooks/coinvello` URL -> store the secret in the env file.
+3. Write the code (see the `integrate-coinvello-into-*` prompt or `api/ai/cookbook`).
+4. `create_checkout_session` -> `simulate_test_payment` on `invoice_id` with enough confirmations.
+5. `get_invoice` shows `paid`; the app's webhook handler was called with a real signed event.
+6. `verify_webhook_signature` to debug a handler that rejects deliveries.
+7. Bookkeeping: `list_records` (with `include_simulated: true` in test mode) -> `get_records_summary` for a period -> `create_export` (`format: "xlsx"`) -> `get_export` until `ready` -> download the `download_url` and check `file.sha256`.
+
+## Development
+
+```bash
+npm install
+npm run build          # copies docs into dist/docs and compiles TypeScript
+npm test               # smoke test against the mock: needs api/reference-server running on :4242
+npm run dev            # tsx src/index.ts (stdio)
+```
+
+Smoke test: `cd api/reference-server && npm install && npm start`, then
+`COINVELLO_API_BASE=http://localhost:4242/v1 npm test` here. It exercises all 18 tools, the three
+resources and the prompts, verifies a real signed delivery captured by the mock's webhook sink, and
+checks the xprv guard. The mock does not implement wallet CRUD, so `create_wallet` / `list_wallets`
+are expected to return a clean 404 tool error there.
+
+## Security notes
+
+- Keep the server on test keys while an agent is writing code. `COINVELLO_ALLOW_LIVE=1` is a deliberate opt-in.
+- The server never logs the API key or webhook secrets. Tool output does include `secret` from `create_webhook` because that is the only time the API returns it.
+- `create_wallet` rejects anything that looks like an extended private key before it leaves the machine.
+- Nothing here moves funds: CoinVello is non-custodial, and the API has no "send" operation.
+
+License MIT. Issues: support@coinvello.com

package/dist/client.d.ts

@@ -0,0 +1,32 @@
+export interface CoinVelloClientOptions {
+    apiKey: string;
+    baseUrl?: string;
+    apiVersion?: string;
+    timeoutMs?: number;
+}
+export interface CoinVelloErrorBody {
+    type: string;
+    code: string;
+    message: string;
+    param?: string;
+    request_id?: string;
+    doc_url?: string;
+    details?: Record<string, unknown>;
+}
+export declare class CoinVelloApiError extends Error {
+    readonly status: number;
+    readonly error: CoinVelloErrorBody;
+    constructor(status: number, error: CoinVelloErrorBody);
+}
+export type Query = Record<string, string | number | boolean | undefined | null>;
+export declare class CoinVelloClient {
+    readonly baseUrl: string;
+    readonly livemode: boolean;
+    private readonly apiKey;
+    private readonly apiVersion?;
+    private readonly timeoutMs;
+    constructor(opts: CoinVelloClientOptions);
+    get<T = unknown>(path: string, query?: Query): Promise<T>;
+    post<T = unknown>(path: string, body?: unknown, idempotencyKey?: string): Promise<T>;
+    request<T>(method: string, path: string, body?: unknown, query?: Query, idempotencyKey?: string): Promise<T>;
+}

package/dist/client.js

@@ -0,0 +1,86 @@
+/**
+ * Minimal HTTP client for the CoinVello REST API used by the MCP tools.
+ * No SDK dependency so the server stays small and `npx -y @coinvello/mcp` starts fast.
+ */
+import { randomUUID } from "node:crypto";
+export class CoinVelloApiError extends Error {
+    status;
+    error;
+    constructor(status, error) {
+        super(`${status} ${error.type}/${error.code}: ${error.message}`);
+        this.status = status;
+        this.error = error;
+        this.name = "CoinVelloApiError";
+    }
+}
+export class CoinVelloClient {
+    baseUrl;
+    livemode;
+    apiKey;
+    apiVersion;
+    timeoutMs;
+    constructor(opts) {
+        this.apiKey = opts.apiKey;
+        this.baseUrl = (opts.baseUrl ?? "https://api.coinvello.com/v1").replace(/\/+$/, "");
+        this.apiVersion = opts.apiVersion;
+        this.timeoutMs = opts.timeoutMs ?? 20_000;
+        this.livemode = /^cv_live_/.test(opts.apiKey);
+    }
+    async get(path, query) {
+        return this.request("GET", path, undefined, query);
+    }
+    async post(path, body, idempotencyKey) {
+        return this.request("POST", path, body, undefined, idempotencyKey ?? randomUUID());
+    }
+    async request(method, path, body, query, idempotencyKey) {
+        const url = new URL(this.baseUrl + path);
+        for (const [k, v] of Object.entries(query ?? {})) {
+            if (v !== undefined && v !== null && v !== "")
+                url.searchParams.set(k, String(v));
+        }
+        const headers = {
+            Authorization: `Bearer ${this.apiKey}`,
+            Accept: "application/json",
+            "User-Agent": "coinvello-mcp/0.1.0",
+        };
+        if (body !== undefined)
+            headers["Content-Type"] = "application/json";
+        if (idempotencyKey)
+            headers["Idempotency-Key"] = idempotencyKey;
+        if (this.apiVersion)
+            headers["CoinVello-Version"] = this.apiVersion;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        let res;
+        try {
+            res = await fetch(url, {
+                method,
+                headers,
+                body: body === undefined ? undefined : JSON.stringify(body),
+                signal: controller.signal,
+            });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        const text = await res.text();
+        let json = null;
+        if (text) {
+            try {
+                json = JSON.parse(text);
+            }
+            catch {
+                json = { raw: text };
+            }
+        }
+        if (!res.ok) {
+            const err = json?.error ?? {
+                type: "api_error",
+                code: `http_${res.status}`,
+                message: text || res.statusText,
+            };
+            throw new CoinVelloApiError(res.status, err);
+        }
+        return json;
+    }
+}