@paymos/mcp 1.6.0 → 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.
Files changed (4) hide show
  1. package/CHANGELOG.md +9 -0
  2. package/README.md +29 -30
  3. package/dist/index.js +13606 -1018
  4. package/package.json +3 -3
package/CHANGELOG.md CHANGED
@@ -2,6 +2,15 @@
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
+
5
14
  ## [1.6.0] - 2026-11-18
6
15
 
7
16
  - feat(mcp): implement merchant-mcp-phase2 OAuth 2.1 host, dashboard parity, and CLI
package/README.md CHANGED
@@ -4,55 +4,52 @@ Paymos offers a local Sandbox server for integration testing and a hosted MCP co
4
4
 
5
5
  ## Connect a merchant account
6
6
 
7
- Use the hosted Streamable HTTP URL when Merchant MCP is enabled for your Paymos instance.
7
+ Connect any supported AI IDE or CLI to your Paymos merchant account with one command and no API keys:
8
8
 
9
- - URL `https://app.paymos.io/connect/merchant-mcp`
10
- - OAuth scopes `merchant:mcp` and `offline_access`
9
+ ```bash
10
+ npx -y @paymos/mcp auth
11
+ ```
11
12
 
12
- Start sign-in from the MCP settings or your terminal. Paymos opens in your browser. The account owner chooses the merchant and environments, reviews the access being granted, and confirms. The client stores its OAuth session and can then call the merchant tools. Dashboard → Developers → Agents shows connection status, activity, recent operations and the Disconnect action.
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.
13
16
 
14
17
  ### Paymos command
15
18
 
16
19
  ```bash
17
- paymos auth --client codex
18
- paymos auth --client claude-code
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
19
25
  ```
20
26
 
21
- With the npm package, run `npx -y @paymos/mcp auth --client codex`. The helper adds the hosted entry and starts the native browser flow. It uses `paymos-merchant` when `paymos` is already the Sandbox entry.
22
-
23
- ### Codex
24
-
25
- In MCP settings, add Paymos as a Streamable HTTP server and choose Authenticate. For a pre-registered OAuth client, set the following in your Codex `config.toml`.
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
26
34
 
27
- ```toml
28
- [mcp_servers.paymos]
29
- url = "https://app.paymos.io/connect/merchant-mcp"
30
- scopes = ["merchant:mcp", "offline_access"]
31
-
32
- [mcp_servers.paymos.oauth]
33
- client_id = "paymos-merchant-codex"
34
- callback_port = 33419
35
- callback_url = "http://127.0.0.1:33419/callback"
36
- ```
35
+ ### Local OAuth bridge (`connect`)
37
36
 
38
- Run `codex mcp login paymos`. Use the same listener port and callback URL. For a coexisting Sandbox entry, use `paymos-merchant` in both the configuration and the login command. [Codex MCP configuration](https://learn.chatgpt.com/docs/config-file/config-reference)
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.
39
38
 
40
- ### Claude Code
39
+ ### Direct URL connectors (cloud / native OAuth clients)
41
40
 
42
- ```bash
43
- claude mcp add --transport http --scope user --client-id paymos-merchant-claude-code --callback-port 33420 paymos https://app.paymos.io/connect/merchant-mcp
44
- claude mcp login paymos
45
- ```
41
+ Clients that connect directly over Streamable HTTP OAuth 2.1 + DCR can use:
46
42
 
47
- You can also select Paymos → Authenticate in Claude Code’s `/mcp` panel. When a local Paymos Sandbox entry already occupies the name, use `paymos-merchant` in both commands. Clients with public OAuth discovery and native loopback dynamic registration can use the hosted URL directly. [Claude Code MCP sign-in](https://code.claude.com/docs/en/mcp#authenticate-from-the-command-line)
43
+ - URL `https://app.paymos.io/connect/merchant-mcp`
44
+ - OAuth scopes `merchant:mcp` and `offline_access`
48
45
 
49
46
  ### Key and file delivery
50
47
 
51
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.
52
49
 
53
50
  ```bash
54
- paymos install-secret --prepare --env-file .env --merchant-id "$PAYMOS_MERCHANT_ID" --environment production --operation-id "$PAYMOS_OPERATION_ID"
55
- paymos install-secret --env-file .env --request-id "$PAYMOS_REQUEST_ID" --token "$PAYMOS_INSTALLER_TICKET"
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"
56
53
  ```
57
54
 
58
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.
@@ -90,7 +87,9 @@ npx -y @paymos/mcp setup --client codex
90
87
  | Codex | `codex` | `$CODEX_HOME/config.toml` or `~/.codex/config.toml` |
91
88
  | Claude Code | `claude-code` | `~/.claude.json` |
92
89
  | Claude Desktop | `claude-desktop` | Claude's macOS or Windows configuration |
90
+ | Antigravity | `antigravity` | `~/.gemini/config/mcp_config.json` |
93
91
  | Kimi CLI | `kimi` | `$KIMI_CODE_HOME/mcp.json` or `~/.kimi-code/mcp.json` |
92
+ | ZCode / GLM | `zcode` (alias `glm`) | `~/.zcode/cli/config.json` |
94
93
  | Cursor | `cursor` | `~/.cursor/mcp.json` |
95
94
  | Windsurf | `windsurf` | `~/.codeium/windsurf/mcp_config.json` |
96
95
  | OpenCode | `opencode` | `OPENCODE_CONFIG`, or the user configuration under `$XDG_CONFIG_HOME/opencode` or `~/.config/opencode` |