@paymos/mcp 0.0.0-stage → 1.0.2
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 +25 -0
- package/LICENSE +21 -0
- package/README.md +198 -2
- package/dist/index.d.ts +10 -0
- package/dist/index.js +990 -0
- package/package.json +72 -4
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## [Unreleased]
|
|
4
|
+
|
|
5
|
+
## [1.0.2] - 2026-10-07
|
|
6
|
+
|
|
7
|
+
- fix(mcp): первый релиз через npm stage publish — registry не создаёт новый пакет по голому OIDC без TP, staged-флоу с approve владельца остаётся безтокенным
|
|
8
|
+
|
|
9
|
+
## [1.0.1] - 2026-10-07
|
|
10
|
+
|
|
11
|
+
- fix(mcp): lock пересобран из registry (@paymos/sdk 2.1.1) — в lock осталась файловая ссылка resolved:../typescript-sdk с восстановления, из-за неё tsc в CI-зеркале не находил SDK (v1.0.0 тег опубликован с битым билдом, рабочий релиз — v1.0.1)
|
|
12
|
+
|
|
13
|
+
## [1.0.0] - 2026-09-28
|
|
14
|
+
|
|
15
|
+
- Initial release: local stdio MCP server for the Paymos Merchant API.
|
|
16
|
+
- Six tools with frozen public contracts: `create_invoice`, `get_invoice`,
|
|
17
|
+
`list_invoices`, `cancel_invoice`, `simulate_invoice_payment`,
|
|
18
|
+
`verify_webhook_signature`.
|
|
19
|
+
- Structural sandbox gate: test key pairs (`pk_test_`/`sk_test_`) only; live
|
|
20
|
+
(`pk_live_`/`sk_live_`) and payout (`rk_`) keys refused at startup and on every
|
|
21
|
+
call with `paymos/sandbox-only`.
|
|
22
|
+
- Five doc resources generated from the Paymos docs corpus at build time:
|
|
23
|
+
quick-start, hosted-checkout, webhooks, testing-sandbox, server-sdks.
|
|
24
|
+
- Credentials via `PAYMOS_API_KEY_ID`/`PAYMOS_API_SECRET` env (flags
|
|
25
|
+
`--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
|
-
#
|
|
1
|
+
# @paymos/mcp
|
|
2
2
|
|
|
3
|
-
|
|
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).
|
package/dist/index.d.ts
ADDED
|
@@ -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 };
|