@paymos/mcp 1.4.1 → 1.5.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 +11 -0
- package/README.md +1 -0
- package/dist/index.js +179 -28
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,17 @@
|
|
|
2
2
|
|
|
3
3
|
## [Unreleased]
|
|
4
4
|
|
|
5
|
+
## [1.5.1] - 2026-11-13
|
|
6
|
+
|
|
7
|
+
- fix(plugins,publicweb): SDK webhook credit recipes, CMS recovery, redirects and CSP logs (audit 2026-11-13)
|
|
8
|
+
|
|
9
|
+
## [1.5.0] - 2026-11-07
|
|
10
|
+
|
|
11
|
+
- feat(publicweb,docs,blazor,mcp): add MCP prompt tab to code snippets and compact /contacts header
|
|
12
|
+
- docs(sdk): backfill published mirror changelogs across SDKs and MCP
|
|
13
|
+
- chore: sync Spec Forge 1.6.1, MCP integration recommendation, webhook alert hold, and social agent runs
|
|
14
|
+
- docs(refunds): publish merchant refunds API reference and guides across 6 locales
|
|
15
|
+
|
|
5
16
|
## [1.4.1] - 2026-11-02
|
|
6
17
|
|
|
7
18
|
- docs: regenerate merged documentation on shared node
|
package/README.md
CHANGED
|
@@ -176,6 +176,7 @@ The server still reads `PAYMOS_API_KEY_ID`, `PAYMOS_API_SECRET`, and optional `P
|
|
|
176
176
|
|
|
177
177
|
| Tool | Purpose |
|
|
178
178
|
|---|---|
|
|
179
|
+
| `recommend_payment_integration` | Recommend invoices, payment channels, or both from the merchant’s payment flow. Explain the fit and relevant lifecycle. When information is missing, return a targeted question instead of choosing. Respect an explicit merchant choice. |
|
|
179
180
|
| `create_invoice` | Create a sandbox invoice; idempotent per `external_order_id`; returns `payment_url` |
|
|
180
181
|
| `get_invoice` | Fetch the current invoice state |
|
|
181
182
|
| `list_invoices` | Fetch one cursor page of invoices, with filters |
|
package/dist/index.js
CHANGED
|
@@ -544,7 +544,7 @@ var DOC_RESOURCES = [
|
|
|
544
544
|
<p>Use an official server SDK below. It serializes the request, creates the exact
|
|
545
545
|
HMAC signature, sets the timestamp headers, applies safe retries, and returns a
|
|
546
546
|
typed response. Manual signing is documented separately in <a href="/docs/authentication">Authentication</a>.</p>
|
|
547
|
-
<div class="code-tab-group"><div class="code-tab-bar"><button type="button" class="code-tab-btn active" data-tab-idx="0" data-code-lang="curl">cURL</button><button type="button" class="code-tab-btn" data-tab-idx="1" data-code-lang="javascript"><i class="devicon-javascript-plain colored"></i> JavaScript</button><button type="button" class="code-tab-btn" data-tab-idx="
|
|
547
|
+
<div class="code-tab-group"><div class="code-tab-bar"><button type="button" class="code-tab-btn active" data-tab-idx="0" data-code-lang="curl">cURL</button><button type="button" class="code-tab-btn" data-tab-idx="1" data-code-lang="mcp">MCP</button><button type="button" class="code-tab-btn" data-tab-idx="2" data-code-lang="javascript"><i class="devicon-javascript-plain colored"></i> JavaScript</button><button type="button" class="code-tab-btn" data-tab-idx="3" data-code-lang="python"><i class="devicon-python-plain colored"></i> Python</button><button type="button" class="code-tab-btn" data-tab-idx="4" data-code-lang="php"><i class="devicon-php-plain colored"></i> PHP</button><button type="button" class="code-tab-btn" data-tab-idx="5" data-code-lang="go"><i class="devicon-go-plain colored"></i> Go</button><button type="button" class="code-tab-btn" data-tab-idx="6" data-code-lang="csharp"><i class="devicon-csharp-plain colored"></i> C#</button><button type="button" class="code-tab-btn" data-tab-idx="7" data-code-lang="java"><i class="devicon-java-plain colored"></i> Java</button><button type="button" class="code-tab-btn" data-tab-idx="8" data-code-lang="ruby"><i class="devicon-ruby-plain colored"></i> Ruby</button><button type="button" class="code-tab-btn" data-tab-idx="9" data-code-lang="rust"><i class="devicon-rust-original colored"></i> Rust</button></div><div class="code-tab-panel active" data-code-lang="curl"><pre class="shiki one-dark-pro" style="background-color:#282c34;color:#abb2bf" tabindex="0" data-lang="curl"><code><span class="line"><span style="color:#E06C75">API_KEY_ID</span><span style="color:#56B6C2">=</span><span style="color:#98C379">"pk_live_xxxxxxxxxxxx"</span></span>
|
|
548
548
|
<span class="line"><span style="color:#E06C75">API_SECRET</span><span style="color:#56B6C2">=</span><span style="color:#98C379">"sk_live_xxxxxxxxxxxx"</span></span>
|
|
549
549
|
<span class="line"><span style="color:#E06C75">BODY</span><span style="color:#56B6C2">=</span><span style="color:#98C379">'{"project_id":"prj_xxxxxxxxxxxx","amount":"100.00","currency":"USD","external_order_id":"order-123","client_id":"customer-456"}'</span></span>
|
|
550
550
|
<span class="line"></span>
|
|
@@ -558,6 +558,15 @@ typed response. Manual signing is documented separately in <a href="/docs/authen
|
|
|
558
558
|
<span class="line"><span style="color:#D19A66"> -H</span><span style="color:#98C379"> "X-Request-Timestamp: </span><span style="color:#E06C75">$TS</span><span style="color:#98C379">"</span><span style="color:#56B6C2"> \\</span></span>
|
|
559
559
|
<span class="line"><span style="color:#D19A66"> -H</span><span style="color:#98C379"> "Content-Type: application/json"</span><span style="color:#56B6C2"> \\</span></span>
|
|
560
560
|
<span class="line"><span style="color:#D19A66"> -d</span><span style="color:#98C379"> "</span><span style="color:#E06C75">$BODY</span><span style="color:#98C379">"</span></span>
|
|
561
|
+
<span class="line"></span></code></pre></div><div class="code-tab-panel" data-code-lang="mcp"><pre class="shiki one-dark-pro" style="background-color:#282c34;color:#abb2bf" tabindex="0" data-lang="mcp"><code><span class="line"><span style="color:#ABB2BF">Setup once in terminal: </span><span style="color:#E5C07B">\`</span><span style="color:#98C379">npx -y @paymos/mcp setup</span><span style="color:#E5C07B">\`</span></span>
|
|
562
|
+
<span class="line"></span>
|
|
563
|
+
<span class="line"><span style="color:#ABB2BF">Prompt:</span></span>
|
|
564
|
+
<span class="line"><span style="color:#ABB2BF">Read </span><span style="color:#E5C07B">\`</span><span style="color:#98C379">paymos://docs/hosted-checkout</span><span style="color:#E5C07B">\`</span><span style="color:#ABB2BF"> and integrate Paymos invoice</span></span>
|
|
565
|
+
<span class="line"><span style="color:#ABB2BF">creation into my backend using the official SDK for this project's</span></span>
|
|
566
|
+
<span class="line"><span style="color:#ABB2BF">stack. Then use </span><span style="color:#E5C07B">\`</span><span style="color:#98C379">@paymos/mcp</span><span style="color:#E5C07B">\`</span><span style="color:#ABB2BF"> in sandbox to call </span><span style="color:#E5C07B">\`</span><span style="color:#98C379">create_invoice</span><span style="color:#E5C07B">\`</span></span>
|
|
567
|
+
<span class="line"><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">\`</span><span style="color:#98C379">project_id</span><span style="color:#E5C07B">\`</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">\`</span><span style="color:#98C379">prj_xxxxxxxxxxxx</span><span style="color:#E5C07B">\`</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">\`</span><span style="color:#98C379">amount</span><span style="color:#E5C07B">\`</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">\`</span><span style="color:#98C379">"100.00"</span><span style="color:#E5C07B">\`</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">\`</span><span style="color:#98C379">currency</span><span style="color:#E5C07B">\`</span><span style="color:#ABB2BF">:</span></span>
|
|
568
|
+
<span class="line"><span style="color:#E5C07B">\`</span><span style="color:#98C379">"USD"</span><span style="color:#E5C07B">\`</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">\`</span><span style="color:#98C379">external_order_id</span><span style="color:#E5C07B">\`</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">\`</span><span style="color:#98C379">"order-123"</span><span style="color:#E5C07B">\`</span><span style="color:#ABB2BF">) and run</span></span>
|
|
569
|
+
<span class="line"><span style="color:#E5C07B">\`</span><span style="color:#98C379">simulate_invoice_payment</span><span style="color:#E5C07B">\`</span><span style="color:#ABB2BF"> (</span><span style="color:#E5C07B">\`</span><span style="color:#98C379">stage</span><span style="color:#E5C07B">\`</span><span style="color:#ABB2BF">: </span><span style="color:#E5C07B">\`</span><span style="color:#98C379">"paid"</span><span style="color:#E5C07B">\`</span><span style="color:#ABB2BF">) to verify the flow.</span></span>
|
|
561
570
|
<span class="line"></span></code></pre></div><div class="code-tab-panel" data-code-lang="javascript"><pre class="shiki one-dark-pro" style="background-color:#282c34;color:#abb2bf" tabindex="0" data-lang="javascript"><code><span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">Paymos</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">externalOrderId</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> '@paymos/sdk'</span><span style="color:#ABB2BF">;</span></span>
|
|
562
571
|
<span class="line"></span>
|
|
563
572
|
<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> paymos</span><span style="color:#56B6C2"> =</span><span style="color:#C678DD"> new</span><span style="color:#61AFEF"> Paymos</span><span style="color:#ABB2BF">({</span></span>
|
|
@@ -734,7 +743,7 @@ typed response. Manual signing is documented separately in <a href="/docs/authen
|
|
|
734
743
|
<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>
|
|
735
744
|
<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>
|
|
736
745
|
<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>
|
|
737
|
-
<span class="line"><span style="color:#E06C75"> "version"</span><span style="color:#ABB2BF">: </span><span style="color:#D19A66">
|
|
746
|
+
<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>
|
|
738
747
|
<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>
|
|
739
748
|
<span class="line"><span style="color:#E06C75"> "data"</span><span style="color:#ABB2BF">: {</span></span>
|
|
740
749
|
<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>
|
|
@@ -783,13 +792,21 @@ typed response. Manual signing is documented separately in <a href="/docs/authen
|
|
|
783
792
|
<span class="line"></span></code></pre>
|
|
784
793
|
<p>Verify the <code>X-Webhook-Signature</code> header and fulfill the order.</p>
|
|
785
794
|
<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>Never fulfill an order from a browser event (<code>paymos:succeeded</code> or iframe <code>postMessage</code>). Only the signed server-side webhook is authoritative \u2014 browser signals can be spoofed.</p></div></div>
|
|
786
|
-
<div class="code-tab-group"><div class="code-tab-bar"><button type="button" class="code-tab-btn active" data-tab-idx="0" data-code-lang="javascript"><i class="devicon-javascript-plain colored"></i> JavaScript</button><button type="button" class="code-tab-btn" data-tab-idx="1" data-code-lang="python"><i class="devicon-python-plain colored"></i> Python</button><button type="button" class="code-tab-btn" data-tab-idx="
|
|
795
|
+
<div class="code-tab-group"><div class="code-tab-bar"><button type="button" class="code-tab-btn active" data-tab-idx="0" data-code-lang="javascript"><i class="devicon-javascript-plain colored"></i> JavaScript</button><button type="button" class="code-tab-btn" data-tab-idx="1" data-code-lang="mcp">MCP</button><button type="button" class="code-tab-btn" data-tab-idx="2" data-code-lang="python"><i class="devicon-python-plain colored"></i> Python</button><button type="button" class="code-tab-btn" data-tab-idx="3" data-code-lang="php"><i class="devicon-php-plain colored"></i> PHP</button><button type="button" class="code-tab-btn" data-tab-idx="4" data-code-lang="go"><i class="devicon-go-plain colored"></i> Go</button><button type="button" class="code-tab-btn" data-tab-idx="5" data-code-lang="csharp"><i class="devicon-csharp-plain colored"></i> C#</button><button type="button" class="code-tab-btn" data-tab-idx="6" data-code-lang="java"><i class="devicon-java-plain colored"></i> Java</button><button type="button" class="code-tab-btn" data-tab-idx="7" data-code-lang="ruby"><i class="devicon-ruby-plain colored"></i> Ruby</button><button type="button" class="code-tab-btn" data-tab-idx="8" data-code-lang="rust"><i class="devicon-rust-original colored"></i> Rust</button></div><div class="code-tab-panel active" data-code-lang="javascript"><pre class="shiki one-dark-pro" style="background-color:#282c34;color:#abb2bf" tabindex="0" data-lang="javascript"><code><span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> { </span><span style="color:#E06C75">WebhookVerifier</span><span style="color:#ABB2BF"> } </span><span style="color:#C678DD">from</span><span style="color:#98C379"> '@paymos/sdk'</span><span style="color:#ABB2BF">;</span></span>
|
|
787
796
|
<span class="line"></span>
|
|
788
797
|
<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> verifier</span><span style="color:#56B6C2"> =</span><span style="color:#C678DD"> new</span><span style="color:#61AFEF"> WebhookVerifier</span><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">process</span><span style="color:#ABB2BF">.</span><span style="color:#E5C07B">env</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">PAYMOS_WEBHOOK_SECRET</span><span style="color:#ABB2BF">);</span></span>
|
|
789
798
|
<span class="line"></span>
|
|
790
799
|
<span class="line"><span style="color:#7F848E;font-style:italic">// Keep the body as a Buffer until verification succeeds.</span></span>
|
|
791
800
|
<span class="line"><span style="color:#C678DD">const</span><span style="color:#E5C07B"> event</span><span style="color:#56B6C2"> =</span><span style="color:#E5C07B"> verifier</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">constructEvent</span><span style="color:#ABB2BF">(</span><span style="color:#E06C75">signatureHeader</span><span style="color:#ABB2BF">, </span><span style="color:#E06C75">rawBody</span><span style="color:#ABB2BF">);</span></span>
|
|
792
801
|
<span class="line"><span style="color:#E5C07B">console</span><span style="color:#ABB2BF">.</span><span style="color:#61AFEF">log</span><span style="color:#ABB2BF">(</span><span style="color:#E5C07B">event</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">eventId</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">event</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">eventType</span><span style="color:#ABB2BF">, </span><span style="color:#E5C07B">event</span><span style="color:#ABB2BF">.</span><span style="color:#E06C75">data</span><span style="color:#ABB2BF">);</span></span>
|
|
802
|
+
<span class="line"></span></code></pre></div><div class="code-tab-panel" data-code-lang="mcp"><pre class="shiki one-dark-pro" style="background-color:#282c34;color:#abb2bf" tabindex="0" data-lang="mcp"><code><span class="line"><span style="color:#ABB2BF">Setup once in terminal: </span><span style="color:#E5C07B">\`</span><span style="color:#98C379">npx -y @paymos/mcp setup</span><span style="color:#E5C07B">\`</span></span>
|
|
803
|
+
<span class="line"></span>
|
|
804
|
+
<span class="line"><span style="color:#ABB2BF">Prompt:</span></span>
|
|
805
|
+
<span class="line"><span style="color:#ABB2BF">Read </span><span style="color:#E5C07B">\`</span><span style="color:#98C379">paymos://docs/webhooks</span><span style="color:#E5C07B">\`</span><span style="color:#ABB2BF"> and add a Paymos webhook endpoint to my</span></span>
|
|
806
|
+
<span class="line"><span style="color:#ABB2BF">backend that verifies </span><span style="color:#E5C07B">\`</span><span style="color:#98C379">X-Webhook-Signature</span><span style="color:#E5C07B">\`</span><span style="color:#ABB2BF"> over the unparsed raw</span></span>
|
|
807
|
+
<span class="line"><span style="color:#ABB2BF">request body using </span><span style="color:#E5C07B">\`</span><span style="color:#98C379">WebhookVerifier</span><span style="color:#E5C07B">\`</span><span style="color:#ABB2BF"> from the official SDK and</span></span>
|
|
808
|
+
<span class="line"><span style="color:#ABB2BF">deduplicates deliveries by </span><span style="color:#E5C07B">\`</span><span style="color:#98C379">event_id</span><span style="color:#E5C07B">\`</span><span style="color:#ABB2BF">. Use </span><span style="color:#E5C07B">\`</span><span style="color:#98C379">@paymos/mcp</span><span style="color:#E5C07B">\`</span><span style="color:#ABB2BF"> tool</span></span>
|
|
809
|
+
<span class="line"><span style="color:#E5C07B">\`</span><span style="color:#98C379">verify_webhook_signature</span><span style="color:#E5C07B">\`</span><span style="color:#ABB2BF"> to test valid and tampered signatures.</span></span>
|
|
793
810
|
<span class="line"></span></code></pre></div><div class="code-tab-panel" data-code-lang="python"><pre class="shiki one-dark-pro" style="background-color:#282c34;color:#abb2bf" tabindex="0" data-lang="python"><code><span class="line"><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> os</span></span>
|
|
794
811
|
<span class="line"></span>
|
|
795
812
|
<span class="line"><span style="color:#C678DD">from</span><span style="color:#ABB2BF"> paymos </span><span style="color:#C678DD">import</span><span style="color:#ABB2BF"> WebhookVerifier</span></span>
|
|
@@ -1017,6 +1034,10 @@ typed response. Manual signing is documented separately in <a href="/docs/authen
|
|
|
1017
1034
|
<p>Sandbox withdrawals don't settle on a real chain. Mark a pending sandbox withdrawal as completed to exercise your full payout flow:</p>
|
|
1018
1035
|
<div class="api-endpoint-badge"><span class="api-method-badge api-method-post">POST</span><span class="api-endpoint-badge__path">/v1/sandbox/withdrawals/:withdrawal_id/simulate-completion</span></div>
|
|
1019
1036
|
<p>No request body. Authenticate it like any other <code>/v1</code> call with your Payout key; it acts on sandbox withdrawals only. It transitions the withdrawal to <code>completed</code> and emits the same <code>withdrawal.completed</code> webhook as a real on-chain payout, so your reconciliation path stays identical between sandbox and production.</p>
|
|
1037
|
+
<h2 id="simulating-refunds">Simulating refunds</h2>
|
|
1038
|
+
<p>Create a sandbox refund first with <a href="/docs/refunds/create"><code>POST /v1/refunds</code></a> using your sandbox Payment key (<code>pk_test_</code>), then drive it to a terminal status:</p>
|
|
1039
|
+
<div class="api-endpoint-badge"><span class="api-method-badge api-method-post">POST</span><span class="api-endpoint-badge__path">/v1/sandbox/refunds/:withdrawal_id/simulate</span></div>
|
|
1040
|
+
<div class="callout callout--info"><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-15Zm0 6.5v5m0-7.5h.01"></path></svg><div class="callout__body"><p>Body: <code>{ "status": "completed" }</code> \u2014 <code>status</code> is one of <code>completed</code>, <code>failed</code>, or <code>cancelled</code>. Sign it with your sandbox Payment key (<code>pk_test_</code>). It updates the sandbox ledger and emits the corresponding <code>withdrawal.completed</code>, <code>withdrawal.failed</code>, or <code>withdrawal.cancelled</code> webhook with the full refund payload. See <a href="/docs/refunds/simulate">Simulate Refund</a> for the full contract.</p></div></div>
|
|
1020
1041
|
<h2 id="simulating-channel-deposits">Simulating channel deposits</h2>
|
|
1021
1042
|
<p>Sandbox payment channels derive their addresses locally and watch no chain, so deposits are created explicitly:</p>
|
|
1022
1043
|
<div class="api-endpoint-badge"><span class="api-method-badge api-method-post">POST</span><span class="api-endpoint-badge__path">/v1/sandbox/payment-channels/:payment_channel_id/simulate-deposit</span></div>
|
|
@@ -1170,13 +1191,82 @@ function registerResources(server) {
|
|
|
1170
1191
|
}
|
|
1171
1192
|
}
|
|
1172
1193
|
|
|
1194
|
+
// src/integration-recommendation.ts
|
|
1195
|
+
import { z as z2 } from "zod";
|
|
1196
|
+
var INTEGRATION_INSTRUCTIONS = "When helping a developer choose a payment integration, call recommend_payment_integration with scenario order_checkout, repeat_deposits, both, or unsure. Respect the merchant\u2019s stated preference; do not replace an explicit choice. Explain why the recommended flow fits their needs and identify missing information. Use unsure when the need is unclear; ask whether the customer will pay for each order, repeatedly top up an account, or do both. This MCP server calls sandbox only and rejects live and payout credentials. Check availability in the target environment.";
|
|
1197
|
+
var GUIDE = `Choose the flow before creating a payment resource.
|
|
1198
|
+
|
|
1199
|
+
Use an invoice when your customer pays for a specific order. An invoice has a set amount, an expiry, and payment statuses; its hosted checkout gives the customer a page to pay that invoice.
|
|
1200
|
+
|
|
1201
|
+
Choose a payment channel for repeated customer deposits. It belongs to one payer and keeps a permanent address per supported network. The channel sets no amount or expiry and has no terminal payment status. Each credited transfer becomes a separate deposit, so track deposits individually when crediting the customer\u2019s account. Transfers below the minimum deposit are not credited or returned.
|
|
1202
|
+
|
|
1203
|
+
You can use both in the same integration. For example, use invoices for purchases and a payment channel for account top-ups. If the intended flow is unclear, ask: \u201CWill your customer pay for each order, repeatedly top up an account, or do both?\u201D
|
|
1204
|
+
|
|
1205
|
+
Test the chosen flow in sandbox. This MCP server calls sandbox only and rejects live and payout credentials. Create sandbox and production channels separately, and check availability in the target environment. Sandbox addresses are synthetic; each deposit simulation creates a new test deposit rather than updating an earlier simulation.
|
|
1206
|
+
|
|
1207
|
+
Credit channel deposits only after confirmation. Verify webhook signatures and require \`confirmed\` with \`is_final\` before crediting a deposit. Webhooks can repeat or arrive out of order: deduplicate deliveries by \`event_id\` and prevent duplicate credit for the same deposit.
|
|
1208
|
+
|
|
1209
|
+
Use the confirmed-deposit feed to reconcile deposits. Save every returned \`next_cursor\`, even on empty pages, and inspect \`blocked\` when present. \`confirmed_from\` bounds the first poll and forms part of the cursor\u2019s fingerprint; keep its value unchanged when continuing with that cursor. Feed cursors expire 24 hours after issue, so poll at least daily. If a cursor expires, restart with a bounded \`confirmed_from\` and retain deposit deduplication.
|
|
1210
|
+
|
|
1211
|
+
Start with the flow you chose. The recommendation needs no credentials; API calls need test credentials.
|
|
1212
|
+
|
|
1213
|
+
For invoices, call \`create_invoice\` with \`project_id\`, \`external_order_id\`, \`amount\` as a decimal string, and \`currency\`. Save the invoice\u2019s link to your order, and use the returned \`payment_url\` for checkout. Test a payment with \`simulate_invoice_payment\`, passing \`invoice_id\` and \`stage\`.
|
|
1214
|
+
|
|
1215
|
+
For payment channels, call \`create_payment_channel\` with \`project_id\` and your customer\u2019s \`external_id\`. Save the channel\u2019s link to that customer. Check the returned networks and addresses; an address may still be provisioning. Call \`get_payment_channel\` again to check readiness and addresses. Call \`simulate_payment_channel_deposit\` with \`payment_channel_id\`, \`amount\` as a decimal string, \`currency\`, and \`network\`; \`stage\` is optional. Read any deposit status with \`get_payment_channel_deposit\`, or use \`list_payment_channel_deposits\` for the confirmed-deposit feed.
|
|
1216
|
+
|
|
1217
|
+
If you chose both, follow both paths. Before changing an order or customer balance, verify webhook signatures, apply the flow\u2019s confirmation checks, and deduplicate events. Credit channel deposits only when \`confirmed\` and \`is_final\`.`;
|
|
1218
|
+
var RECOMMENDATIONS = {
|
|
1219
|
+
order_checkout: {
|
|
1220
|
+
recommendation: "invoice",
|
|
1221
|
+
summary: "Use an invoice for each order: it has a set amount, an expiry, payment statuses, and hosted checkout. Explain how this fits the order flow while respecting the merchant\u2019s stated preference."
|
|
1222
|
+
},
|
|
1223
|
+
repeat_deposits: {
|
|
1224
|
+
recommendation: "payment_channel",
|
|
1225
|
+
summary: "Use a payment channel for repeated deposits from one payer to reusable addresses per network. Track credited deposits separately; transfers below the minimum are not credited or returned. The channel sets no amount or expiry."
|
|
1226
|
+
},
|
|
1227
|
+
both: {
|
|
1228
|
+
recommendation: "both",
|
|
1229
|
+
summary: "Use invoices for individual orders and payment channels for repeated account top-ups. Explain which customer action uses each flow, and respect any preference the merchant has already stated."
|
|
1230
|
+
},
|
|
1231
|
+
unsure: {
|
|
1232
|
+
recommendation: "unsure",
|
|
1233
|
+
summary: "Do not choose a flow yet. Ask: \u201CWill your customer pay for each order, repeatedly top up an account, or do both?\u201D Use the answer and the merchant\u2019s preferences to guide the recommendation."
|
|
1234
|
+
}
|
|
1235
|
+
};
|
|
1236
|
+
function registerIntegrationRecommendation(server) {
|
|
1237
|
+
server.registerTool(
|
|
1238
|
+
"recommend_payment_integration",
|
|
1239
|
+
{
|
|
1240
|
+
title: "Recommend a payment integration",
|
|
1241
|
+
description: "Recommend invoices, payment channels, or both from the merchant\u2019s payment flow. Explain the fit and relevant lifecycle. When information is missing, return a targeted question instead of choosing. Respect an explicit merchant choice.",
|
|
1242
|
+
inputSchema: {
|
|
1243
|
+
scenario: z2.enum(["order_checkout", "repeat_deposits", "both", "unsure"]).optional().describe("Choose order_checkout for payment per order, repeat_deposits for repeated customer account top-ups, or both when both flows are needed. Use unsure when the payment flow is unclear; ask whether the customer pays for each order, repeatedly tops up an account, or does both. Respect the merchant\u2019s explicit choice.")
|
|
1244
|
+
},
|
|
1245
|
+
annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: false }
|
|
1246
|
+
},
|
|
1247
|
+
async ({ scenario }) => {
|
|
1248
|
+
const selected = scenario ?? "unsure";
|
|
1249
|
+
return {
|
|
1250
|
+
content: [{
|
|
1251
|
+
type: "text",
|
|
1252
|
+
text: JSON.stringify({ scenario: selected, ...RECOMMENDATIONS[selected], guide: GUIDE }, null, 2)
|
|
1253
|
+
}]
|
|
1254
|
+
};
|
|
1255
|
+
}
|
|
1256
|
+
);
|
|
1257
|
+
}
|
|
1258
|
+
|
|
1173
1259
|
// src/version.ts
|
|
1174
|
-
var MCP_VERSION = "1.
|
|
1260
|
+
var MCP_VERSION = "1.5.1";
|
|
1175
1261
|
|
|
1176
1262
|
// src/server.ts
|
|
1177
1263
|
function buildServer(gateway) {
|
|
1178
|
-
const server = new McpServer(
|
|
1264
|
+
const server = new McpServer(
|
|
1265
|
+
{ name: "paymos", version: MCP_VERSION },
|
|
1266
|
+
{ instructions: INTEGRATION_INSTRUCTIONS }
|
|
1267
|
+
);
|
|
1179
1268
|
registerTools(server, gateway);
|
|
1269
|
+
registerIntegrationRecommendation(server);
|
|
1180
1270
|
registerResources(server);
|
|
1181
1271
|
return server;
|
|
1182
1272
|
}
|
|
@@ -1184,27 +1274,85 @@ function buildServer(gateway) {
|
|
|
1184
1274
|
// src/setup.ts
|
|
1185
1275
|
import {
|
|
1186
1276
|
chmodSync,
|
|
1187
|
-
closeSync as
|
|
1277
|
+
closeSync as closeSync3,
|
|
1188
1278
|
constants as constants2,
|
|
1189
1279
|
existsSync,
|
|
1190
|
-
fstatSync as
|
|
1280
|
+
fstatSync as fstatSync3,
|
|
1191
1281
|
linkSync,
|
|
1192
|
-
lstatSync as
|
|
1193
|
-
mkdirSync,
|
|
1194
|
-
openSync as
|
|
1282
|
+
lstatSync as lstatSync3,
|
|
1283
|
+
mkdirSync as mkdirSync2,
|
|
1284
|
+
openSync as openSync3,
|
|
1195
1285
|
readFileSync as readFileSync2,
|
|
1196
1286
|
renameSync,
|
|
1197
|
-
unlinkSync,
|
|
1287
|
+
unlinkSync as unlinkSync2,
|
|
1198
1288
|
writeFileSync
|
|
1199
1289
|
} from "fs";
|
|
1200
1290
|
import { randomUUID } from "crypto";
|
|
1201
1291
|
import { homedir } from "os";
|
|
1202
|
-
import { dirname, isAbsolute, join, resolve } from "path";
|
|
1292
|
+
import { dirname as dirname2, isAbsolute, join, resolve } from "path";
|
|
1203
1293
|
import { createInterface } from "readline";
|
|
1204
1294
|
import { Writable } from "stream";
|
|
1205
1295
|
import { isDeepStrictEqual } from "util";
|
|
1206
1296
|
import { applyEdits, modify, parse as parseJson, parseTree } from "jsonc-parser";
|
|
1207
1297
|
import { parse as parseToml, stringify as stringifyToml } from "smol-toml";
|
|
1298
|
+
|
|
1299
|
+
// src/setup-lock.ts
|
|
1300
|
+
import { closeSync as closeSync2, fstatSync as fstatSync2, lstatSync as lstatSync2, mkdirSync, openSync as openSync2, unlinkSync } from "fs";
|
|
1301
|
+
import { dirname } from "path";
|
|
1302
|
+
var LOCK_SUFFIX = ".paymos-setup.lock";
|
|
1303
|
+
var STALE_LOCK_MS = 3e4;
|
|
1304
|
+
var DestinationBusyError = class extends Error {
|
|
1305
|
+
constructor() {
|
|
1306
|
+
super("Another setup is publishing to this destination.");
|
|
1307
|
+
this.name = "DestinationBusyError";
|
|
1308
|
+
}
|
|
1309
|
+
};
|
|
1310
|
+
function acquire(lock, now) {
|
|
1311
|
+
for (let attempt = 0; ; attempt++) {
|
|
1312
|
+
let fd;
|
|
1313
|
+
try {
|
|
1314
|
+
fd = openSync2(lock, "wx", 384);
|
|
1315
|
+
} catch (cause) {
|
|
1316
|
+
if (cause.code !== "EEXIST") throw cause;
|
|
1317
|
+
if (attempt > 0 || !removeIfStale(lock, now)) throw new DestinationBusyError();
|
|
1318
|
+
continue;
|
|
1319
|
+
}
|
|
1320
|
+
try {
|
|
1321
|
+
const stat = fstatSync2(fd);
|
|
1322
|
+
return { ino: stat.ino, dev: stat.dev };
|
|
1323
|
+
} finally {
|
|
1324
|
+
closeSync2(fd);
|
|
1325
|
+
}
|
|
1326
|
+
}
|
|
1327
|
+
}
|
|
1328
|
+
function removeIfStale(lock, now) {
|
|
1329
|
+
try {
|
|
1330
|
+
if (now() - lstatSync2(lock).mtimeMs < STALE_LOCK_MS) return false;
|
|
1331
|
+
unlinkSync(lock);
|
|
1332
|
+
return true;
|
|
1333
|
+
} catch (cause) {
|
|
1334
|
+
return cause.code === "ENOENT";
|
|
1335
|
+
}
|
|
1336
|
+
}
|
|
1337
|
+
function release(lock, mine) {
|
|
1338
|
+
try {
|
|
1339
|
+
const stat = lstatSync2(lock);
|
|
1340
|
+
if (stat.ino === mine.ino && stat.dev === mine.dev) unlinkSync(lock);
|
|
1341
|
+
} catch {
|
|
1342
|
+
}
|
|
1343
|
+
}
|
|
1344
|
+
function withDestinationLock(destination, action, now = Date.now) {
|
|
1345
|
+
const lock = destination + LOCK_SUFFIX;
|
|
1346
|
+
mkdirSync(dirname(lock), { recursive: true, mode: 448 });
|
|
1347
|
+
const mine = acquire(lock, now);
|
|
1348
|
+
try {
|
|
1349
|
+
return action();
|
|
1350
|
+
} finally {
|
|
1351
|
+
release(lock, mine);
|
|
1352
|
+
}
|
|
1353
|
+
}
|
|
1354
|
+
|
|
1355
|
+
// src/setup.ts
|
|
1208
1356
|
var SETUP_CLIENTS = [
|
|
1209
1357
|
"codex",
|
|
1210
1358
|
"claude-code",
|
|
@@ -1297,18 +1445,18 @@ function defaultConfigPath(client, env, context) {
|
|
|
1297
1445
|
function snapshot(path) {
|
|
1298
1446
|
let fd;
|
|
1299
1447
|
try {
|
|
1300
|
-
const stat =
|
|
1448
|
+
const stat = lstatSync3(path);
|
|
1301
1449
|
if (stat.isSymbolicLink()) error("symlink");
|
|
1302
1450
|
if (!stat.isFile() || stat.size > 4194304) error("configFile");
|
|
1303
|
-
fd =
|
|
1304
|
-
if (
|
|
1451
|
+
fd = openSync3(path, constants2.O_RDONLY | (constants2.O_NOFOLLOW ?? 0));
|
|
1452
|
+
if (fstatSync3(fd).ino !== stat.ino) error("changed");
|
|
1305
1453
|
return { path, content: readFileSync2(fd, "utf8") };
|
|
1306
1454
|
} catch (cause) {
|
|
1307
1455
|
if (cause.code === "ENOENT") return { path, content: null };
|
|
1308
1456
|
if (cause instanceof Error && Object.values(SETUP_COPY.errors).includes(cause.message)) throw cause;
|
|
1309
1457
|
return error("configFile");
|
|
1310
1458
|
} finally {
|
|
1311
|
-
if (fd !== void 0)
|
|
1459
|
+
if (fd !== void 0) closeSync3(fd);
|
|
1312
1460
|
}
|
|
1313
1461
|
}
|
|
1314
1462
|
function assertUnchanged(before) {
|
|
@@ -1381,20 +1529,20 @@ function planClientConfig(client, original, credentialsPath, platform) {
|
|
|
1381
1529
|
return next;
|
|
1382
1530
|
}
|
|
1383
1531
|
function writeConfig(before, content) {
|
|
1384
|
-
|
|
1385
|
-
const temp = join(
|
|
1532
|
+
mkdirSync2(dirname2(before.path), { recursive: true, mode: 448 });
|
|
1533
|
+
const temp = join(dirname2(before.path), `.paymos-${randomUUID()}.tmp`);
|
|
1386
1534
|
let created = false;
|
|
1387
1535
|
try {
|
|
1388
1536
|
writeFileSync(temp, content, { encoding: "utf8", mode: 384, flag: "wx" });
|
|
1389
1537
|
created = true;
|
|
1390
1538
|
if (process.platform !== "win32") chmodSync(temp, 384);
|
|
1391
|
-
const identity =
|
|
1539
|
+
const identity = lstatSync3(temp);
|
|
1392
1540
|
assertUnchanged(before);
|
|
1393
1541
|
if (before.content === null) linkSync(temp, before.path);
|
|
1394
1542
|
else renameSync(temp, before.path);
|
|
1395
1543
|
return { ino: identity.ino, dev: identity.dev };
|
|
1396
1544
|
} finally {
|
|
1397
|
-
if (created && existsSync(temp))
|
|
1545
|
+
if (created && existsSync(temp)) unlinkSync2(temp);
|
|
1398
1546
|
}
|
|
1399
1547
|
}
|
|
1400
1548
|
async function ask(io, label, secret = false) {
|
|
@@ -1476,17 +1624,20 @@ async function runSetup(argv, env = process.env, io = terminalIO(), context = {
|
|
|
1476
1624
|
}
|
|
1477
1625
|
let createdKeys;
|
|
1478
1626
|
try {
|
|
1479
|
-
|
|
1480
|
-
|
|
1481
|
-
|
|
1482
|
-
|
|
1483
|
-
|
|
1484
|
-
|
|
1627
|
+
withDestinationLock(configPath, () => {
|
|
1628
|
+
assertUnchanged(before);
|
|
1629
|
+
assertUnchanged(beforeKeys);
|
|
1630
|
+
if (stored === void 0) {
|
|
1631
|
+
createdKeys = writeConfig(beforeKeys, JSON.stringify(credentials, null, 2) + "\n");
|
|
1632
|
+
}
|
|
1633
|
+
if (before.content !== next) writeConfig(before, next);
|
|
1634
|
+
});
|
|
1485
1635
|
} catch (cause) {
|
|
1636
|
+
if (cause instanceof DestinationBusyError) error("changed");
|
|
1486
1637
|
if (createdKeys !== void 0) {
|
|
1487
1638
|
try {
|
|
1488
|
-
const stat =
|
|
1489
|
-
if (!stat.isSymbolicLink() && stat.ino === createdKeys.ino && stat.dev === createdKeys.dev && isDeepStrictEqual(readCredentialFile(credentialsPath), credentials))
|
|
1639
|
+
const stat = lstatSync3(credentialsPath);
|
|
1640
|
+
if (!stat.isSymbolicLink() && stat.ino === createdKeys.ino && stat.dev === createdKeys.dev && isDeepStrictEqual(readCredentialFile(credentialsPath), credentials)) unlinkSync2(credentialsPath);
|
|
1490
1641
|
} catch {
|
|
1491
1642
|
}
|
|
1492
1643
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@paymos/mcp",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.5.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",
|