@paymos/mcp 1.3.1 → 1.4.1

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 CHANGED
@@ -2,6 +2,17 @@
2
2
 
3
3
  ## [Unreleased]
4
4
 
5
+ ## [1.4.1] - 2026-11-02
6
+
7
+ - docs: regenerate merged documentation on shared node
8
+ - merge: integrate current main and shared workspace
9
+ - wip: snapshot shared working tree before merging main
10
+ - wip(refunds): merchant refund plugin work (CMS adapters, PHP SDK, tests) - unverified WIP snapshot
11
+
12
+ ## [1.4.0] - 2026-11-01
13
+
14
+ - feat(mcp): add sandbox payment channel tools
15
+
5
16
  ## [1.3.1] - 2026-11-01
6
17
 
7
18
  - refactor(invoices): remove the multiple-payment toggle
package/README.md CHANGED
@@ -2,11 +2,13 @@
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 runs over stdio. It exposes six tools and five documentation resources and accepts test key pairs only. Live and payout keys are refused.
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
 
9
- - Node.js 20 or newer
11
+ - Requires Node.js 22.12 or later.
10
12
  - A Paymos merchant account with a test key pair from Dashboard → Developer → API Keys (`pk_test_…` and `sk_test_…`)
11
13
  - An MCP client that can launch a local stdio server
12
14
 
@@ -180,6 +182,18 @@ The server still reads `PAYMOS_API_KEY_ID`, `PAYMOS_API_SECRET`, and optional `P
180
182
  | `cancel_invoice` | Cancel an unpaid invoice and store the reason |
181
183
  | `simulate_invoice_payment` | Simulate `paid`, `paid_late`, `overpaid`, `underpay`, or `cancel` in the sandbox |
182
184
  | `verify_webhook_signature` | Verify `X-Webhook-Signature` against the raw webhook body locally |
185
+ | `create_payment_channel` | Create a channel; idempotent per `project_id` and `external_id` |
186
+ | `get_payment_channel` | Read a channel's current status and available deposit addresses |
187
+ | `list_payment_channels` | List one page of channels with filters and a cursor |
188
+ | `block_payment_channel` | Set a payment channel's status to blocked |
189
+ | `unblock_payment_channel` | Clear a payment channel's blocked status |
190
+ | `simulate_payment_channel_deposit` | Simulate a new `confirming`, `reorged`, or `confirmed` deposit |
191
+ | `get_payment_channel_deposit` | Read a deposit at any stage |
192
+ | `list_payment_channel_deposits` | Read one page of confirmed deposits, oldest first |
193
+
194
+ 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.
195
+
196
+ A deposit-feed cursor is valid for 24 hours; keep `confirmed_from` unchanged when continuing with that cursor.
183
197
 
184
198
  `paid_late` is a simulation scenario, not an invoice status. See the [sandbox documentation](https://paymos.io/docs/testing) for its behavior.
185
199
 
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 six tools) but every tool call answers with the gate
5
- * error — no tool runs. Startup lines go to stderr only: stdout is the
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
- invoices() {
187
+ client() {
188
188
  const check = this.check();
189
189
  if (!check.ok) throw new ToolError(check.code, check.message);
190
- const client = new Paymos({
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
- return client.invoices;
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
  {
@@ -604,7 +734,7 @@ typed response. Manual signing is documented separately in <a href="/docs/authen
604
734
  <pre class="shiki one-dark-pro" style="background-color:#282c34;color:#abb2bf" tabindex="0" data-lang="json"><code><span class="line"><span style="color:#ABB2BF">{</span></span>
605
735
  <span class="line"><span style="color:#E06C75"> "event_id"</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"evt_J7EEYeL9pZJukfj2c5OQ44"</span><span style="color:#ABB2BF">,</span></span>
606
736
  <span class="line"><span style="color:#E06C75"> "event_type"</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"invoice.paid"</span><span style="color:#ABB2BF">,</span></span>
607
- <span class="line"><span style="color:#E06C75"> "version"</span><span style="color:#ABB2BF">: </span><span style="color:#D19A66">1</span><span style="color:#ABB2BF">,</span></span>
737
+ <span class="line"><span style="color:#E06C75"> "version"</span><span style="color:#ABB2BF">: </span><span style="color:#D19A66">2</span><span style="color:#ABB2BF">,</span></span>
608
738
  <span class="line"><span style="color:#E06C75"> "occurred_at"</span><span style="color:#ABB2BF">: </span><span style="color:#D19A66">1739281200</span><span style="color:#ABB2BF">,</span></span>
609
739
  <span class="line"><span style="color:#E06C75"> "data"</span><span style="color:#ABB2BF">: {</span></span>
610
740
  <span class="line"><span style="color:#E06C75"> "invoice_id"</span><span style="color:#ABB2BF">: </span><span style="color:#98C379">"inv_5CcyDYmMUGtzYL10q0Iimr"</span><span style="color:#ABB2BF">,</span></span>
@@ -770,7 +900,7 @@ typed response. Manual signing is documented separately in <a href="/docs/authen
770
900
  <span class="line"><span style="color:#D19A66"> src</span><span style="color:#ABB2BF">=</span><span style="color:#98C379">"https://checkout.paymos.io/invoice/inv_xxx?embed=true"</span></span>
771
901
  <span class="line"><span style="color:#D19A66"> title</span><span style="color:#ABB2BF">=</span><span style="color:#98C379">"Paymos checkout"</span></span>
772
902
  <span class="line"><span style="color:#D19A66"> allow</span><span style="color:#ABB2BF">=</span><span style="color:#98C379">"clipboard-write"</span></span>
773
- <span class="line"><span style="color:#D19A66"> sandbox</span><span style="color:#ABB2BF">=</span><span style="color:#98C379">"allow-scripts allow-same-origin allow-forms"</span></span>
903
+ <span class="line"><span style="color:#D19A66"> sandbox</span><span style="color:#ABB2BF">=</span><span style="color:#98C379">"allow-scripts allow-same-origin allow-forms allow-popups"</span></span>
774
904
  <span class="line"><span style="color:#D19A66"> style</span><span style="color:#ABB2BF">=</span><span style="color:#98C379">"display:block;width:100%;max-width:460px;height:min(90vh,900px);border:0;"</span></span>
775
905
  <span class="line"><span style="color:#ABB2BF">>&#x3C;/</span><span style="color:#E06C75">iframe</span><span style="color:#ABB2BF">></span></span>
776
906
  <span class="line"></span></code></pre>
@@ -822,7 +952,7 @@ typed response. Manual signing is documented separately in <a href="/docs/authen
822
952
  <div class="callout callout--danger"><svg class="callout__icon" viewBox="0 0 20 20" fill="none" stroke="currentColor" aria-hidden="true"><path stroke-linecap="round" stroke-linejoin="round" stroke-width="1.6" d="M10 2.5a7.5 7.5 0 1 0 0 15 7.5 7.5 0 0 0 0-15ZM7 7l6 6m0-6-6 6"></path></svg><div class="callout__body"><p>Treat these events as UX hints, not proof of payment. Drive spinners, redirects, and analytics from them \u2014 but never ship goods, credit balances, or mark an order paid based on a <code>postMessage</code>. A <code>postMessage</code> is trivial to spoof: any page sharing the customer's origin can post a fake <code>paymos:succeeded</code>. Settlement is confirmed only by the signed server-side webhook \u2014 the one source of truth for fulfillment.</p></div></div>
823
953
  <h2 id="security-model">Security model</h2>
824
954
  <p>The recommended iframe sandbox is deliberately small:</p>
825
- <ul class="list-none p-0 m-0 flex flex-col gap-3"><li class="flex gap-3"><span class="font-mono text-primary shrink-0">\u2014</span><span><code>allow-scripts</code> is required for checkout interactivity, API calls, timers, copy buttons, and live status updates.</span></li><li class="flex gap-3"><span class="font-mono text-primary shrink-0">\u2014</span><span><code>allow-same-origin</code> lets the Paymos-hosted checkout run with its own origin instead of an opaque sandbox origin.</span></li><li class="flex gap-3"><span class="font-mono text-primary shrink-0">\u2014</span><span><code>allow-forms</code> allows normal form interactions inside checkout.</span></li><li class="flex gap-3"><span class="font-mono text-primary shrink-0">\u2014</span><span><code>allow-top-navigation</code> is omitted so the iframe cannot navigate the merchant page.</span></li><li class="flex gap-3"><span class="font-mono text-primary shrink-0">\u2014</span><span><code>allow-popups</code> is omitted because the checkout does not need to open extra browser windows.</span></li></ul>
955
+ <ul class="list-none p-0 m-0 flex flex-col gap-3"><li class="flex gap-3"><span class="font-mono text-primary shrink-0">\u2014</span><span><code>allow-scripts</code> is required for checkout interactivity, API calls, timers, copy buttons, and live status updates.</span></li><li class="flex gap-3"><span class="font-mono text-primary shrink-0">\u2014</span><span><code>allow-same-origin</code> lets the Paymos-hosted checkout run with its own origin instead of an opaque sandbox origin.</span></li><li class="flex gap-3"><span class="font-mono text-primary shrink-0">\u2014</span><span><code>allow-forms</code> allows normal form interactions inside checkout.</span></li><li class="flex gap-3"><span class="font-mono text-primary shrink-0">\u2014</span><span><code>allow-top-navigation</code> is omitted so the iframe cannot navigate the merchant page.</span></li><li class="flex gap-3"><span class="font-mono text-primary shrink-0">\u2014</span><span><code>allow-popups</code> lets the buyer open the terms and other checkout links in a new tab.</span></li></ul>
826
956
  <h2 id="when-to-use-low-code-sdk-instead">When to use Low-Code SDK instead</h2>
827
957
  <p>Use <a href="/docs/widget-sdk">Low-Code SDK</a> when you want Paymos to create invoices from browser-side config, render the payment button, manage the modal lifecycle, validate iframe messages, and dispatch <code>paymos:*</code> <code>CustomEvent</code>s for you.</p>
828
958
  <p>Use manual iframe embed when your backend already owns invoice creation and you only need to place the hosted checkout UI inside your page.</p>`
@@ -1041,7 +1171,7 @@ function registerResources(server) {
1041
1171
  }
1042
1172
 
1043
1173
  // src/version.ts
1044
- var MCP_VERSION = "1.3.1";
1174
+ var MCP_VERSION = "1.4.1";
1045
1175
 
1046
1176
  // src/server.ts
1047
1177
  function buildServer(gateway) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@paymos/mcp",
3
- "version": "1.3.1",
3
+ "version": "1.4.1",
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",
@@ -47,7 +47,7 @@
47
47
  ],
48
48
  "sideEffects": false,
49
49
  "engines": {
50
- "node": ">=20"
50
+ "node": ">=22.12"
51
51
  },
52
52
  "scripts": {
53
53
  "build": "npm run build:resources && tsup src/index.ts --format esm --dts --clean",
@@ -59,7 +59,7 @@
59
59
  },
60
60
  "dependencies": {
61
61
  "@modelcontextprotocol/sdk": "^1.31.0",
62
- "@paymos/sdk": "^2.0.0",
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"