recurly-mcp 0.1.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 +61 -0
- package/LICENSE +21 -0
- package/README.md +179 -0
- package/dist/bin.d.ts +2 -0
- package/dist/bin.js +19 -0
- package/dist/bin.js.map +1 -0
- package/dist/client/errors.d.ts +16 -0
- package/dist/client/errors.js +44 -0
- package/dist/client/errors.js.map +1 -0
- package/dist/client/pagination.d.ts +8 -0
- package/dist/client/pagination.js +33 -0
- package/dist/client/pagination.js.map +1 -0
- package/dist/client/recurly.d.ts +19 -0
- package/dist/client/recurly.js +277 -0
- package/dist/client/recurly.js.map +1 -0
- package/dist/config.d.ts +9 -0
- package/dist/config.js +99 -0
- package/dist/config.js.map +1 -0
- package/dist/responseGuard.d.ts +1 -0
- package/dist/responseGuard.js +124 -0
- package/dist/responseGuard.js.map +1 -0
- package/dist/server.d.ts +7 -0
- package/dist/server.js +119 -0
- package/dist/server.js.map +1 -0
- package/dist/tools/accounts.d.ts +217 -0
- package/dist/tools/accounts.js +71 -0
- package/dist/tools/accounts.js.map +1 -0
- package/dist/tools/addOns.d.ts +46 -0
- package/dist/tools/addOns.js +24 -0
- package/dist/tools/addOns.js.map +1 -0
- package/dist/tools/billingInfo.d.ts +57 -0
- package/dist/tools/billingInfo.js +31 -0
- package/dist/tools/billingInfo.js.map +1 -0
- package/dist/tools/businessEntities.d.ts +80 -0
- package/dist/tools/businessEntities.js +32 -0
- package/dist/tools/businessEntities.js.map +1 -0
- package/dist/tools/couponRedemptions.d.ts +135 -0
- package/dist/tools/couponRedemptions.js +57 -0
- package/dist/tools/couponRedemptions.js.map +1 -0
- package/dist/tools/coupons.d.ts +86 -0
- package/dist/tools/coupons.js +37 -0
- package/dist/tools/coupons.js.map +1 -0
- package/dist/tools/creditPayments.d.ts +73 -0
- package/dist/tools/creditPayments.js +28 -0
- package/dist/tools/creditPayments.js.map +1 -0
- package/dist/tools/customFieldDefinitions.d.ts +46 -0
- package/dist/tools/customFieldDefinitions.js +32 -0
- package/dist/tools/customFieldDefinitions.js.map +1 -0
- package/dist/tools/dunningCampaigns.d.ts +42 -0
- package/dist/tools/dunningCampaigns.js +21 -0
- package/dist/tools/dunningCampaigns.js.map +1 -0
- package/dist/tools/exports.d.ts +20 -0
- package/dist/tools/exports.js +21 -0
- package/dist/tools/exports.js.map +1 -0
- package/dist/tools/externalAccounts.d.ts +48 -0
- package/dist/tools/externalAccounts.js +28 -0
- package/dist/tools/externalAccounts.js.map +1 -0
- package/dist/tools/externalInvoices.d.ts +73 -0
- package/dist/tools/externalInvoices.js +28 -0
- package/dist/tools/externalInvoices.js.map +1 -0
- package/dist/tools/externalProducts.d.ts +85 -0
- package/dist/tools/externalProducts.js +34 -0
- package/dist/tools/externalProducts.js.map +1 -0
- package/dist/tools/externalSubscriptions.d.ts +147 -0
- package/dist/tools/externalSubscriptions.js +47 -0
- package/dist/tools/externalSubscriptions.js.map +1 -0
- package/dist/tools/generalLedgerAccounts.d.ts +46 -0
- package/dist/tools/generalLedgerAccounts.js +32 -0
- package/dist/tools/generalLedgerAccounts.js.map +1 -0
- package/dist/tools/giftCards.d.ts +42 -0
- package/dist/tools/giftCards.js +21 -0
- package/dist/tools/giftCards.js.map +1 -0
- package/dist/tools/index.d.ts +2 -0
- package/dist/tools/index.js +68 -0
- package/dist/tools/index.js.map +1 -0
- package/dist/tools/invoiceTemplates.d.ts +83 -0
- package/dist/tools/invoiceTemplates.js +39 -0
- package/dist/tools/invoiceTemplates.js.map +1 -0
- package/dist/tools/invoices.d.ts +168 -0
- package/dist/tools/invoices.js +58 -0
- package/dist/tools/invoices.js.map +1 -0
- package/dist/tools/items.d.ts +46 -0
- package/dist/tools/items.js +24 -0
- package/dist/tools/items.js.map +1 -0
- package/dist/tools/lineItems.d.ts +93 -0
- package/dist/tools/lineItems.js +37 -0
- package/dist/tools/lineItems.js.map +1 -0
- package/dist/tools/measuredUnits.d.ts +46 -0
- package/dist/tools/measuredUnits.js +24 -0
- package/dist/tools/measuredUnits.js.map +1 -0
- package/dist/tools/performanceObligations.d.ts +42 -0
- package/dist/tools/performanceObligations.js +24 -0
- package/dist/tools/performanceObligations.js.map +1 -0
- package/dist/tools/plans.d.ts +93 -0
- package/dist/tools/plans.js +34 -0
- package/dist/tools/plans.js.map +1 -0
- package/dist/tools/priceSegments.d.ts +42 -0
- package/dist/tools/priceSegments.js +21 -0
- package/dist/tools/priceSegments.js.map +1 -0
- package/dist/tools/request.d.ts +17 -0
- package/dist/tools/request.js +55 -0
- package/dist/tools/request.js.map +1 -0
- package/dist/tools/shared.d.ts +32 -0
- package/dist/tools/shared.js +73 -0
- package/dist/tools/shared.js.map +1 -0
- package/dist/tools/shippingAddresses.d.ts +48 -0
- package/dist/tools/shippingAddresses.js +28 -0
- package/dist/tools/shippingAddresses.js.map +1 -0
- package/dist/tools/shippingMethods.d.ts +42 -0
- package/dist/tools/shippingMethods.js +21 -0
- package/dist/tools/shippingMethods.js.map +1 -0
- package/dist/tools/sites.d.ts +46 -0
- package/dist/tools/sites.js +24 -0
- package/dist/tools/sites.js.map +1 -0
- package/dist/tools/subscriptions.d.ts +178 -0
- package/dist/tools/subscriptions.js +68 -0
- package/dist/tools/subscriptions.js.map +1 -0
- package/dist/tools/transactions.d.ts +87 -0
- package/dist/tools/transactions.js +36 -0
- package/dist/tools/transactions.js.map +1 -0
- package/dist/tools/types.d.ts +13 -0
- package/dist/tools/types.js +2 -0
- package/dist/tools/types.js.map +1 -0
- package/dist/tools/usage.d.ts +52 -0
- package/dist/tools/usage.js +33 -0
- package/dist/tools/usage.js.map +1 -0
- package/package.json +77 -0
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to `recurly-mcp` will be documented in this file.
|
|
4
|
+
|
|
5
|
+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
6
|
+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
|
+
|
|
8
|
+
## [Unreleased]
|
|
9
|
+
|
|
10
|
+
## [0.1.0] — 2026-06-03
|
|
11
|
+
|
|
12
|
+
Initial release. A **read-only** MCP server with feature parity on every `GET`
|
|
13
|
+
endpoint of the Recurly v2021-02-25 API — 30 resource-grouped tools covering all
|
|
14
|
+
97 read operations, plus a generic `recurly_request` escape hatch.
|
|
15
|
+
|
|
16
|
+
### Added
|
|
17
|
+
|
|
18
|
+
- **30 resource tools** (`recurly_sites`, `recurly_accounts`, `recurly_billing_info`,
|
|
19
|
+
`recurly_shipping_addresses`, `recurly_coupons`, `recurly_coupon_redemptions`,
|
|
20
|
+
`recurly_credit_payments`, `recurly_invoices`, `recurly_line_items`,
|
|
21
|
+
`recurly_subscriptions`, `recurly_transactions`, `recurly_custom_field_definitions`,
|
|
22
|
+
`recurly_items`, `recurly_measured_units`, `recurly_plans`, `recurly_add_ons`,
|
|
23
|
+
`recurly_shipping_methods`, `recurly_usage`, `recurly_export`,
|
|
24
|
+
`recurly_dunning_campaigns`, `recurly_invoice_templates`, `recurly_external_products`,
|
|
25
|
+
`recurly_external_subscriptions`, `recurly_external_invoices`, `recurly_external_accounts`,
|
|
26
|
+
`recurly_general_ledger_accounts`, `recurly_performance_obligations`,
|
|
27
|
+
`recurly_price_segments`, `recurly_business_entities`, `recurly_gift_cards`) — each a
|
|
28
|
+
discriminated union of read-only actions returning the raw Recurly JSON payload.
|
|
29
|
+
- `recurly_request` — escape hatch for any Recurly API path. Read-only: only `GET`
|
|
30
|
+
is supported, with path-traversal and header-injection guards.
|
|
31
|
+
- HTTP client: HTTP Basic auth (private API key), `Accept: application/vnd.recurly.<version>`,
|
|
32
|
+
comma-separated array query params, retries on 429 (honoring `Retry-After`, including the
|
|
33
|
+
HTTP-date form) and 5xx with equal-jitter exponential backoff, a 25 MB response cap, and
|
|
34
|
+
base64 wrapping of binary responses (invoice PDFs).
|
|
35
|
+
- Read-only by construction: the client's only HTTP method is `GET`. No mutating code path.
|
|
36
|
+
- Cursor pagination: `limit`/`order`/`sort`/`cursor`/`ids`/`begin_time`/`end_time` plus
|
|
37
|
+
per-resource filters; responses gain a `_pagination` hint with `next_cursor`.
|
|
38
|
+
- US/EU region selection (`RECURLY_REGION`), host override (`RECURLY_HOST`), configurable
|
|
39
|
+
timeout and retries; startup warning when `RECURLY_API_KEY` is unset.
|
|
40
|
+
- `npm run validate` — spawns the built server and validates every tool's `inputSchema`
|
|
41
|
+
against MCP/Claude constraints (top-level `type: "object"`, no top-level
|
|
42
|
+
`anyOf`/`oneOf`/`allOf`).
|
|
43
|
+
- CI on Node 20 + 22: `npm audit --audit-level=high`, lint, typecheck, test (154 tests), build, validate.
|
|
44
|
+
|
|
45
|
+
### Security
|
|
46
|
+
|
|
47
|
+
- Path parameters are URL-encoded and reject `.`/`..` segments; the `recurly_request`
|
|
48
|
+
path rejects `..` traversal (raw or percent-encoded) and requires a leading `/`.
|
|
49
|
+
- User-supplied headers are lowercased and the reserved set
|
|
50
|
+
(`authorization`/`host`/`cookie`) is stripped before the canonical Basic auth header
|
|
51
|
+
is attached; header values with CR/LF are rejected.
|
|
52
|
+
- `RECURLY_HOST` must be a parseable `http:`/`https:` URL; warns on `http:`.
|
|
53
|
+
- A server-supplied `Retry-After` is capped at 60 s to prevent a stall holding the API key.
|
|
54
|
+
|
|
55
|
+
### Notes
|
|
56
|
+
|
|
57
|
+
This is an **unofficial** project, not affiliated with or endorsed by Recurly. It mirrors
|
|
58
|
+
the structure of [airbrake-mcp](https://github.com/francktrouillez/airbrake-mcp).
|
|
59
|
+
|
|
60
|
+
[Unreleased]: https://github.com/francktrouillez/recurly-mcp/compare/v0.1.0...HEAD
|
|
61
|
+
[0.1.0]: https://github.com/francktrouillez/recurly-mcp/releases/tag/v0.1.0
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Franck Trouillez
|
|
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
ADDED
|
@@ -0,0 +1,179 @@
|
|
|
1
|
+
# recurly-mcp
|
|
2
|
+
|
|
3
|
+
[](https://github.com/francktrouillez/recurly-mcp/actions/workflows/ci.yml)
|
|
4
|
+
[](https://www.npmjs.com/package/recurly-mcp)
|
|
5
|
+
[](LICENSE)
|
|
6
|
+
[](https://nodejs.org)
|
|
7
|
+
|
|
8
|
+
A **read-only** MCP (Model Context Protocol) server that exposes the [Recurly v2021-02-25 API](https://recurly.com/developers/api/v2021-02-25/index.html) to LLM clients. Works with any MCP-compatible client (Claude Desktop, Claude Code, Cursor, Cline, Codex CLI, Continue.dev, etc.).
|
|
9
|
+
|
|
10
|
+
Thirty resource-grouped tools cover every read (`GET`) endpoint Recurly exposes — accounts, subscriptions, invoices, transactions, line items, plans, coupons, items, usage, exports, external products/subscriptions, and the rest — plus a generic `recurly_request` escape hatch for anything not directly modeled.
|
|
11
|
+
|
|
12
|
+
**This server is read-only by construction: the HTTP client only ever issues `GET`. There is no code path that can create, update, or delete Recurly data — including via the escape hatch.**
|
|
13
|
+
|
|
14
|
+
**Unofficial. Not affiliated with or endorsed by Recurly.**
|
|
15
|
+
|
|
16
|
+
## Install
|
|
17
|
+
|
|
18
|
+
### Claude Code (one-liner)
|
|
19
|
+
|
|
20
|
+
```bash
|
|
21
|
+
claude mcp add recurly --scope user \
|
|
22
|
+
--env RECURLY_API_KEY=YOUR_PRIVATE_API_KEY \
|
|
23
|
+
-- npx -y recurly-mcp
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
Restart Claude Code and the `recurly_*` tools become available.
|
|
27
|
+
|
|
28
|
+
### Run the binary directly (optional)
|
|
29
|
+
|
|
30
|
+
The server is normally spawned by your MCP client over stdio. To test it stand-alone:
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
RECURLY_API_KEY=your_private_api_key npx recurly-mcp
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
It will wait for JSON-RPC messages on stdin. Useful for debugging the install only.
|
|
37
|
+
|
|
38
|
+
## Configuration
|
|
39
|
+
|
|
40
|
+
All configuration is via environment variables.
|
|
41
|
+
|
|
42
|
+
| Var | Required | Default | Purpose |
|
|
43
|
+
|---|---|---|---|
|
|
44
|
+
| `RECURLY_API_KEY` | yes | — | Private API key. Sent as the HTTP Basic auth username (empty password). |
|
|
45
|
+
| `RECURLY_REGION` | no | `us` | `us` or `eu` — selects the API host. |
|
|
46
|
+
| `RECURLY_HOST` | no | `https://v3.recurly.com` | Override the API origin entirely (local mocks, proxies). Overrides `RECURLY_REGION`. |
|
|
47
|
+
| `RECURLY_API_VERSION` | no | `v2021-02-25` | Recurly API version sent in the `Accept` header. The tool paths/params here are modeled on `v2021-02-25`. |
|
|
48
|
+
| `RECURLY_TIMEOUT_MS` | no | `15000` | Per-request timeout. |
|
|
49
|
+
| `RECURLY_MAX_RETRIES` | no | `2` | Retries on 429 and 5xx (honors `Retry-After`, equal-jitter backoff). |
|
|
50
|
+
|
|
51
|
+
Get a private API key from the Recurly dashboard → Integrations → API Credentials. Use a key scoped to read-only access where possible — this server never writes, but defense in depth is good.
|
|
52
|
+
|
|
53
|
+
## MCP client config
|
|
54
|
+
|
|
55
|
+
The MCP entry below is the same for every MCP client — only the config file location differs.
|
|
56
|
+
|
|
57
|
+
```json
|
|
58
|
+
{
|
|
59
|
+
"mcpServers": {
|
|
60
|
+
"recurly": {
|
|
61
|
+
"command": "npx",
|
|
62
|
+
"args": ["-y", "recurly-mcp"],
|
|
63
|
+
"env": {
|
|
64
|
+
"RECURLY_API_KEY": "your_private_api_key_here"
|
|
65
|
+
}
|
|
66
|
+
}
|
|
67
|
+
}
|
|
68
|
+
}
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
Where to put it, by client:
|
|
72
|
+
|
|
73
|
+
| Client | Location |
|
|
74
|
+
|---|---|
|
|
75
|
+
| **Claude Desktop** (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json` |
|
|
76
|
+
| **Claude Code** | `~/.claude.json` — or use `claude mcp add recurly --scope user --env RECURLY_API_KEY=… -- npx -y recurly-mcp` |
|
|
77
|
+
| **Cursor** | `.cursor/mcp.json` (per-project) or `~/.cursor/mcp.json` (user-wide) |
|
|
78
|
+
| **Cline (VS Code)** | VS Code Settings → Cline → MCP servers (UI), or `cline_mcp_settings.json` |
|
|
79
|
+
| **Codex CLI** | `~/.codex/config.json` under `mcpServers` |
|
|
80
|
+
| **Continue.dev** | `.continue/config.json` under `experimental.modelContextProtocolServers` |
|
|
81
|
+
|
|
82
|
+
For the EU data region, add `"RECURLY_REGION": "eu"` to `env`.
|
|
83
|
+
|
|
84
|
+
## Tools
|
|
85
|
+
|
|
86
|
+
Every action is read-only. Each tool takes an `action` discriminator plus the parameters for that action.
|
|
87
|
+
|
|
88
|
+
| Tool | Actions |
|
|
89
|
+
|---|---|
|
|
90
|
+
| `recurly_sites` | `list`, `get` |
|
|
91
|
+
| `recurly_accounts` | `list`, `get`, `get_balance`, `get_acquisition`, `list_acquisitions`, `list_child_accounts`, `list_notes`, `get_note`, `list_entitlements` |
|
|
92
|
+
| `recurly_billing_info` | `get`, `list`, `get_one` |
|
|
93
|
+
| `recurly_shipping_addresses` | `list`, `get` |
|
|
94
|
+
| `recurly_coupons` | `list`, `get`, `list_unique_coupon_codes`, `get_unique_coupon_code` |
|
|
95
|
+
| `recurly_coupon_redemptions` | `list_for_account`, `list_active_for_account`, `get_for_account`, `list_for_invoice`, `list_for_subscription`, `get_for_subscription` |
|
|
96
|
+
| `recurly_credit_payments` | `list`, `get`, `list_for_account` |
|
|
97
|
+
| `recurly_invoices` | `list`, `get`, `get_pdf`, `list_line_items`, `list_related`, `list_for_account` |
|
|
98
|
+
| `recurly_line_items` | `list`, `get`, `list_for_account` |
|
|
99
|
+
| `recurly_subscriptions` | `list`, `get`, `get_change`, `get_preview_renewal`, `list_invoices`, `list_line_items`, `list_for_account` |
|
|
100
|
+
| `recurly_transactions` | `list`, `get`, `list_for_account` |
|
|
101
|
+
| `recurly_custom_field_definitions` | `list`, `get` |
|
|
102
|
+
| `recurly_items` | `list`, `get` |
|
|
103
|
+
| `recurly_measured_units` | `list`, `get` |
|
|
104
|
+
| `recurly_plans` | `list`, `get`, `list_add_ons`, `get_add_on` |
|
|
105
|
+
| `recurly_add_ons` | `list`, `get` |
|
|
106
|
+
| `recurly_shipping_methods` | `list`, `get` |
|
|
107
|
+
| `recurly_usage` | `list`, `get` |
|
|
108
|
+
| `recurly_export` | `get_dates`, `get_files` |
|
|
109
|
+
| `recurly_dunning_campaigns` | `list`, `get` |
|
|
110
|
+
| `recurly_invoice_templates` | `list`, `get`, `list_accounts` |
|
|
111
|
+
| `recurly_external_products` | `list`, `get`, `list_references`, `get_reference` |
|
|
112
|
+
| `recurly_external_subscriptions` | `list`, `get`, `list_invoices`, `list_payment_phases`, `get_payment_phase`, `list_for_account` |
|
|
113
|
+
| `recurly_external_invoices` | `list`, `get`, `list_for_account` |
|
|
114
|
+
| `recurly_external_accounts` | `list`, `get` |
|
|
115
|
+
| `recurly_general_ledger_accounts` | `list`, `get` |
|
|
116
|
+
| `recurly_performance_obligations` | `list`, `get` |
|
|
117
|
+
| `recurly_price_segments` | `list`, `get` |
|
|
118
|
+
| `recurly_business_entities` | `list`, `get`, `list_invoices` |
|
|
119
|
+
| `recurly_gift_cards` | `list`, `get` |
|
|
120
|
+
| `recurly_request` | Escape hatch — a raw `GET` to any Recurly API path. |
|
|
121
|
+
|
|
122
|
+
Tools return raw Recurly JSON payloads with no field-stripping. `list` actions add a `_pagination` metadata object so the model can iterate pages.
|
|
123
|
+
|
|
124
|
+
### IDs and codes
|
|
125
|
+
|
|
126
|
+
Most ID parameters accept **either** the opaque Recurly object ID (e.g. `e28zov4fw0v2`) **or** a prefixed human key:
|
|
127
|
+
|
|
128
|
+
- accounts/plans/items/coupons/…: `code-<your_code>`
|
|
129
|
+
- sites: `subdomain-<name>`
|
|
130
|
+
- invoices: `number-<invoice_number>`
|
|
131
|
+
- subscriptions/transactions: `uuid-<uuid>`
|
|
132
|
+
|
|
133
|
+
Values are URL-encoded before interpolation, so codes containing special characters work, and path-traversal segments are rejected.
|
|
134
|
+
|
|
135
|
+
### Pagination
|
|
136
|
+
|
|
137
|
+
Recurly uses cursor-based pagination. `list` actions accept `limit` (1–200), `order` (`asc`/`desc`), `sort`, `cursor`, `ids`, `begin_time`, `end_time`, plus resource-specific filters (`state`, `type`, etc.). Responses include Recurly's native `has_more`/`next`, and this server adds a `_pagination` hint:
|
|
138
|
+
|
|
139
|
+
```json
|
|
140
|
+
{ "object": "list", "has_more": true, "next": "/accounts?cursor=…", "data": [ … ],
|
|
141
|
+
"_pagination": { "has_more": true, "next_cursor": "…" } }
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
Pass `_pagination.next_cursor` back as `cursor` to fetch the next page.
|
|
145
|
+
|
|
146
|
+
### Invoice PDFs
|
|
147
|
+
|
|
148
|
+
`recurly_invoices` `get_pdf` returns the PDF as a base64 wrapper rather than a mangled string:
|
|
149
|
+
|
|
150
|
+
```json
|
|
151
|
+
{ "object": "binary_file", "content_type": "application/pdf", "encoding": "base64", "byte_length": 12345, "data": "JVBERi0…" }
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
### Coverage notes
|
|
155
|
+
|
|
156
|
+
- **Write operations are intentionally not modeled.** This is a read-only server; the client cannot issue anything but `GET`.
|
|
157
|
+
- **Filters beyond the common set** are reachable via `recurly_request` (`{ "path": "/...", "query": { … } }`) if a specific list endpoint accepts a parameter not modeled on its typed tool.
|
|
158
|
+
|
|
159
|
+
## Development
|
|
160
|
+
|
|
161
|
+
```bash
|
|
162
|
+
npm install
|
|
163
|
+
npm test # vitest, 154 tests
|
|
164
|
+
npm run typecheck
|
|
165
|
+
npm run lint
|
|
166
|
+
npm run build # emits dist/
|
|
167
|
+
npm run validate # spawns the built server, checks tool schemas (expects 31 tools)
|
|
168
|
+
npm run dev # tsx src/bin.ts (for local stdio testing)
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
## Contributing
|
|
172
|
+
|
|
173
|
+
Issues and pull requests welcome at <https://github.com/francktrouillez/recurly-mcp/issues>.
|
|
174
|
+
|
|
175
|
+
Bug reports are most useful with: the tool and action you called, the params (with secrets redacted), and the response.
|
|
176
|
+
|
|
177
|
+
## License
|
|
178
|
+
|
|
179
|
+
MIT
|
package/dist/bin.d.ts
ADDED
package/dist/bin.js
ADDED
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
import { startStdioServer } from './server.js';
|
|
3
|
+
// Last-resort handlers: terminate with a single stderr line rather than letting
|
|
4
|
+
// an unexpected error crash the stdio transport with a raw stack trace (which can
|
|
5
|
+
// leak file paths). The per-tool catch in server.ts already handles normal tool
|
|
6
|
+
// failures; these only cover anything that escapes it.
|
|
7
|
+
process.on('unhandledRejection', (reason) => {
|
|
8
|
+
process.stderr.write(`recurly-mcp: unhandled rejection: ${reason instanceof Error ? reason.message : String(reason)}\n`);
|
|
9
|
+
process.exit(1);
|
|
10
|
+
});
|
|
11
|
+
process.on('uncaughtException', (err) => {
|
|
12
|
+
process.stderr.write(`recurly-mcp: uncaught exception: ${err.message}\n`);
|
|
13
|
+
process.exit(1);
|
|
14
|
+
});
|
|
15
|
+
startStdioServer().catch((err) => {
|
|
16
|
+
process.stderr.write(`recurly-mcp failed to start: ${err instanceof Error ? err.message : String(err)}\n`);
|
|
17
|
+
process.exit(1);
|
|
18
|
+
});
|
|
19
|
+
//# sourceMappingURL=bin.js.map
|
package/dist/bin.js.map
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"bin.js","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/C,gFAAgF;AAChF,kFAAkF;AAClF,gFAAgF;AAChF,uDAAuD;AACvD,OAAO,CAAC,EAAE,CAAC,oBAAoB,EAAE,CAAC,MAAM,EAAE,EAAE;IAC1C,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,qCAAqC,MAAM,YAAY,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CACnG,CAAC;IACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC;AACH,OAAO,CAAC,EAAE,CAAC,mBAAmB,EAAE,CAAC,GAAG,EAAE,EAAE;IACtC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,oCAAoC,GAAG,CAAC,OAAO,IAAI,CAAC,CAAC;IAC1E,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC;AAEH,gBAAgB,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IAC/B,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,gCAAgC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CACrF,CAAC;IACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
export declare class RecurlyApiError extends Error {
|
|
2
|
+
readonly status: number;
|
|
3
|
+
readonly method: string;
|
|
4
|
+
readonly path: string;
|
|
5
|
+
readonly body: unknown;
|
|
6
|
+
constructor(status: number, method: string, path: string, body: unknown);
|
|
7
|
+
}
|
|
8
|
+
export declare class RecurlyNetworkError extends Error {
|
|
9
|
+
readonly method: string;
|
|
10
|
+
readonly path: string;
|
|
11
|
+
readonly cause: unknown;
|
|
12
|
+
constructor(method: string, path: string, cause: unknown);
|
|
13
|
+
}
|
|
14
|
+
export declare class RecurlyConfigError extends Error {
|
|
15
|
+
constructor(message: string);
|
|
16
|
+
}
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
// Bound the body rendered into the error MESSAGE. The full `body` is retained on
|
|
2
|
+
// the instance for programmatic callers, but the message is what gets forwarded
|
|
3
|
+
// to the MCP client, so a hostile/large upstream error body (up to the 25 MB
|
|
4
|
+
// read cap) must not be embedded verbatim.
|
|
5
|
+
const MAX_ERROR_BODY_CHARS = 2048;
|
|
6
|
+
function bodyForMessage(body) {
|
|
7
|
+
const s = JSON.stringify(body) ?? 'null';
|
|
8
|
+
return s.length > MAX_ERROR_BODY_CHARS
|
|
9
|
+
? `${s.slice(0, MAX_ERROR_BODY_CHARS)}…[truncated ${s.length - MAX_ERROR_BODY_CHARS} chars]`
|
|
10
|
+
: s;
|
|
11
|
+
}
|
|
12
|
+
export class RecurlyApiError extends Error {
|
|
13
|
+
status;
|
|
14
|
+
method;
|
|
15
|
+
path;
|
|
16
|
+
body;
|
|
17
|
+
constructor(status, method, path, body) {
|
|
18
|
+
super(`Recurly API error ${status} on ${method} ${path}: ${bodyForMessage(body)}`);
|
|
19
|
+
this.status = status;
|
|
20
|
+
this.method = method;
|
|
21
|
+
this.path = path;
|
|
22
|
+
this.body = body;
|
|
23
|
+
this.name = 'RecurlyApiError';
|
|
24
|
+
}
|
|
25
|
+
}
|
|
26
|
+
export class RecurlyNetworkError extends Error {
|
|
27
|
+
method;
|
|
28
|
+
path;
|
|
29
|
+
cause;
|
|
30
|
+
constructor(method, path, cause) {
|
|
31
|
+
super(`Recurly network error on ${method} ${path}: ${cause instanceof Error ? cause.message : String(cause)}`);
|
|
32
|
+
this.method = method;
|
|
33
|
+
this.path = path;
|
|
34
|
+
this.cause = cause;
|
|
35
|
+
this.name = 'RecurlyNetworkError';
|
|
36
|
+
}
|
|
37
|
+
}
|
|
38
|
+
export class RecurlyConfigError extends Error {
|
|
39
|
+
constructor(message) {
|
|
40
|
+
super(message);
|
|
41
|
+
this.name = 'RecurlyConfigError';
|
|
42
|
+
}
|
|
43
|
+
}
|
|
44
|
+
//# sourceMappingURL=errors.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/client/errors.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,gFAAgF;AAChF,6EAA6E;AAC7E,2CAA2C;AAC3C,MAAM,oBAAoB,GAAG,IAAI,CAAC;AAClC,SAAS,cAAc,CAAC,IAAa;IACnC,MAAM,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,MAAM,CAAC;IACzC,OAAO,CAAC,CAAC,MAAM,GAAG,oBAAoB;QACpC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,oBAAoB,CAAC,eAAe,CAAC,CAAC,MAAM,GAAG,oBAAoB,SAAS;QAC5F,CAAC,CAAC,CAAC,CAAC;AACR,CAAC;AAED,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAEtB;IACA;IACA;IACA;IAJlB,YACkB,MAAc,EACd,MAAc,EACd,IAAY,EACZ,IAAa;QAE7B,KAAK,CAAC,qBAAqB,MAAM,OAAO,MAAM,IAAI,IAAI,KAAK,cAAc,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QALnE,WAAM,GAAN,MAAM,CAAQ;QACd,WAAM,GAAN,MAAM,CAAQ;QACd,SAAI,GAAJ,IAAI,CAAQ;QACZ,SAAI,GAAJ,IAAI,CAAS;QAG7B,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF;AAED,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IAE1B;IACA;IACA;IAHlB,YACkB,MAAc,EACd,IAAY,EACZ,KAAc;QAE9B,KAAK,CACH,4BAA4B,MAAM,IAAI,IAAI,KAAK,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,CACxG,CAAC;QANc,WAAM,GAAN,MAAM,CAAQ;QACd,SAAI,GAAJ,IAAI,CAAQ;QACZ,UAAK,GAAL,KAAK,CAAS;QAK9B,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;IACpC,CAAC;CACF;AAED,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAC3C,YAAY,OAAe;QACzB,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF"}
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
export interface CursorMeta {
|
|
2
|
+
has_more: boolean;
|
|
3
|
+
next_cursor: string | null;
|
|
4
|
+
}
|
|
5
|
+
export declare function extractCursor(next: unknown): string | null;
|
|
6
|
+
export declare function withCursor<T extends Record<string, unknown>>(payload: T): T & {
|
|
7
|
+
_pagination?: CursorMeta;
|
|
8
|
+
};
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
// Recurly uses cursor-based pagination. A list response looks like:
|
|
2
|
+
// { "object": "list", "has_more": true, "next": "/accounts?cursor=…&limit=…", "data": [ … ] }
|
|
3
|
+
// To fetch the next page the caller re-issues the same list action with the
|
|
4
|
+
// `cursor` extracted from `next`. We surface that cursor in a `_pagination`
|
|
5
|
+
// hint so the model doesn't have to parse the `next` URL itself.
|
|
6
|
+
// `next` may be a relative path (`/accounts?cursor=…`) or an absolute URL.
|
|
7
|
+
// Parse it against a dummy base and pull out the `cursor` query param.
|
|
8
|
+
export function extractCursor(next) {
|
|
9
|
+
if (typeof next !== 'string' || next === '')
|
|
10
|
+
return null;
|
|
11
|
+
try {
|
|
12
|
+
const url = new URL(next, 'https://v3.recurly.com');
|
|
13
|
+
return url.searchParams.get('cursor');
|
|
14
|
+
}
|
|
15
|
+
catch {
|
|
16
|
+
return null;
|
|
17
|
+
}
|
|
18
|
+
}
|
|
19
|
+
// Attach a `_pagination` hint to a Recurly list payload. Non-list payloads are
|
|
20
|
+
// returned unchanged.
|
|
21
|
+
export function withCursor(payload) {
|
|
22
|
+
if (!payload || typeof payload !== 'object')
|
|
23
|
+
return payload;
|
|
24
|
+
const isList = payload['object'] === 'list' || 'has_more' in payload || 'next' in payload;
|
|
25
|
+
if (!isList)
|
|
26
|
+
return payload;
|
|
27
|
+
const meta = {
|
|
28
|
+
has_more: payload['has_more'] === true,
|
|
29
|
+
next_cursor: extractCursor(payload['next']),
|
|
30
|
+
};
|
|
31
|
+
return { ...payload, _pagination: meta };
|
|
32
|
+
}
|
|
33
|
+
//# sourceMappingURL=pagination.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"pagination.js","sourceRoot":"","sources":["../../src/client/pagination.ts"],"names":[],"mappings":"AAAA,oEAAoE;AACpE,gGAAgG;AAChG,4EAA4E;AAC5E,4EAA4E;AAC5E,iEAAiE;AAOjE,2EAA2E;AAC3E,uEAAuE;AACvE,MAAM,UAAU,aAAa,CAAC,IAAa;IACzC,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,EAAE;QAAE,OAAO,IAAI,CAAC;IACzD,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,IAAI,EAAE,wBAAwB,CAAC,CAAC;QACpD,OAAO,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACxC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,+EAA+E;AAC/E,sBAAsB;AACtB,MAAM,UAAU,UAAU,CACxB,OAAU;IAEV,IAAI,CAAC,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ;QAAE,OAAO,OAAO,CAAC;IAC5D,MAAM,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,KAAK,MAAM,IAAI,UAAU,IAAI,OAAO,IAAI,MAAM,IAAI,OAAO,CAAC;IAC1F,IAAI,CAAC,MAAM;QAAE,OAAO,OAAO,CAAC;IAC5B,MAAM,IAAI,GAAe;QACvB,QAAQ,EAAE,OAAO,CAAC,UAAU,CAAC,KAAK,IAAI;QACtC,WAAW,EAAE,aAAa,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;KAC5C,CAAC;IACF,OAAO,EAAE,GAAG,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC;AAC3C,CAAC"}
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
import type { Config } from '../config.js';
|
|
2
|
+
export type HttpMethod = 'GET';
|
|
3
|
+
export type QueryValue = string | number | boolean | string[];
|
|
4
|
+
export interface RequestOptions {
|
|
5
|
+
query?: Record<string, QueryValue | undefined>;
|
|
6
|
+
headers?: Record<string, string>;
|
|
7
|
+
}
|
|
8
|
+
export declare const MAX_RETRY_DELAY_MS = 60000;
|
|
9
|
+
export declare const MAX_RESPONSE_BYTES: number;
|
|
10
|
+
export declare const DEFAULT_ACCEPT_LANGUAGE = "en-US";
|
|
11
|
+
export declare function parseRetryAfter(value: string | null, now?: number): number | null;
|
|
12
|
+
export declare function backoffMs(attempt: number, baseMs?: number): number;
|
|
13
|
+
export declare class RecurlyClient {
|
|
14
|
+
private readonly config;
|
|
15
|
+
constructor(config: Config);
|
|
16
|
+
private authHeader;
|
|
17
|
+
request(method: HttpMethod, path: string, options?: RequestOptions): Promise<unknown>;
|
|
18
|
+
}
|
|
19
|
+
export declare function readBodyBytesWithLimit(response: Response, max: number): Promise<Uint8Array>;
|