@arionpay/mcp 0.0.0-stage → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md ADDED
@@ -0,0 +1,13 @@
1
+ # Changelog
2
+
3
+ ## 1.0.0
4
+
5
+ First release.
6
+
7
+ - Docs tools (no keys, offline): `search_docs`, `get_doc_page`, `list_integrations`, `get_api_reference`.
8
+ - Live public tools: `list_coins`, `get_rates`.
9
+ - Store tools (with `ARIONPAY_API_KEY` and `ARIONPAY_API_SECRET`): `check_connection`, `list_invoices`, `get_invoice`,
10
+ `create_invoice`, `simulate_payment`, `send_test_webhook`.
11
+ - Test invoices by default; real invoices only with `ARIONPAY_LIVE=true`, an explicit request and below
12
+ `ARIONPAY_MAX_AMOUNT`; `ARIONPAY_READ_ONLY` for reading only.
13
+ - `list_invoices` needs ArionPay v2.0.61 or newer on the server (`GET /api/v1/invoices`).
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 ArionPay
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,137 @@
1
- # Temporary Holding Version
1
+ # ArionPay MCP server
2
2
 
3
- 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.
3
+ The official [Model Context Protocol](https://modelcontextprotocol.io) server for [ArionPay](https://arionpay.com), the
4
+ non-custodial crypto payment gateway. Your AI assistant (Claude, Cursor, VS Code Copilot and other MCP apps) can:
5
+
6
+ - **answer ArionPay questions and write integration code**: it searches the ArionPay docs, API reference, plugin and
7
+ library guides. No account or keys needed.
8
+ - **work with your store**: create an invoice and get its payment link, check whether an order was paid, list today's
9
+ payments, and try a payment in test mode.
10
+
11
+ ArionPay never holds your money: customers pay straight into your own wallet.
12
+
13
+ ## Tools
14
+
15
+ | Tool | What it does | Needs keys |
16
+ | --- | --- | --- |
17
+ | `search_docs` | Searches the ArionPay help pages (API, webhooks, test mode, payment rules, fees, 24 plugins, 8 libraries) | no |
18
+ | `get_doc_page` | Reads one page, e.g. `/docs`, `/libraries/python`, `/plugins/woocommerce` | no |
19
+ | `list_integrations` | Every plugin and library, with its guide | no |
20
+ | `get_api_reference` | The REST API from its OpenAPI description, one endpoint or all | no |
21
+ | `list_coins` | Coins and networks a checkout can offer right now (live) | no |
22
+ | `get_rates` | Current coin prices in a fiat currency (live) | no |
23
+ | `check_connection` | Checks your keys and names the store | yes |
24
+ | `list_invoices` | Your invoices, newest first, filter by status, date or order ID | yes |
25
+ | `get_invoice` | One invoice: status, coin, amounts, confirmations, transaction | yes |
26
+ | `create_invoice` | Creates an invoice and returns its payment link | yes |
27
+ | `simulate_payment` | Pays a **test** invoice in a chosen scenario (exact, underpaid, late …) | yes |
28
+ | `send_test_webhook` | Sends a signed sample event to your shop's webhook | yes |
29
+
30
+ The docs tools read a copy of the public pages of arionpay.com that ships inside the package: they work offline and
31
+ send nothing anywhere.
32
+
33
+ ## Set up
34
+
35
+ You need Node.js 20 or newer. The server runs on your own computer; your AI app starts it.
36
+
37
+ **Docs only (no keys)** — add the server without any environment variables.
38
+
39
+ **With your store** — in the [ArionPay dashboard](https://merchant.arionpay.com) open **Stores → your store** and copy
40
+ the API key (`pk_…`) and the API secret (`sk_…`). Tip: make a separate store for your assistant, so you can see its
41
+ invoices apart and replace its keys without touching your shop.
42
+
43
+ ### Claude Desktop
44
+
45
+ Settings → Developer → Edit config, then add:
46
+
47
+ ```json
48
+ {
49
+ "mcpServers": {
50
+ "arionpay": {
51
+ "command": "npx",
52
+ "args": ["-y", "@arionpay/mcp"],
53
+ "env": {
54
+ "ARIONPAY_API_KEY": "pk_...",
55
+ "ARIONPAY_API_SECRET": "sk_..."
56
+ }
57
+ }
58
+ }
59
+ }
60
+ ```
61
+
62
+ ### Claude Code
63
+
64
+ ```sh
65
+ claude mcp add arionpay -e ARIONPAY_API_KEY=pk_... -e ARIONPAY_API_SECRET=sk_... -- npx -y @arionpay/mcp
66
+ ```
67
+
68
+ ### Cursor
69
+
70
+ `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (one project): the same `mcpServers` block as for Claude
71
+ Desktop.
72
+
73
+ ### VS Code
74
+
75
+ `.vscode/mcp.json` — VS Code asks for the secret once and stores it for you:
76
+
77
+ ```json
78
+ {
79
+ "inputs": [
80
+ { "type": "promptString", "id": "arionpay-secret", "description": "ArionPay API secret (sk_...)", "password": true }
81
+ ],
82
+ "servers": {
83
+ "arionpay": {
84
+ "type": "stdio",
85
+ "command": "npx",
86
+ "args": ["-y", "@arionpay/mcp"],
87
+ "env": {
88
+ "ARIONPAY_API_KEY": "pk_...",
89
+ "ARIONPAY_API_SECRET": "${input:arionpay-secret}"
90
+ }
91
+ }
92
+ }
93
+ }
94
+ ```
95
+
96
+ ## Settings
97
+
98
+ | Variable | Default | Meaning |
99
+ | --- | --- | --- |
100
+ | `ARIONPAY_API_KEY` | – | Store API key (`pk_…`). Without key and secret only the docs and public tools are offered. |
101
+ | `ARIONPAY_API_SECRET` | – | Store API secret (`sk_…`). |
102
+ | `ARIONPAY_LIVE` | off | `true` allows **real** invoices, and only when the assistant asks for one (`test: false`). Off: every invoice is a test invoice. |
103
+ | `ARIONPAY_MAX_AMOUNT` | `1000` | Largest real invoice, in the invoice's own currency. |
104
+ | `ARIONPAY_READ_ONLY` | off | `true` leaves out `create_invoice`, `simulate_payment` and `send_test_webhook`. |
105
+ | `ARIONPAY_BASE_URL` | `https://merchant.arionpay.com` | Only for testing against another ArionPay server. |
106
+
107
+ ## Safety
108
+
109
+ - Your keys stay in your settings on your computer. No tool takes a key, so they never pass through the chat.
110
+ - Test mode by default. Real invoices need `ARIONPAY_LIVE=true` **and** an explicit request, and stay under
111
+ `ARIONPAY_MAX_AMOUNT`.
112
+ - The assistant can create and read invoices, nothing more. There is no tool for wallets, API secrets, webhook
113
+ settings, payouts or marking an invoice paid, and `create_invoice` cannot set webhook or redirect addresses: text
114
+ the assistant read somewhere else cannot send your payment notices or your customers to another address.
115
+ - A test invoice moves no money. An order is paid only when `get_invoice` says `PAID` and `test` is `false` — and
116
+ your shop should confirm orders from the signed webhook, as always.
117
+
118
+ ## Try it
119
+
120
+ - "How do I verify an ArionPay webhook in Laravel?"
121
+ - "Create a test invoice for 25 USD for order 1042, paid in USDT on TRON, then simulate the payment."
122
+ - "Which of today's invoices are paid?"
123
+ - "Is invoice 6b03… paid? How many confirmations does it have?"
124
+
125
+ ## Development
126
+
127
+ ```sh
128
+ npm install
129
+ npm test # builds, then runs the tests
130
+ npm run docs-snapshot -- <path to a build of the arionpay.com website (dist)>
131
+ ```
132
+
133
+ `src/docs-snapshot.json` is generated from the public pages of a website build; regenerate it when the docs change.
134
+
135
+ ## Licence
136
+
137
+ MIT
@@ -0,0 +1,31 @@
1
+ export declare class ArionPayApiError extends Error {
2
+ readonly status: number;
3
+ readonly code?: string | undefined;
4
+ constructor(message: string, status: number, code?: string | undefined);
5
+ }
6
+ export interface ClientOptions {
7
+ baseUrl: string;
8
+ apiKey?: string;
9
+ apiSecret?: string;
10
+ /** For tests. */
11
+ fetch?: typeof fetch;
12
+ timeoutMs?: number;
13
+ userAgent?: string;
14
+ }
15
+ export declare class ArionPayClient {
16
+ private readonly opts;
17
+ private readonly fetchImpl;
18
+ private readonly timeoutMs;
19
+ constructor(opts: ClientOptions);
20
+ get hasKeys(): boolean;
21
+ /** Public endpoint, no signature. */
22
+ publicGet<T>(path: string): Promise<T>;
23
+ /** Signed GET: `query` values that are undefined are left out. */
24
+ signedGet<T>(path: string, query?: Record<string, string | number | boolean | undefined>): Promise<T>;
25
+ /** Signed POST of a JSON body (the exact bytes sent are the bytes signed). */
26
+ signedPost<T>(path: string, body: Record<string, unknown>): Promise<T>;
27
+ private headers;
28
+ /** The same request signed again (new timestamp) once, when the server says the signature was already used. */
29
+ private withReplayRetry;
30
+ private send;
31
+ }
package/dist/client.js ADDED
@@ -0,0 +1,119 @@
1
+ /**
2
+ * A small signed client for the ArionPay shop API.
3
+ *
4
+ * x-api-key store API key (pk_…)
5
+ * x-timestamp unix seconds
6
+ * x-signature hex HMAC-SHA256(secret, `${timestamp}.${body}`) POST
7
+ * hex HMAC-SHA256(secret, `${timestamp}.GET ${path?query}`) GET
8
+ *
9
+ * The server refuses an identical signed request twice (replay guard). Every signed GET therefore carries a random
10
+ * `nonce` query value, and a POST refused as "already used" is signed again one second later.
11
+ */
12
+ import { createHmac, randomBytes } from "node:crypto";
13
+ export class ArionPayApiError extends Error {
14
+ status;
15
+ code;
16
+ constructor(message, status, code) {
17
+ super(message);
18
+ this.status = status;
19
+ this.code = code;
20
+ this.name = "ArionPayApiError";
21
+ }
22
+ }
23
+ const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
24
+ export class ArionPayClient {
25
+ opts;
26
+ fetchImpl;
27
+ timeoutMs;
28
+ constructor(opts) {
29
+ this.opts = opts;
30
+ this.fetchImpl = opts.fetch ?? fetch;
31
+ this.timeoutMs = opts.timeoutMs ?? 20_000;
32
+ }
33
+ get hasKeys() {
34
+ return Boolean(this.opts.apiKey && this.opts.apiSecret);
35
+ }
36
+ /** Public endpoint, no signature. */
37
+ async publicGet(path) {
38
+ return this.send("GET", path, undefined, {});
39
+ }
40
+ /** Signed GET: `query` values that are undefined are left out. */
41
+ async signedGet(path, query = {}) {
42
+ const params = new URLSearchParams();
43
+ for (const [k, v] of Object.entries(query))
44
+ if (v !== undefined && v !== "")
45
+ params.set(k, String(v));
46
+ params.set("nonce", randomBytes(8).toString("hex"));
47
+ const pathWithQuery = `${path}?${params.toString()}`;
48
+ return this.withReplayRetry(() => {
49
+ const ts = Math.floor(Date.now() / 1000);
50
+ return this.send("GET", pathWithQuery, undefined, this.headers(ts, `${ts}.GET ${pathWithQuery}`));
51
+ });
52
+ }
53
+ /** Signed POST of a JSON body (the exact bytes sent are the bytes signed). */
54
+ async signedPost(path, body) {
55
+ const raw = JSON.stringify(body);
56
+ return this.withReplayRetry(() => {
57
+ const ts = Math.floor(Date.now() / 1000);
58
+ return this.send("POST", path, raw, this.headers(ts, `${ts}.${raw}`));
59
+ });
60
+ }
61
+ headers(ts, toSign) {
62
+ if (!this.opts.apiKey || !this.opts.apiSecret)
63
+ throw new ArionPayApiError("This needs your store API key and secret (ARIONPAY_API_KEY and ARIONPAY_API_SECRET).", 0, "no_keys");
64
+ return {
65
+ "x-api-key": this.opts.apiKey,
66
+ "x-timestamp": String(ts),
67
+ "x-signature": createHmac("sha256", this.opts.apiSecret).update(toSign).digest("hex"),
68
+ };
69
+ }
70
+ /** The same request signed again (new timestamp) once, when the server says the signature was already used. */
71
+ async withReplayRetry(run) {
72
+ try {
73
+ return await run();
74
+ }
75
+ catch (e) {
76
+ if (e instanceof ArionPayApiError && e.status === 401 && /already used/i.test(e.message)) {
77
+ await sleep(1100);
78
+ return run();
79
+ }
80
+ throw e;
81
+ }
82
+ }
83
+ async send(method, path, raw, headers) {
84
+ const ctrl = new AbortController();
85
+ const timer = setTimeout(() => ctrl.abort(), this.timeoutMs);
86
+ let res;
87
+ try {
88
+ res = await this.fetchImpl(`${this.opts.baseUrl}${path}`, {
89
+ method,
90
+ headers: { accept: "application/json", "user-agent": this.opts.userAgent ?? "arionpay-mcp", ...(raw !== undefined ? { "content-type": "application/json" } : {}), ...headers },
91
+ body: raw,
92
+ signal: ctrl.signal,
93
+ });
94
+ }
95
+ catch (e) {
96
+ const why = e.name === "AbortError" ? `no answer within ${Math.round(this.timeoutMs / 1000)} s` : e.message;
97
+ throw new ArionPayApiError(`Could not reach ArionPay (${why}).`, 0, "network");
98
+ }
99
+ finally {
100
+ clearTimeout(timer);
101
+ }
102
+ const text = await res.text();
103
+ let data = undefined;
104
+ try {
105
+ data = text ? JSON.parse(text) : undefined;
106
+ }
107
+ catch {
108
+ // not JSON (e.g. a proxy error page)
109
+ }
110
+ if (!res.ok) {
111
+ const d = (data ?? {});
112
+ const msg = typeof d.error === "string" ? d.error : typeof d.message === "string" ? d.message : `HTTP ${res.status}`;
113
+ throw new ArionPayApiError(msg, res.status, typeof d.code === "string" ? d.code : undefined);
114
+ }
115
+ if (data === undefined)
116
+ throw new ArionPayApiError(`ArionPay answered with something that is not JSON (HTTP ${res.status}).`, res.status, "bad_response");
117
+ return data;
118
+ }
119
+ }
@@ -0,0 +1,21 @@
1
+ /**
2
+ * Settings, read from environment variables only. The API secret is never a tool argument, so it never passes
3
+ * through the AI chat.
4
+ */
5
+ export interface Config {
6
+ /** Store API key (pk_…). Without key AND secret only the docs and public tools are offered. */
7
+ apiKey?: string;
8
+ /** Store API secret (sk_…). */
9
+ apiSecret?: string;
10
+ /** API base URL. */
11
+ baseUrl: string;
12
+ /** Real (non-test) invoices allowed. Off by default: every invoice is a test invoice. */
13
+ live: boolean;
14
+ /** Largest amount of a real invoice, in the invoice's own currency. */
15
+ maxAmount: number;
16
+ /** Only reading tools: no invoice is created, simulated or webhook sent. */
17
+ readOnly: boolean;
18
+ }
19
+ export declare const DEFAULT_BASE_URL = "https://merchant.arionpay.com";
20
+ export declare const DEFAULT_MAX_AMOUNT = 1000;
21
+ export declare function configFromEnv(env?: NodeJS.ProcessEnv): Config;
package/dist/config.js ADDED
@@ -0,0 +1,22 @@
1
+ export const DEFAULT_BASE_URL = "https://merchant.arionpay.com";
2
+ export const DEFAULT_MAX_AMOUNT = 1000;
3
+ const yes = (v) => /^(1|true|yes|on)$/i.test((v ?? "").trim());
4
+ export function configFromEnv(env = process.env) {
5
+ const apiKey = env.ARIONPAY_API_KEY?.trim() || undefined;
6
+ const apiSecret = env.ARIONPAY_API_SECRET?.trim() || undefined;
7
+ if (apiKey && !/^pk_[A-Za-z0-9_-]{8,64}$/.test(apiKey))
8
+ throw new Error("ARIONPAY_API_KEY must be your store's API key (it starts with pk_).");
9
+ if (apiKey && !apiSecret)
10
+ throw new Error("ARIONPAY_API_SECRET is missing. Set both ARIONPAY_API_KEY and ARIONPAY_API_SECRET, or neither.");
11
+ if (apiSecret && !apiKey)
12
+ throw new Error("ARIONPAY_API_KEY is missing. Set both ARIONPAY_API_KEY and ARIONPAY_API_SECRET, or neither.");
13
+ const baseUrl = (env.ARIONPAY_BASE_URL?.trim() || DEFAULT_BASE_URL).replace(/\/+$/, "");
14
+ if (!/^https:\/\//.test(baseUrl) && !/^http:\/\/(localhost|127\.0\.0\.1)(:\d+)?$/.test(baseUrl)) {
15
+ throw new Error("ARIONPAY_BASE_URL must be an https:// address (http:// only for localhost).");
16
+ }
17
+ const rawMax = env.ARIONPAY_MAX_AMOUNT?.trim();
18
+ const maxAmount = rawMax ? Number(rawMax) : DEFAULT_MAX_AMOUNT;
19
+ if (!Number.isFinite(maxAmount) || maxAmount <= 0)
20
+ throw new Error("ARIONPAY_MAX_AMOUNT must be a number above 0.");
21
+ return { apiKey, apiSecret, baseUrl, live: yes(env.ARIONPAY_LIVE), maxAmount, readOnly: yes(env.ARIONPAY_READ_ONLY) };
22
+ }