@paymos/mcp 1.5.1 → 1.7.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 CHANGED
@@ -2,6 +2,22 @@
2
2
 
3
3
  ## [Unreleased]
4
4
 
5
+ ## [1.7.0] - 2026-11-19
6
+
7
+ - fix(mcp): build dist before tests in clean release preflight
8
+ - feat(mcp): universal one-command OAuth connect across AI clients
9
+ - fix(mcp): CLI --file flag for Node 22+, WebBackend PaymentChannels config, and full live E2E evidence
10
+
11
+ - feat(mcp): connect a merchant account from Codex or Claude Code through Paymos OAuth, with Owner consent and dashboard connection management
12
+ - feat(mcp): add proof-bound `install-secret`, `upload-file`, and `download-file` helpers alongside local Sandbox
13
+
14
+ ## [1.6.0] - 2026-11-18
15
+
16
+ - feat(mcp): implement merchant-mcp-phase2 OAuth 2.1 host, dashboard parity, and CLI
17
+
18
+ - feat(mcp): connect a merchant account from Codex or Claude Code through Paymos OAuth, with Owner consent and dashboard connection management
19
+ - feat(mcp): add proof-bound `install-secret`, `upload-file`, and `download-file` helpers alongside local Sandbox
20
+
5
21
  ## [1.5.1] - 2026-11-13
6
22
 
7
23
  - fix(plugins,publicweb): SDK webhook credit recipes, CMS recovery, redirects and CSP logs (audit 2026-11-13)
package/README.md CHANGED
@@ -1,18 +1,72 @@
1
1
  # @paymos/mcp
2
2
 
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.
3
+ Paymos offers a local Sandbox server for integration testing and a hosted MCP connection for your merchant account.
4
4
 
5
- The local MCP server connects your coding agent to the Paymos sandbox with 14 tools and five documentation resources for testing merchant integrations.
5
+ ## Connect a merchant account
6
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.
7
+ Connect any supported AI IDE or CLI to your Paymos merchant account with one command and no API keys:
8
8
 
9
- ## Requirements
9
+ ```bash
10
+ npx -y @paymos/mcp auth
11
+ ```
12
+
13
+ `auth` automatically detects installed clients (`antigravity`, `claude-code`, `codex`, `kimi`, `zcode`/`glm`, `cursor`, `windsurf`, `opencode`, `claude-desktop`, and project `.vscode`), opens Paymos in your browser for OAuth 2.1 PKCE `S256` sign-in (`merchant:mcp` and `offline_access`), saves your OAuth session under OS-protected permissions outside IDE configs (`%APPDATA%\Paymos\mcp\merchant-oauth.json` on Windows, `$XDG_CONFIG_HOME/paymos/mcp/merchant-oauth.json` on Unix), and configures the local stdio OAuth bridge (`@paymos/mcp connect`). If a local Sandbox entry already occupies `paymos`, Merchant MCP is configured side-by-side as `paymos-merchant`.
14
+
15
+ Dashboard → Developers → Agents shows connection status, activity, recent operations and the Disconnect action.
16
+
17
+ ### Paymos command
18
+
19
+ ```bash
20
+ npx -y @paymos/mcp auth
21
+ npx -y @paymos/mcp auth --client antigravity
22
+ npx -y @paymos/mcp auth --client glm
23
+ npx -y @paymos/mcp auth --client codex
24
+ npx -y @paymos/mcp auth --client claude-code
25
+ ```
26
+
27
+ Options for `auth`:
28
+ - `--client NAME`: `codex`, `claude-code`, `claude-desktop`, `antigravity`, `kimi`, `zcode` (or alias `glm`), `cursor`, `windsurf`, `opencode`, `vscode`, or `generic`
29
+ - `--config PATH`: explicit client configuration path (required for `generic`)
30
+ - `--origin URL`: custom Paymos origin (`https://...` or loopback `http://127.0.0.1` / `http://localhost`, default `https://app.paymos.io`)
31
+ - `--token-file PATH`: custom OAuth token store path
32
+ - `--no-login`: write client configurations without opening browser login
33
+ - `--dry-run`: preview target files without signing in or writing
34
+
35
+ ### Local OAuth bridge (`connect`)
36
+
37
+ Configured clients launch `npx -y @paymos/mcp connect` (or `cmd /d /c npx -y @paymos/mcp connect` on Windows). `connect` responds to MCP startup requests (`initialize`, `ping`, `tools/list`, `resources/list`, `prompts/list`) locally without blocking IDE startup, triggers browser OAuth lazily on `tools/call` when needed, and transparently refreshes expired access tokens.
38
+
39
+ ### Direct URL connectors (cloud / native OAuth clients)
40
+
41
+ Clients that connect directly over Streamable HTTP OAuth 2.1 + DCR can use:
42
+
43
+ - URL `https://app.paymos.io/connect/merchant-mcp`
44
+ - OAuth scopes `merchant:mcp` and `offline_access`
45
+
46
+ ### Key and file delivery
47
+
48
+ The merchant tools can create and rotate Payment and Payout credentials under the merchant’s access policy. The tools return a short-lived installer ticket. The installer uses a verifier generated on the destination machine to exchange the ticket and save the credentials into the chosen environment file.
49
+
50
+ ```bash
51
+ paymos install-secret --prepare --file .env --merchant-id "$PAYMOS_MERCHANT_ID" --environment production --operation-id "$PAYMOS_OPERATION_ID"
52
+ paymos install-secret --file .env --request-id "$PAYMOS_REQUEST_ID" --token "$PAYMOS_INSTALLER_TICKET"
53
+ ```
54
+
55
+ Pass the first command’s `request_id` and `challenge` as the tool’s `delivery` input with the same merchant, environment and operation ID. Run the second command on the same machine with the returned ticket. For private exports and staged logo or avatar uploads, the `download-file` and `upload-file` helpers use the same prepare-and-redeem flow with `--file`. Upload preparation also supplies the file size, content type and hash.
56
+
57
+ Withdrawals follow the merchant’s current policy and native approval rules. Manage withdrawal whitelist addresses from the dashboard.
58
+
59
+ ## Local Sandbox
60
+
61
+ The local stdio server provides 14 tools and five documentation resources for creating and simulating test invoices, checking invoice states and verifying webhook signatures. It signs API requests with the official SDK using a test Payment key pair.
62
+
63
+ ### Requirements
10
64
 
11
65
  - Requires Node.js 22.12 or later.
12
66
  - A Paymos merchant account with a test key pair from Dashboard → Developer → API Keys (`pk_test_…` and `sk_test_…`)
13
67
  - An MCP client that can launch a local stdio server
14
68
 
15
- ## Setup
69
+ ### Setup the local server
16
70
 
17
71
  Run:
18
72
 
@@ -33,7 +87,9 @@ npx -y @paymos/mcp setup --client codex
33
87
  | Codex | `codex` | `$CODEX_HOME/config.toml` or `~/.codex/config.toml` |
34
88
  | Claude Code | `claude-code` | `~/.claude.json` |
35
89
  | Claude Desktop | `claude-desktop` | Claude's macOS or Windows configuration |
90
+ | Antigravity | `antigravity` | `~/.gemini/config/mcp_config.json` |
36
91
  | Kimi CLI | `kimi` | `$KIMI_CODE_HOME/mcp.json` or `~/.kimi-code/mcp.json` |
92
+ | ZCode / GLM | `zcode` (alias `glm`) | `~/.zcode/cli/config.json` |
37
93
  | Cursor | `cursor` | `~/.cursor/mcp.json` |
38
94
  | Windsurf | `windsurf` | `~/.codeium/windsurf/mcp_config.json` |
39
95
  | OpenCode | `opencode` | `OPENCODE_CONFIG`, or the user configuration under `$XDG_CONFIG_HOME/opencode` or `~/.config/opencode` |
@@ -216,8 +272,6 @@ The server opens no network listener and calls the Merchant API through `@paymos
216
272
 
217
273
  Live (`pk_live_`/`sk_live_`) and payout (`rk_…`) keys are rejected during setup, at server startup, and on tool calls. After checking your integration in the sandbox, run your own application with its live keys. This local MCP server stays outside production payment paths.
218
274
 
219
- Hosted MCP is deferred and is not available as a connection method.
220
-
221
275
  ## Development
222
276
 
223
277
  ```bash