@paymos/mcp 1.3.0 → 1.4.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 +8 -0
- package/README.md +17 -1
- package/dist/index.d.ts +2 -2
- package/dist/index.js +134 -8
- package/package.json +2 -2
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,14 @@
|
|
|
2
2
|
|
|
3
3
|
## [Unreleased]
|
|
4
4
|
|
|
5
|
+
## [1.4.0] - 2026-11-01
|
|
6
|
+
|
|
7
|
+
- feat(mcp): add sandbox payment channel tools
|
|
8
|
+
|
|
9
|
+
## [1.3.1] - 2026-11-01
|
|
10
|
+
|
|
11
|
+
- refactor(invoices): remove the multiple-payment toggle
|
|
12
|
+
|
|
5
13
|
## [1.3.0] - 2026-10-30
|
|
6
14
|
|
|
7
15
|
- fix(plugins): reject invalid Woo refund controls and unblock SDK checks
|
package/README.md
CHANGED
|
@@ -2,10 +2,14 @@
|
|
|
2
2
|
|
|
3
3
|
Connect your coding agent to the Paymos sandbox through a local MCP server. The agent can create test invoices, simulate payment scenarios, inspect invoice states, and verify webhook signatures while building your application around a Paymos server SDK.
|
|
4
4
|
|
|
5
|
-
The server
|
|
5
|
+
The local MCP server connects your coding agent to the Paymos sandbox with 14 tools and five documentation resources for testing merchant integrations.
|
|
6
|
+
|
|
7
|
+
Use a test Payment key pair. Live and Payout keys are rejected; API requests are signed through the official SDK, and real funds are not involved.
|
|
6
8
|
|
|
7
9
|
## Requirements
|
|
8
10
|
|
|
11
|
+
The MCP package passes tests on Node.js 20, but its SDK dependency officially requires Node.js 22.12 or newer, so npm refuses installation on Node.js 20 when `engine-strict` is enabled.
|
|
12
|
+
|
|
9
13
|
- Node.js 20 or newer
|
|
10
14
|
- A Paymos merchant account with a test key pair from Dashboard → Developer → API Keys (`pk_test_…` and `sk_test_…`)
|
|
11
15
|
- An MCP client that can launch a local stdio server
|
|
@@ -180,6 +184,18 @@ The server still reads `PAYMOS_API_KEY_ID`, `PAYMOS_API_SECRET`, and optional `P
|
|
|
180
184
|
| `cancel_invoice` | Cancel an unpaid invoice and store the reason |
|
|
181
185
|
| `simulate_invoice_payment` | Simulate `paid`, `paid_late`, `overpaid`, `underpay`, or `cancel` in the sandbox |
|
|
182
186
|
| `verify_webhook_signature` | Verify `X-Webhook-Signature` against the raw webhook body locally |
|
|
187
|
+
| `create_payment_channel` | Create a channel; idempotent per `project_id` and `external_id` |
|
|
188
|
+
| `get_payment_channel` | Read a channel's current status and available deposit addresses |
|
|
189
|
+
| `list_payment_channels` | List one page of channels with filters and a cursor |
|
|
190
|
+
| `block_payment_channel` | Set a payment channel's status to blocked |
|
|
191
|
+
| `unblock_payment_channel` | Clear a payment channel's blocked status |
|
|
192
|
+
| `simulate_payment_channel_deposit` | Simulate a new `confirming`, `reorged`, or `confirmed` deposit |
|
|
193
|
+
| `get_payment_channel_deposit` | Read a deposit at any stage |
|
|
194
|
+
| `list_payment_channel_deposits` | Read one page of confirmed deposits, oldest first |
|
|
195
|
+
|
|
196
|
+
Each `simulate_payment_channel_deposit` call creates a new test deposit. The deposit feed returns only confirmed deposits. Save `next_cursor` from every response, including empty pages, and use it for the next poll. If the feed stops advancing, check `blocked` for the deposit and reason.
|
|
197
|
+
|
|
198
|
+
A deposit-feed cursor is valid for 24 hours; keep `confirmed_from` unchanged when continuing with that cursor.
|
|
183
199
|
|
|
184
200
|
`paid_late` is a simulation scenario, not an invoice status. See the [sandbox documentation](https://paymos.io/docs/testing) for its behavior.
|
|
185
201
|
|
package/dist/index.d.ts
CHANGED
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
#!/usr/bin/env node
|
|
2
2
|
/**
|
|
3
3
|
* Stdio entry point. On a credential failure the server still starts (so the
|
|
4
|
-
* MCP client sees the
|
|
5
|
-
* error — no
|
|
4
|
+
* MCP client sees the tools) but every API tool call answers with the gate
|
|
5
|
+
* error — no API call runs. Startup lines go to stderr only: stdout is the
|
|
6
6
|
* JSON-RPC channel, and no line ever contains the secret.
|
|
7
7
|
*/
|
|
8
8
|
declare function main(env?: Readonly<Record<string, string | undefined>>, argv?: readonly string[]): Promise<void>;
|
package/dist/index.js
CHANGED
|
@@ -184,15 +184,23 @@ var PaymosGateway = class {
|
|
|
184
184
|
webhookSecret() {
|
|
185
185
|
return this.credentials.webhookSecret;
|
|
186
186
|
}
|
|
187
|
-
|
|
187
|
+
client() {
|
|
188
188
|
const check = this.check();
|
|
189
189
|
if (!check.ok) throw new ToolError(check.code, check.message);
|
|
190
|
-
|
|
190
|
+
return new Paymos({
|
|
191
191
|
apiKey: this.credentials.apiKeyId,
|
|
192
192
|
apiSecret: this.credentials.apiSecret,
|
|
193
193
|
...this.overrides.fetch ? { fetch: this.overrides.fetch } : {}
|
|
194
194
|
});
|
|
195
|
-
|
|
195
|
+
}
|
|
196
|
+
invoices() {
|
|
197
|
+
return this.client().invoices;
|
|
198
|
+
}
|
|
199
|
+
paymentChannels() {
|
|
200
|
+
return this.client().paymentChannels;
|
|
201
|
+
}
|
|
202
|
+
paymentChannelDeposits() {
|
|
203
|
+
return this.client().paymentChannelDeposits;
|
|
196
204
|
}
|
|
197
205
|
};
|
|
198
206
|
|
|
@@ -248,6 +256,128 @@ async function guarded(run) {
|
|
|
248
256
|
}
|
|
249
257
|
}
|
|
250
258
|
function registerTools(server, gateway) {
|
|
259
|
+
server.registerTool(
|
|
260
|
+
"create_payment_channel",
|
|
261
|
+
{
|
|
262
|
+
title: "Create payment channel",
|
|
263
|
+
description: "Create a Sandbox payment channel using project_id and external_id. Repeating the same pair returns the existing channel.",
|
|
264
|
+
inputSchema: {
|
|
265
|
+
project_id: z.string().min(1).describe("Project ID."),
|
|
266
|
+
external_id: z.string().min(1).max(128).describe("Your identifier for the payer; channel creation is idempotent within the project.")
|
|
267
|
+
}
|
|
268
|
+
},
|
|
269
|
+
async ({ project_id, external_id }) => guarded(async () => {
|
|
270
|
+
const channel = await gateway.paymentChannels().create({ projectId: project_id, externalId: external_id });
|
|
271
|
+
return textJson(toWireShape(channel));
|
|
272
|
+
})
|
|
273
|
+
);
|
|
274
|
+
server.registerTool(
|
|
275
|
+
"get_payment_channel",
|
|
276
|
+
{
|
|
277
|
+
title: "Get payment channel",
|
|
278
|
+
description: "Read a Sandbox payment channel by ID, including its current status and available deposit addresses.",
|
|
279
|
+
inputSchema: { payment_channel_id: z.string().min(1).describe("Payment channel ID.") }
|
|
280
|
+
},
|
|
281
|
+
async ({ payment_channel_id }) => guarded(async () => textJson(toWireShape(await gateway.paymentChannels().get(payment_channel_id))))
|
|
282
|
+
);
|
|
283
|
+
server.registerTool(
|
|
284
|
+
"list_payment_channels",
|
|
285
|
+
{
|
|
286
|
+
title: "List payment channels",
|
|
287
|
+
description: "List Sandbox payment channels with optional project_id, external_id, and status filters. Use limit and cursor to request one page at a time.",
|
|
288
|
+
inputSchema: {
|
|
289
|
+
project_id: z.string().min(1).optional().describe("Project ID."),
|
|
290
|
+
external_id: z.string().min(1).max(128).optional().describe("Your identifier for the payer; channel creation is idempotent within the project."),
|
|
291
|
+
status: z.array(z.enum(["active", "blocked", "provisioning"])).optional().describe("Array of channel statuses to include: active, blocked, or provisioning."),
|
|
292
|
+
limit: z.number().int().min(1).max(100).optional().describe("Maximum number of items to return in this page."),
|
|
293
|
+
cursor: z.string().optional().describe("Pagination cursor from the previous channel-list response.")
|
|
294
|
+
}
|
|
295
|
+
},
|
|
296
|
+
async ({ project_id, external_id, status, limit, cursor }) => guarded(async () => {
|
|
297
|
+
const page = await gateway.paymentChannels().list({
|
|
298
|
+
...project_id !== void 0 ? { projectId: project_id } : {},
|
|
299
|
+
...external_id !== void 0 ? { externalId: external_id } : {},
|
|
300
|
+
...status !== void 0 ? { status } : {},
|
|
301
|
+
...limit !== void 0 ? { limit } : {},
|
|
302
|
+
...cursor !== void 0 ? { cursor } : {}
|
|
303
|
+
});
|
|
304
|
+
return textJson(toWireShape(page));
|
|
305
|
+
})
|
|
306
|
+
);
|
|
307
|
+
server.registerTool(
|
|
308
|
+
"block_payment_channel",
|
|
309
|
+
{
|
|
310
|
+
title: "Block payment channel",
|
|
311
|
+
description: "Set a Sandbox payment channel's status to blocked.",
|
|
312
|
+
inputSchema: { payment_channel_id: z.string().min(1).describe("Payment channel ID.") }
|
|
313
|
+
},
|
|
314
|
+
async ({ payment_channel_id }) => guarded(async () => textJson(toWireShape(await gateway.paymentChannels().block(payment_channel_id))))
|
|
315
|
+
);
|
|
316
|
+
server.registerTool(
|
|
317
|
+
"unblock_payment_channel",
|
|
318
|
+
{
|
|
319
|
+
title: "Unblock payment channel",
|
|
320
|
+
description: "Clear a Sandbox payment channel's blocked status.",
|
|
321
|
+
inputSchema: { payment_channel_id: z.string().min(1).describe("Payment channel ID.") }
|
|
322
|
+
},
|
|
323
|
+
async ({ payment_channel_id }) => guarded(async () => textJson(toWireShape(await gateway.paymentChannels().unblock(payment_channel_id))))
|
|
324
|
+
);
|
|
325
|
+
server.registerTool(
|
|
326
|
+
"simulate_payment_channel_deposit",
|
|
327
|
+
{
|
|
328
|
+
title: "Simulate payment channel deposit",
|
|
329
|
+
description: "Create a new Sandbox deposit on every call using a channel ID, decimal-string amount, currency, and network. The optional stage accepts confirming, reorged, or confirmed and defaults to confirmed. No real blockchain is called, and no real funds move.",
|
|
330
|
+
inputSchema: {
|
|
331
|
+
payment_channel_id: z.string().min(1).describe("Payment channel ID."),
|
|
332
|
+
amount: z.string().min(1).describe("Deposit amount as a decimal string."),
|
|
333
|
+
currency: z.string().min(1).describe("Currency symbol for the simulated deposit."),
|
|
334
|
+
network: z.string().min(1).describe("Network for the simulated deposit."),
|
|
335
|
+
stage: z.enum(["confirming", "reorged", "confirmed"]).optional().describe("Simulated deposit stage: confirming, reorged, or confirmed. Defaults to confirmed when omitted.")
|
|
336
|
+
}
|
|
337
|
+
},
|
|
338
|
+
async ({ payment_channel_id, amount, currency, network, stage }) => guarded(async () => {
|
|
339
|
+
const deposit = await gateway.paymentChannels().simulateDeposit(payment_channel_id, {
|
|
340
|
+
amount,
|
|
341
|
+
currency,
|
|
342
|
+
network,
|
|
343
|
+
...stage !== void 0 ? { stage } : {}
|
|
344
|
+
});
|
|
345
|
+
return textJson(toWireShape(deposit));
|
|
346
|
+
})
|
|
347
|
+
);
|
|
348
|
+
server.registerTool(
|
|
349
|
+
"get_payment_channel_deposit",
|
|
350
|
+
{
|
|
351
|
+
title: "Get payment channel deposit",
|
|
352
|
+
description: "Read a Sandbox payment channel deposit by ID at any stage, including confirming, reorged, and confirmed.",
|
|
353
|
+
inputSchema: { payment_channel_deposit_id: z.string().min(1).describe("Payment channel deposit ID.") }
|
|
354
|
+
},
|
|
355
|
+
async ({ payment_channel_deposit_id }) => guarded(async () => textJson(toWireShape(await gateway.paymentChannelDeposits().get(payment_channel_deposit_id))))
|
|
356
|
+
);
|
|
357
|
+
server.registerTool(
|
|
358
|
+
"list_payment_channel_deposits",
|
|
359
|
+
{
|
|
360
|
+
title: "List confirmed channel deposits",
|
|
361
|
+
description: "Poll confirmed Sandbox deposits, oldest first. Every response includes next_cursor, even on an empty page; save it for the next poll. If the feed stops advancing, the optional blocked field identifies the deposit and explains why.",
|
|
362
|
+
inputSchema: {
|
|
363
|
+
limit: z.number().int().min(1).max(100).optional().describe("Maximum number of items to return in this page."),
|
|
364
|
+
cursor: z.string().optional().describe("Cursor from the previous response. For the deposit feed, keep it even after an empty page."),
|
|
365
|
+
project_id: z.string().min(1).optional().describe("Project ID."),
|
|
366
|
+
payment_channel_id: z.string().min(1).optional().describe("Payment channel ID."),
|
|
367
|
+
confirmed_from: z.number().int().optional().describe("Inclusive lower bound in Unix seconds for the initial poll. Keep the same value when continuing with a cursor.")
|
|
368
|
+
}
|
|
369
|
+
},
|
|
370
|
+
async ({ limit, cursor, project_id, payment_channel_id, confirmed_from }) => guarded(async () => {
|
|
371
|
+
const page = await gateway.paymentChannelDeposits().read({
|
|
372
|
+
...limit !== void 0 ? { limit } : {},
|
|
373
|
+
...cursor !== void 0 ? { cursor } : {},
|
|
374
|
+
...project_id !== void 0 ? { projectId: project_id } : {},
|
|
375
|
+
...payment_channel_id !== void 0 ? { paymentChannelId: payment_channel_id } : {},
|
|
376
|
+
...confirmed_from !== void 0 ? { confirmedFrom: confirmed_from } : {}
|
|
377
|
+
});
|
|
378
|
+
return textJson(toWireShape(page));
|
|
379
|
+
})
|
|
380
|
+
);
|
|
251
381
|
server.registerTool(
|
|
252
382
|
"create_invoice",
|
|
253
383
|
{
|
|
@@ -261,7 +391,6 @@ function registerTools(server, gateway) {
|
|
|
261
391
|
`Locks the crypto invoice to one network: ${NETWORKS}. Omit to let the customer choose on the payment page`
|
|
262
392
|
),
|
|
263
393
|
external_order_id: z.string().min(1).max(128).describe("Your order identifier (\u2264128 chars); idempotency key per project"),
|
|
264
|
-
allow_multiple_payments: z.boolean().optional().describe("Allow the customer to pay an invoice in several transfers (default true)"),
|
|
265
394
|
customer_fee_percent: z.number().int().min(0).max(100).optional().describe("0\u2013100 service fee percent charged to the customer; overrides the project setting"),
|
|
266
395
|
client_id: z.string().max(200).optional().describe("Your customer reference (\u2264200 chars)")
|
|
267
396
|
}
|
|
@@ -272,7 +401,6 @@ function registerTools(server, gateway) {
|
|
|
272
401
|
currency,
|
|
273
402
|
network,
|
|
274
403
|
external_order_id,
|
|
275
|
-
allow_multiple_payments,
|
|
276
404
|
customer_fee_percent,
|
|
277
405
|
client_id
|
|
278
406
|
}) => guarded(async () => {
|
|
@@ -282,7 +410,6 @@ function registerTools(server, gateway) {
|
|
|
282
410
|
currency,
|
|
283
411
|
externalOrderId: external_order_id,
|
|
284
412
|
...network !== void 0 ? { network } : {},
|
|
285
|
-
...allow_multiple_payments !== void 0 ? { allowMultiplePayments: allow_multiple_payments } : {},
|
|
286
413
|
...customer_fee_percent !== void 0 ? { customerFeePercent: customer_fee_percent } : {},
|
|
287
414
|
...client_id !== void 0 ? { clientId: client_id } : {}
|
|
288
415
|
});
|
|
@@ -572,7 +699,6 @@ typed response. Manual signing is documented separately in <a href="/docs/authen
|
|
|
572
699
|
<span class="line"><span style="color:#E06C75"> currency</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"USD"</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">to_owned</span><span style="color:#ABB2BF">(),</span></span>
|
|
573
700
|
<span class="line"><span style="color:#E06C75"> external_order_id</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"order-123"</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">to_owned</span><span style="color:#ABB2BF">(),</span></span>
|
|
574
701
|
<span class="line"><span style="color:#E06C75"> network</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">None</span><span style="color:#ABB2BF">,</span></span>
|
|
575
|
-
<span class="line"><span style="color:#E06C75"> allow_multiple_payments</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">None</span><span style="color:#ABB2BF">,</span></span>
|
|
576
702
|
<span class="line"><span style="color:#E06C75"> customer_fee_percent</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">None</span><span style="color:#ABB2BF">,</span></span>
|
|
577
703
|
<span class="line"><span style="color:#E06C75"> client_id</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">Some</span><span style="color:#ABB2BF">(</span><span style="color:#98C379">"customer-456"</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">to_owned</span><span style="color:#ABB2BF">()),</span></span>
|
|
578
704
|
<span class="line"><span style="color:#ABB2BF"> })</span></span>
|
|
@@ -1045,7 +1171,7 @@ function registerResources(server) {
|
|
|
1045
1171
|
}
|
|
1046
1172
|
|
|
1047
1173
|
// src/version.ts
|
|
1048
|
-
var MCP_VERSION = "1.
|
|
1174
|
+
var MCP_VERSION = "1.4.0";
|
|
1049
1175
|
|
|
1050
1176
|
// src/server.ts
|
|
1051
1177
|
function buildServer(gateway) {
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@paymos/mcp",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.4.0",
|
|
4
4
|
"description": "Official Paymos MCP server: a local stdio server that lets coding agents (Claude Code, Cursor, custom LLM bots) build and verify a merchant integration against the Paymos sandbox without reading docs.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"paymos",
|
|
@@ -59,7 +59,7 @@
|
|
|
59
59
|
},
|
|
60
60
|
"dependencies": {
|
|
61
61
|
"@modelcontextprotocol/sdk": "^1.31.0",
|
|
62
|
-
"@paymos/sdk": "^2.
|
|
62
|
+
"@paymos/sdk": "^2.4.0",
|
|
63
63
|
"jsonc-parser": "3.3.1",
|
|
64
64
|
"smol-toml": "1.9.1",
|
|
65
65
|
"zod": "^4.6.5"
|