@paymos/mcp 0.0.0-stage → 1.1.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 ADDED
@@ -0,0 +1,33 @@
1
+ # Changelog
2
+
3
+ ## [Unreleased]
4
+
5
+ ## [1.1.1] - 2026-10-07
6
+
7
+ - fix(mcp): repository.url/bugs с канон-кейсом Paymos-labs — npm provenance строго мэтчит регистр (E422 на v1.1.0)
8
+
9
+ ## [1.1.0] - 2026-10-07
10
+
11
+ - feat(mcp): trusted publisher зарегистрирован (Paymos-labs/mcp + publish.yml) — возврат на обычный npm publish, контрольный релиз валидирует TP по OIDC
12
+
13
+ ## [1.0.2] - 2026-10-07
14
+
15
+ - fix(mcp): первый релиз через npm stage publish — registry не создаёт новый пакет по голому OIDC без TP, staged-флоу с approve владельца остаётся безтокенным
16
+
17
+ ## [1.0.1] - 2026-10-07
18
+
19
+ - fix(mcp): lock пересобран из registry (@paymos/sdk 2.1.1) — в lock осталась файловая ссылка resolved:../typescript-sdk с восстановления, из-за неё tsc в CI-зеркале не находил SDK (v1.0.0 тег опубликован с битым билдом, рабочий релиз — v1.0.1)
20
+
21
+ ## [1.0.0] - 2026-09-28
22
+
23
+ - Initial release: local stdio MCP server for the Paymos Merchant API.
24
+ - Six tools with frozen public contracts: `create_invoice`, `get_invoice`,
25
+ `list_invoices`, `cancel_invoice`, `simulate_invoice_payment`,
26
+ `verify_webhook_signature`.
27
+ - Structural sandbox gate: test key pairs (`pk_test_`/`sk_test_`) only; live
28
+ (`pk_live_`/`sk_live_`) and payout (`rk_`) keys refused at startup and on every
29
+ call with `paymos/sandbox-only`.
30
+ - Five doc resources generated from the Paymos docs corpus at build time:
31
+ quick-start, hosted-checkout, webhooks, testing-sandbox, server-sdks.
32
+ - Credentials via `PAYMOS_API_KEY_ID`/`PAYMOS_API_SECRET` env (flags
33
+ `--api-key-id`/`--api-secret` as fallback); optional `PAYMOS_WEBHOOK_SECRET`.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Paymos Labs
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,199 @@
1
- # Temporary Holding Version
1
+ # @paymos/mcp
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ The official Paymos MCP server. A local stdio server: your coding agent — Claude
4
+ Code, Cursor, or your own LLM bot — builds and verifies a Paymos merchant integration
5
+ in minutes. It creates sandbox invoices, opens the payment URL, simulates payment,
6
+ watches the status turn `paid`, verifies webhook signatures, then writes the
7
+ production integration around `@paymos/sdk` for you. No docs to read, no skeleton code
8
+ to copy.
9
+
10
+ Sandbox only in v1: the server accepts test key pairs (`pk_test_` / `sk_test_`) and
11
+ refuses live and payout keys with a clear error. Live operation arrives with the
12
+ hosted `mcp.paymos.io` (phase 2).
13
+
14
+ ## Requirements
15
+
16
+ - Node.js ≥ 20
17
+ - A Paymos merchant account with a test key pair: **Dashboard → Developers → API
18
+ keys**
19
+
20
+ ## Install
21
+
22
+ Nothing to install globally — run it through `npx` from your MCP client config.
23
+
24
+ ## Configure
25
+
26
+ Credentials come from the environment (the `--api-key-id` / `--api-secret` flags also
27
+ work; the environment wins on conflict):
28
+
29
+ | Env | Meaning |
30
+ |---|---|
31
+ | `PAYMOS_API_KEY_ID` | Test key id, `pk_test_…` |
32
+ | `PAYMOS_API_SECRET` | Test secret, `sk_test_…` |
33
+ | `PAYMOS_WEBHOOK_SECRET` | Optional `whsec_…` for `verify_webhook_signature` |
34
+
35
+ ### Claude Code
36
+
37
+ ```json
38
+ {
39
+ "mcpServers": {
40
+ "paymos": {
41
+ "command": "npx",
42
+ "args": ["-y", "@paymos/mcp"],
43
+ "env": {
44
+ "PAYMOS_API_KEY_ID": "pk_test_…",
45
+ "PAYMOS_API_SECRET": "sk_test_…",
46
+ "PAYMOS_WEBHOOK_SECRET": "whsec_…"
47
+ }
48
+ }
49
+ }
50
+ }
51
+ ```
52
+
53
+ ### Claude Desktop
54
+
55
+ Same `mcpServers` block in `claude_desktop_config.json` — Claude → Settings →
56
+ Developer → Edit Config (macOS:
57
+ `~/Library/Application Support/Claude/claude_desktop_config.json`, Windows:
58
+ `%APPDATA%\Claude\claude_desktop_config.json`).
59
+
60
+ ### Cursor
61
+
62
+ `~/.cursor/mcp.json` (or `.cursor/mcp.json` in the project) uses the same shape:
63
+
64
+ ```json
65
+ {
66
+ "mcpServers": {
67
+ "paymos": {
68
+ "command": "npx",
69
+ "args": ["-y", "@paymos/mcp"],
70
+ "env": {
71
+ "PAYMOS_API_KEY_ID": "pk_test_…",
72
+ "PAYMOS_API_SECRET": "sk_test_…"
73
+ }
74
+ }
75
+ }
76
+ }
77
+ ```
78
+
79
+ ### Windsurf
80
+
81
+ Same `mcpServers` block in `~/.codeium/windsurf/mcp_config.json`.
82
+
83
+ ### Cline / Roo Code
84
+
85
+ Same `mcpServers` block in `cline_mcp_settings.json` for Cline and
86
+ `roo_mcp_settings.json` for Roo Code (MCP Servers → Configure in the extension).
87
+
88
+ ### VS Code (Copilot)
89
+
90
+ `.vscode/mcp.json` (or the user-level `mcp.json`) wraps the entry in `servers`
91
+ with an explicit transport type:
92
+
93
+ ```json
94
+ {
95
+ "servers": {
96
+ "paymos": {
97
+ "type": "stdio",
98
+ "command": "npx",
99
+ "args": ["-y", "@paymos/mcp"],
100
+ "env": {
101
+ "PAYMOS_API_KEY_ID": "pk_test_…",
102
+ "PAYMOS_API_SECRET": "sk_test_…"
103
+ }
104
+ }
105
+ }
106
+ }
107
+ ```
108
+
109
+ ### Zed
110
+
111
+ `~/.zed/settings.json`, same fields under `context_servers`:
112
+
113
+ ```json
114
+ {
115
+ "context_servers": {
116
+ "paymos": {
117
+ "command": "npx",
118
+ "args": ["-y", "@paymos/mcp"],
119
+ "env": {
120
+ "PAYMOS_API_KEY_ID": "pk_test_…",
121
+ "PAYMOS_API_SECRET": "sk_test_…"
122
+ }
123
+ }
124
+ }
125
+ }
126
+ ```
127
+
128
+ ### GLM (Z.ai)
129
+
130
+ GLM Coding Plan plugs into Claude Code as its model backend (see the Z.ai docs
131
+ for the Claude Code endpoint setup). Once Claude Code runs on GLM, add the
132
+ `paymos` server with the Claude Code config above — the MCP layer is identical.
133
+
134
+ ### ChatGPT
135
+
136
+ The ChatGPT app and web chat cannot launch local stdio servers; they talk to
137
+ remote MCP servers over HTTP. The hosted `mcp.paymos.io` (phase 2) will cover
138
+ ChatGPT and other hosted clients. Developers building on the OpenAI Agents SDK
139
+ can mount this stdio server in their own agent code today.
140
+
141
+ ### Generic MCP client
142
+
143
+ Any client that speaks MCP over stdio: command `npx`, args `["-y", "@paymos/mcp"]`,
144
+ env as above.
145
+
146
+ ## Tools (frozen public surface)
147
+
148
+ Names and schemas are fixed from 1.0.0 — breaking changes mean a new major version.
149
+
150
+ | Tool | What it does |
151
+ |---|---|
152
+ | `create_invoice` | Creates a sandbox invoice; idempotent per `external_order_id`; returns `payment_url` |
153
+ | `get_invoice` | Fetches the current invoice state |
154
+ | `list_invoices` | One cursor page of invoices with filters (status, dates, order id) |
155
+ | `cancel_invoice` | Cancels an unpaid invoice with a stored reason |
156
+ | `simulate_invoice_payment` | Sandbox only: drives an invoice through `paid` / `overpaid` / `underpay` / `cancel` |
157
+ | `verify_webhook_signature` | Locally verifies `X-Webhook-Signature` against a raw webhook body |
158
+
159
+ Tool errors are `{ "code": "paymos/<api_error_code>", "message": "…" }`; the gate
160
+ refusals use `paymos/sandbox-only`, `paymos/missing-credentials` and
161
+ `paymos/invalid-credentials`.
162
+
163
+ ## Resources
164
+
165
+ Five static doc pages are served as MCP resources so the agent never leaves the
166
+ session: `paymos://docs/quick-start`, `paymos://docs/hosted-checkout`,
167
+ `paymos://docs/webhooks`, `paymos://docs/testing-sandbox`,
168
+ `paymos://docs/server-sdks`.
169
+
170
+ ## Security notes
171
+
172
+ - stdio only: no network listener is opened; the server talks to
173
+ `https://api.paymos.io` exclusively through `@paymos/sdk`.
174
+ - The secret never appears in logs, stdout or error text.
175
+ - Live (`pk_live_`/`sk_live_`) and payout (`rk_…`) keys are refused at startup and on
176
+ every call: `paymos/sandbox-only`.
177
+
178
+ ## FAQ
179
+
180
+ **Can my agent move real money?** No. v1 is deliberately sandbox-only. When the agent
181
+ has written and verified your integration, your own code goes live with your live keys
182
+ — the MCP server stays out of production paths.
183
+
184
+ **Why does my live key pair fail?** By design. Create a test pair in Dashboard →
185
+ Developers → API keys.
186
+
187
+ **Is there a hosted version?** Phase 2: `mcp.paymos.io` with OAuth 2.1 login, agent
188
+ entities with scoped keys, and live operation.
189
+
190
+ ## Development
191
+
192
+ ```bash
193
+ npm install # deps (@paymos/sdk resolves from ../typescript-sdk)
194
+ npm run build:resources # regenerate doc resources from the docs corpus
195
+ npm test # vitest suite incl. the contract-freeze snapshot
196
+ npm run build # tsup bundle to dist/
197
+ ```
198
+
199
+ License: MIT — see [LICENSE](LICENSE).
@@ -0,0 +1,10 @@
1
+ #!/usr/bin/env node
2
+ /**
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
6
+ * JSON-RPC channel, and no line ever contains the secret.
7
+ */
8
+ declare function main(env?: Readonly<Record<string, string | undefined>>, argv?: readonly string[]): Promise<void>;
9
+
10
+ export { main };