@kelviq/mcp-server 0.2.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 (149) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +322 -0
  3. package/dist/config.d.ts +16 -0
  4. package/dist/config.js +45 -0
  5. package/dist/config.js.map +1 -0
  6. package/dist/docs/README.md +128 -0
  7. package/dist/docs/api-reference/authentication.md +41 -0
  8. package/dist/docs/backend-integration/node-sdk.md +1040 -0
  9. package/dist/docs/backend-integration/python-sdk.md +1198 -0
  10. package/dist/docs/changelog/app.md +80 -0
  11. package/dist/docs/changelog/checkout-api.md +59 -0
  12. package/dist/docs/changelog/js-promotions-ui.md +14 -0
  13. package/dist/docs/changelog/js-sdk.md +281 -0
  14. package/dist/docs/changelog/node-sdk.md +378 -0
  15. package/dist/docs/changelog/python-sdk.md +456 -0
  16. package/dist/docs/changelog/react-sdk.md +580 -0
  17. package/dist/docs/checkout/checkout-configuration.md +434 -0
  18. package/dist/docs/coustomers-management/overview.md +111 -0
  19. package/dist/docs/customer-portal/overview.md +81 -0
  20. package/dist/docs/frontend-integration/js-sdk.md +676 -0
  21. package/dist/docs/frontend-integration/promotions-ui-js.md +265 -0
  22. package/dist/docs/frontend-integration/react-promotions-ui.md +361 -0
  23. package/dist/docs/frontend-integration/react-sdk.md +1187 -0
  24. package/dist/docs/frontend-integration/react-ui.md +771 -0
  25. package/dist/docs/getstarted/fees.md +160 -0
  26. package/dist/docs/getstarted/introduction-to-kelviq.md +80 -0
  27. package/dist/docs/getstarted/merchant-of-record.md +64 -0
  28. package/dist/docs/getstarted/review-process.md +190 -0
  29. package/dist/docs/guides/subscription-integration-for-nextjs.md +512 -0
  30. package/dist/docs/guides/subscription-integration.md +291 -0
  31. package/dist/docs/guides/webhooks.md +963 -0
  32. package/dist/docs/legal/approved-prohibited-policy.md +252 -0
  33. package/dist/docs/legal/buyer-terms.md +177 -0
  34. package/dist/docs/legal/compliant-user-flow.md +216 -0
  35. package/dist/docs/legal/master-service-agreement.md +404 -0
  36. package/dist/docs/legal/payment-flow-diagram.md +188 -0
  37. package/dist/docs/legal/seller-terms.md +169 -0
  38. package/dist/docs/manifest.json +415 -0
  39. package/dist/docs/monetization/offerings.md +156 -0
  40. package/dist/docs/monetization/pricing-tables.md +226 -0
  41. package/dist/docs/monetization/targeting-rules.md +278 -0
  42. package/dist/docs/openapi.json +5479 -0
  43. package/dist/docs/payouts/overview.md +43 -0
  44. package/dist/docs/payouts/payout-account.md +12 -0
  45. package/dist/docs/payouts/transactions.md +23 -0
  46. package/dist/docs/product-catalog/digital-downloads.md +117 -0
  47. package/dist/docs/product-catalog/discounts.md +69 -0
  48. package/dist/docs/product-catalog/entitlements.md +428 -0
  49. package/dist/docs/product-catalog/free-and-trials.md +36 -0
  50. package/dist/docs/product-catalog/license-keys.md +324 -0
  51. package/dist/docs/product-catalog/links.md +92 -0
  52. package/dist/docs/product-catalog/location-based-pricing.md +41 -0
  53. package/dist/docs/product-catalog/one-time-payments.md +24 -0
  54. package/dist/docs/product-catalog/plans.md +199 -0
  55. package/dist/docs/product-catalog/products.md +60 -0
  56. package/dist/docs/product-catalog/subscriptions.md +29 -0
  57. package/dist/docs/product-catalog/tax-settings.md +37 -0
  58. package/dist/docs/product-catalog/usage-based-billing.md +119 -0
  59. package/dist/docs/promotions/create-a-promotion.md +75 -0
  60. package/dist/docs/promotions/customize-banner.md +41 -0
  61. package/dist/docs/promotions/integrate.md +38 -0
  62. package/dist/docs/promotions/overview.md +51 -0
  63. package/dist/docs/quickstart/core-concepts.md +146 -0
  64. package/dist/docs/quickstart/dashboard-setup.md +129 -0
  65. package/dist/docs/quickstart/integrate-with-your-app.md +149 -0
  66. package/dist/docs/sales/checkout-sessions.md +58 -0
  67. package/dist/docs/sales/orders.md +76 -0
  68. package/dist/http/client.d.ts +28 -0
  69. package/dist/http/client.js +76 -0
  70. package/dist/http/client.js.map +1 -0
  71. package/dist/http/errors.d.ts +20 -0
  72. package/dist/http/errors.js +58 -0
  73. package/dist/http/errors.js.map +1 -0
  74. package/dist/resources/docs-index.d.ts +25 -0
  75. package/dist/resources/docs-index.js +109 -0
  76. package/dist/resources/docs-index.js.map +1 -0
  77. package/dist/resources/index.d.ts +2 -0
  78. package/dist/resources/index.js +73 -0
  79. package/dist/resources/index.js.map +1 -0
  80. package/dist/schemas/kelviq.d.ts +1304 -0
  81. package/dist/schemas/kelviq.js +468 -0
  82. package/dist/schemas/kelviq.js.map +1 -0
  83. package/dist/server.d.ts +2 -0
  84. package/dist/server.js +41 -0
  85. package/dist/server.js.map +1 -0
  86. package/dist/tools/_util.d.ts +15 -0
  87. package/dist/tools/_util.js +15 -0
  88. package/dist/tools/_util.js.map +1 -0
  89. package/dist/tools/checkout.d.ts +3 -0
  90. package/dist/tools/checkout.js +18 -0
  91. package/dist/tools/checkout.js.map +1 -0
  92. package/dist/tools/customers.d.ts +3 -0
  93. package/dist/tools/customers.js +32 -0
  94. package/dist/tools/customers.js.map +1 -0
  95. package/dist/tools/docs.d.ts +2 -0
  96. package/dist/tools/docs.js +43 -0
  97. package/dist/tools/docs.js.map +1 -0
  98. package/dist/tools/entitlements.d.ts +3 -0
  99. package/dist/tools/entitlements.js +22 -0
  100. package/dist/tools/entitlements.js.map +1 -0
  101. package/dist/tools/features.d.ts +3 -0
  102. package/dist/tools/features.js +55 -0
  103. package/dist/tools/features.js.map +1 -0
  104. package/dist/tools/index.d.ts +3 -0
  105. package/dist/tools/index.js +44 -0
  106. package/dist/tools/index.js.map +1 -0
  107. package/dist/tools/licenses.d.ts +3 -0
  108. package/dist/tools/licenses.js +44 -0
  109. package/dist/tools/licenses.js.map +1 -0
  110. package/dist/tools/media.d.ts +3 -0
  111. package/dist/tools/media.js +18 -0
  112. package/dist/tools/media.js.map +1 -0
  113. package/dist/tools/offerings.d.ts +3 -0
  114. package/dist/tools/offerings.js +21 -0
  115. package/dist/tools/offerings.js.map +1 -0
  116. package/dist/tools/partner.d.ts +3 -0
  117. package/dist/tools/partner.js +55 -0
  118. package/dist/tools/partner.js.map +1 -0
  119. package/dist/tools/plan-entitlements.d.ts +3 -0
  120. package/dist/tools/plan-entitlements.js +56 -0
  121. package/dist/tools/plan-entitlements.js.map +1 -0
  122. package/dist/tools/plan-files.d.ts +3 -0
  123. package/dist/tools/plan-files.js +43 -0
  124. package/dist/tools/plan-files.js.map +1 -0
  125. package/dist/tools/plans.d.ts +3 -0
  126. package/dist/tools/plans.js +120 -0
  127. package/dist/tools/plans.js.map +1 -0
  128. package/dist/tools/portal.d.ts +3 -0
  129. package/dist/tools/portal.js +18 -0
  130. package/dist/tools/portal.js.map +1 -0
  131. package/dist/tools/product-files.d.ts +3 -0
  132. package/dist/tools/product-files.js +31 -0
  133. package/dist/tools/product-files.js.map +1 -0
  134. package/dist/tools/product-settings.d.ts +3 -0
  135. package/dist/tools/product-settings.js +31 -0
  136. package/dist/tools/product-settings.js.map +1 -0
  137. package/dist/tools/products.d.ts +3 -0
  138. package/dist/tools/products.js +69 -0
  139. package/dist/tools/products.js.map +1 -0
  140. package/dist/tools/promotions.d.ts +3 -0
  141. package/dist/tools/promotions.js +19 -0
  142. package/dist/tools/promotions.js.map +1 -0
  143. package/dist/tools/subscriptions.d.ts +3 -0
  144. package/dist/tools/subscriptions.js +63 -0
  145. package/dist/tools/subscriptions.js.map +1 -0
  146. package/dist/tools/usage.d.ts +3 -0
  147. package/dist/tools/usage.js +18 -0
  148. package/dist/tools/usage.js.map +1 -0
  149. package/package.json +88 -0
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Kelviq
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,322 @@
1
+ # @kelviq/mcp-server
2
+
3
+ A [Model Context Protocol](https://modelcontextprotocol.io) server for
4
+ [Kelviq](https://kelviq.com), the SaaS monetization & subscription platform.
5
+
6
+ Gives any MCP-capable client (Claude Desktop, Claude Code, Cursor, Zed, …) two
7
+ capabilities at once:
8
+
9
+ 1. **Typed tools** for the full Kelviq REST API — manage products, plans,
10
+ features, entitlements, customers, subscriptions, checkout sessions, license
11
+ keys, usage, promotions, the customer portal, and partner organizations.
12
+ 2. **Searchable documentation** — the entire Kelviq docs site is bundled
13
+ inside the package and exposed as MCP resources plus `docs_search` /
14
+ `docs_read` tools, so the LLM can ground its answers in the canonical docs.
15
+
16
+ > **51 tools** across **13 domains**, **61 resources** including the full
17
+ > OpenAPI spec. Works offline for docs Q&A — only API tools require a key.
18
+
19
+ ## Install
20
+
21
+ ```bash
22
+ npm install -g @kelviq/mcp-server
23
+ # or, no install needed:
24
+ npx -y @kelviq/mcp-server
25
+ ```
26
+
27
+ ## Configure your MCP client
28
+
29
+ ### Claude Code (CLI)
30
+
31
+ ```bash
32
+ claude mcp add kelviq npx -y @kelviq/mcp-server \
33
+ --env KELVIQ_SERVER_API_KEY=<your-server-key> \
34
+ --env KELVIQ_CLIENT_API_KEY=<your-client-key>
35
+ ```
36
+
37
+ Then `/mcp` in a new Claude Code session shows `kelviq` connected.
38
+
39
+ ### Claude Desktop
40
+
41
+ Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):
42
+
43
+ ```json
44
+ {
45
+ "mcpServers": {
46
+ "kelviq": {
47
+ "command": "npx",
48
+ "args": ["-y", "@kelviq/mcp-server"],
49
+ "env": {
50
+ "KELVIQ_SERVER_API_KEY": "server-...",
51
+ "KELVIQ_CLIENT_API_KEY": "client-..."
52
+ }
53
+ }
54
+ }
55
+ }
56
+ ```
57
+
58
+ Restart Claude Desktop. The hammer icon shows `kelviq` with all tools.
59
+
60
+ ### Cursor / Zed / other MCP clients
61
+
62
+ Any client that supports stdio MCP servers — point it at
63
+ `npx -y @kelviq/mcp-server` with the env vars above.
64
+
65
+ ### Get your API keys
66
+
67
+ [app.kelviq.com/settings/api-keys](https://app.kelviq.com/settings/api-keys).
68
+ The **Server key** is required for all API tools; the **Client key** is only
69
+ needed if you use `promotion_get` (it hits the edge endpoint with the public
70
+ key). Docs tools (`docs_search`, `docs_read`) work with no keys at all.
71
+
72
+ > **Never commit keys to git.** Use `--env` / your MCP client's secrets
73
+ > mechanism, never inline them in shared config.
74
+
75
+ ## Environment variables
76
+
77
+ | Variable | Required | Default | Purpose |
78
+ |---|---|---|---|
79
+ | `KELVIQ_SERVER_API_KEY` | yes (for API tools) | — | Bearer token for `api.kelviq.com` |
80
+ | `KELVIQ_CLIENT_API_KEY` | only for `promotion_get` | — | Bearer token for `edge.kelviq.com` |
81
+ | `KELVIQ_BASE_URL` | no | `https://api.kelviq.com/api/v1` | Override (sandbox, self-host) |
82
+ | `KELVIQ_ENTITLEMENTS_URL` | no | `https://edge.api.kelviq.com` | Override entitlements host |
83
+ | `KELVIQ_EDGE_URL` | no | `https://edge.kelviq.com/api/v1` | Override promotions edge host |
84
+
85
+ To point at Kelviq staging:
86
+
87
+ ```
88
+ KELVIQ_BASE_URL=https://stagingapi.kelviq.com/api/v1
89
+ KELVIQ_ENTITLEMENTS_URL=https://edge.stagingapi.kelviq.com
90
+ KELVIQ_EDGE_URL=https://edge.stagingapi.kelviq.com/api/v1
91
+ ```
92
+
93
+ ## Tools
94
+
95
+ ### Customers
96
+ - `customer_create` — create a customer
97
+ - `customer_update` — patch an existing customer
98
+
99
+ ### Checkout & Portal
100
+ - `checkout_create_session` — create a hosted checkout session
101
+ - `portal_session_create` — mint a customer portal URL
102
+
103
+ ### Subscriptions
104
+ - `subscription_create` — create a subscription directly (skip checkout)
105
+ - `subscription_list` — list subscriptions, filter by customer
106
+ - `subscription_update` — change plan / charge period / features
107
+ - `subscription_cancel` — immediately, at period end, or on a specific date
108
+
109
+ ### Entitlements, Licenses, Usage
110
+ - `entitlements_get` — fetch a customer's entitlements (all, or by featureId)
111
+ - `license_activate` / `license_deactivate` / `license_validate` — license key lifecycle
112
+ - `usage_report` — report metered usage (`SET` or `DELTA`)
113
+
114
+ ### Offerings & Promotions
115
+ - `offering_get_product` — public pricing scoped to a product UUID
116
+ - `promotion_get` — resolve the active promotion for the caller's location *(uses Client API key, edge host)*
117
+
118
+ ### Catalog: Products
119
+ - `product_list` / `product_create` / `product_retrieve` / `product_update` / `product_archive`
120
+ - `product_settings_get` / `product_settings_update` — VPN/Tor/proxy policy, default currency, product URL
121
+ - `product_image_update` / `product_image_delete`
122
+
123
+ ### Catalog: Features
124
+ - `feature_list` / `feature_create` / `feature_retrieve` / `feature_archive`
125
+
126
+ ### Catalog: Plans
127
+ - `plan_list` / `plan_create` / `plan_retrieve` / `plan_update` / `plan_archive`
128
+ - `plan_publish` — release the latest draft, optionally migrate existing customers
129
+ - `plan_discard_draft` — drop the current draft, keep the published version
130
+ - `plan_prices_list` / `plan_prices_bulk_set` — atomic per-currency pricing updates
131
+ - `plan_entitlements_list` / `plan_entitlements_add` / `plan_entitlement_update` / `plan_entitlement_delete`
132
+ - `plan_file_update` / `plan_file_delete` / `plan_file_download` — plan-attached digital deliverables
133
+
134
+ ### Media
135
+ - `media_presigned_upload` — get a presigned S3 POST policy for uploading product images or plan files (max 5 GB). Returns a `fileKey` you pass back into `product_create` / `product_update` / `plan_create` / `plan_update`.
136
+
137
+ ### Partner
138
+ - `partner_org_provision` — provision a new Kelviq org under your partner account
139
+ - `partner_org_list` / `partner_org_retrieve` / `partner_org_retrieve_by_external_id`
140
+
141
+ ### Docs (no API key required)
142
+ - `docs_search` — full-text search across the bundled docs; returns slugs
143
+ - `docs_read` — fetch a single doc page by slug
144
+
145
+ ## Resources
146
+
147
+ - `kelviq://docs/{section}/{slug}` — every conceptual page in the Kelviq docs (~59 pages)
148
+ - `kelviq://openapi.json` — the full OpenAPI 3.0 spec (49 operations, all schemas)
149
+ - `kelviq://README` — top-level Kelviq overview
150
+
151
+ The OpenAPI spec is the source of truth for request/response shapes — for any
152
+ endpoint detail the LLM can read it inline via the resource.
153
+
154
+ ## Try it
155
+
156
+ Once wired into your MCP client, try prompts like:
157
+
158
+ - *"Search Kelviq docs for license keys"* → `docs_search` + `docs_read`
159
+ - *"List my Kelviq products"* → `product_list`
160
+ - *"Create a plan named 'Pro Monthly' under product UUID `…`, then publish it"* → `plan_create` → `plan_publish`
161
+ - *"What entitlements does customer `acme-42` have for `seats`?"* → `entitlements_get`
162
+ - *"Create a checkout session for plan `pro-monthly`, success URL `https://example.com/ok`"* → `checkout_create_session`
163
+ - *"Provision a partner org with external ID `acme-99` and email `ops@acme.com`"* → `partner_org_provision`
164
+
165
+ The LLM picks the tool from the description — you don't need to say "use the
166
+ tool called X."
167
+
168
+ ## Test without an LLM
169
+
170
+ Use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector):
171
+
172
+ ```bash
173
+ npx -y @modelcontextprotocol/inspector \
174
+ npx -y @kelviq/mcp-server
175
+ ```
176
+
177
+ Opens a browser UI where you can browse all 51 tools, fill in arguments, and
178
+ run them against the real Kelviq API. Pre-fill env vars by exporting them
179
+ before the command:
180
+
181
+ ```bash
182
+ KELVIQ_SERVER_API_KEY=<key> KELVIQ_CLIENT_API_KEY=<key> \
183
+ npx -y @modelcontextprotocol/inspector \
184
+ npx -y @kelviq/mcp-server
185
+ ```
186
+
187
+ If the Inspector opens but the Command field shows the default placeholder
188
+ (`mcp-server-everything`), fill in:
189
+
190
+ | Field | Value |
191
+ |---|---|
192
+ | Transport Type | `STDIO` |
193
+ | Command | `npx` |
194
+ | Arguments | `-y @kelviq/mcp-server` |
195
+ | Environment Variables | `KELVIQ_SERVER_API_KEY=…`, `KELVIQ_CLIENT_API_KEY=…` |
196
+
197
+ Then click **Connect**.
198
+
199
+ ## Troubleshooting
200
+
201
+ ### Claude Code: `Executable not found in $PATH: "node"`
202
+
203
+ GUI/launcher processes don't source `~/.zshrc`, so nvm's node isn't on the
204
+ PATH. Either:
205
+
206
+ 1. **Symlink node into a system path:**
207
+ ```bash
208
+ sudo ln -s "$(which node)" /usr/local/bin/node
209
+ ```
210
+ One-time fix for every MCP server you'll ever add.
211
+
212
+ 2. **Use the absolute path** in the `claude mcp add` command:
213
+ ```bash
214
+ claude mcp add kelviq /Users/you/.nvm/versions/node/v20.19.0/bin/node \
215
+ $(npm root -g)/@kelviq/mcp-server/dist/server.js \
216
+ --env KELVIQ_SERVER_API_KEY=...
217
+ ```
218
+
219
+ 3. **Install node via Homebrew** (`brew install node`) so it lives on the
220
+ system PATH.
221
+
222
+ ### Tool returns `{"error": {"status": "Configuration error", …}}`
223
+
224
+ Means a required env var is missing. The error message names which one. Set
225
+ it in your MCP client config and reconnect.
226
+
227
+ ### API tool returns `{"error": {"status": "Bad request", "message": "Invalid product identifier"}}`
228
+
229
+ Your API key works but the plan/product/feature identifier doesn't exist on
230
+ this account. Common cause: server key is for **production** but the
231
+ identifier exists only in **staging** (or vice versa). Check
232
+ `KELVIQ_BASE_URL`.
233
+
234
+ ## Develop locally
235
+
236
+ ```bash
237
+ git clone https://github.com/kelviq/kelviq-mcp-server.git
238
+ cd kelviq-mcp-server
239
+ npm install # also installs husky git hooks
240
+ npm run snapshot # snapshot ../docs into src/docs/ (expects sibling kelviq/docs repo)
241
+ npm run build # tsc -> dist/
242
+ npm run dev # tsx src/server.ts (no build needed)
243
+ npm run inspect # launch MCP Inspector against the dev server
244
+ npm run typecheck
245
+ npm run lint # eslint
246
+ npm run lint:fix # eslint --fix
247
+ ```
248
+
249
+ ### Commit conventions
250
+
251
+ This repo uses [Conventional Commits](https://www.conventionalcommits.org/) — enforced by `commitlint` via a husky `commit-msg` hook. Format:
252
+
253
+ ```
254
+ <type>(optional scope): <subject>
255
+ ```
256
+
257
+ Allowed types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`, `revert`.
258
+
259
+ Examples:
260
+
261
+ ```
262
+ feat(plans): add plan_publish tool
263
+ fix(http): handle non-JSON 500 responses
264
+ docs: clarify env-var precedence
265
+ chore(deps): bump @modelcontextprotocol/sdk to 1.30
266
+ ```
267
+
268
+ The `pre-commit` hook runs `lint-staged`, which auto-fixes staged `.ts` / `.js` files via ESLint.
269
+
270
+ Don't want to remember the format? Use `commitizen` instead of `git commit`:
271
+
272
+ ```bash
273
+ git add .
274
+ npm run commit # interactive prompt walks you through type, scope, subject
275
+ ```
276
+
277
+ The prompt is generated from this repo's `commitlint.config.js`, so it'll never let you build a message commitlint would reject.
278
+
279
+ The snapshot step expects the [kelviq/docs](https://github.com/kelviq/docs) repo
280
+ checked out as a sibling directory of `mcp-server/`. The published npm package
281
+ ships the snapshot inline, so end-users never need the docs repo.
282
+
283
+ To add a new tool:
284
+
285
+ 1. Add a zod schema to [`src/schemas/kelviq.ts`](src/schemas/kelviq.ts).
286
+ 2. Add a `register…Tools(server, http)` call in a new (or existing) file under [`src/tools/`](src/tools/).
287
+ 3. Wire it into [`src/tools/index.ts`](src/tools/index.ts).
288
+ 4. `npm run build && npm run inspect` to verify.
289
+
290
+ ## Architecture
291
+
292
+ ```
293
+ src/
294
+ ├── server.ts # MCP server bootstrap (stdio transport)
295
+ ├── config.ts # env loading
296
+ ├── http/ # fetch wrapper + normalized errors
297
+ ├── schemas/kelviq.ts # zod schemas derived from openapi.json
298
+ ├── tools/ # one file per domain — registerXxxTools(server, http)
299
+ ├── resources/ # docs index + ListResources / ReadResource handlers
300
+ └── docs/ # snapshot of ../docs + openapi.json (built at npm publish)
301
+ ```
302
+
303
+ The HTTP client routes between three hosts based on each tool's `host` /
304
+ `auth` arguments:
305
+
306
+ - `api.kelviq.com` — main API (Server key)
307
+ - `edge.api.kelviq.com` — entitlements only (Server key)
308
+ - `edge.kelviq.com` — promotions only (Client key)
309
+
310
+ All API responses are passed through as JSON text content; errors are
311
+ returned as `{ error: { status, message } }` with `isError: true` rather than
312
+ thrown, so the LLM can react to them.
313
+
314
+ ## License
315
+
316
+ MIT — see [LICENSE](./LICENSE).
317
+
318
+ ## Support
319
+
320
+ - Kelviq docs: [docs.kelviq.com](https://docs.kelviq.com)
321
+ - Email: [hi@kelviq.com](mailto:hi@kelviq.com)
322
+ - Issues: [github.com/kelviq/kelviq-mcp-server/issues](https://github.com/kelviq/kelviq-mcp-server/issues)
@@ -0,0 +1,16 @@
1
+ export type AuthScope = 'server' | 'client';
2
+ export interface KelviqConfig {
3
+ serverApiKey: string | undefined;
4
+ clientApiKey: string | undefined;
5
+ baseUrl: string;
6
+ edgeUrl: string;
7
+ entitlementsUrl: string;
8
+ userAgent: string;
9
+ }
10
+ export declare function loadConfig(env?: NodeJS.ProcessEnv): KelviqConfig;
11
+ export declare function requireKey(config: KelviqConfig, scope: AuthScope): string;
12
+ export declare class MissingKeyError extends Error {
13
+ readonly envVar: string;
14
+ readonly scope: AuthScope;
15
+ constructor(envVar: string, scope: AuthScope);
16
+ }
package/dist/config.js ADDED
@@ -0,0 +1,45 @@
1
+ const DEFAULT_BASE_URL = 'https://api.kelviq.com/api/v1';
2
+ const DEFAULT_EDGE_URL = 'https://edge.kelviq.com/api/v1';
3
+ const DEFAULT_ENTITLEMENTS_URL = 'https://edge.api.kelviq.com';
4
+ export function loadConfig(env = process.env) {
5
+ const stripSlash = (u) => u.replace(/\/+$/, '');
6
+ return {
7
+ serverApiKey: env.KELVIQ_SERVER_API_KEY?.trim() || undefined,
8
+ clientApiKey: env.KELVIQ_CLIENT_API_KEY?.trim() || undefined,
9
+ baseUrl: stripSlash(env.KELVIQ_BASE_URL?.trim() || DEFAULT_BASE_URL),
10
+ edgeUrl: stripSlash(env.KELVIQ_EDGE_URL?.trim() || DEFAULT_EDGE_URL),
11
+ entitlementsUrl: stripSlash(env.KELVIQ_ENTITLEMENTS_URL?.trim() || DEFAULT_ENTITLEMENTS_URL),
12
+ userAgent: `kelviq-mcp/${getPackageVersion()} (+https://kelviq.com)`,
13
+ };
14
+ }
15
+ import { createRequire } from 'node:module';
16
+ function getPackageVersion() {
17
+ try {
18
+ const require = createRequire(import.meta.url);
19
+ const pkg = require('../package.json');
20
+ return pkg.version ?? 'dev';
21
+ }
22
+ catch {
23
+ return 'dev';
24
+ }
25
+ }
26
+ export function requireKey(config, scope) {
27
+ const key = scope === 'server' ? config.serverApiKey : config.clientApiKey;
28
+ if (!key) {
29
+ const envVar = scope === 'server' ? 'KELVIQ_SERVER_API_KEY' : 'KELVIQ_CLIENT_API_KEY';
30
+ throw new MissingKeyError(envVar, scope);
31
+ }
32
+ return key;
33
+ }
34
+ export class MissingKeyError extends Error {
35
+ envVar;
36
+ scope;
37
+ constructor(envVar, scope) {
38
+ super(`Missing ${envVar}. Set it in your MCP client config to enable ${scope}-scoped Kelviq API tools. ` +
39
+ `Get keys at https://app.kelviq.com/settings/api-keys.`);
40
+ this.envVar = envVar;
41
+ this.scope = scope;
42
+ this.name = 'MissingKeyError';
43
+ }
44
+ }
45
+ //# sourceMappingURL=config.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAWA,MAAM,gBAAgB,GAAG,+BAA+B,CAAC;AACzD,MAAM,gBAAgB,GAAG,gCAAgC,CAAC;AAC1D,MAAM,wBAAwB,GAAG,6BAA6B,CAAC;AAE/D,MAAM,UAAU,UAAU,CAAC,MAAyB,OAAO,CAAC,GAAG;IAC7D,MAAM,UAAU,GAAG,CAAC,CAAS,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACxD,OAAO;QACL,YAAY,EAAE,GAAG,CAAC,qBAAqB,EAAE,IAAI,EAAE,IAAI,SAAS;QAC5D,YAAY,EAAE,GAAG,CAAC,qBAAqB,EAAE,IAAI,EAAE,IAAI,SAAS;QAC5D,OAAO,EAAE,UAAU,CAAC,GAAG,CAAC,eAAe,EAAE,IAAI,EAAE,IAAI,gBAAgB,CAAC;QACpE,OAAO,EAAE,UAAU,CAAC,GAAG,CAAC,eAAe,EAAE,IAAI,EAAE,IAAI,gBAAgB,CAAC;QACpE,eAAe,EAAE,UAAU,CAAC,GAAG,CAAC,uBAAuB,EAAE,IAAI,EAAE,IAAI,wBAAwB,CAAC;QAC5F,SAAS,EAAE,cAAc,iBAAiB,EAAE,wBAAwB;KACrE,CAAC;AACJ,CAAC;AAED,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,SAAS,iBAAiB;IACxB,IAAI,CAAC;QACH,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAC/C,MAAM,GAAG,GAAG,OAAO,CAAC,iBAAiB,CAAyB,CAAC;QAC/D,OAAO,GAAG,CAAC,OAAO,IAAI,KAAK,CAAC;IAC9B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,MAAoB,EAAE,KAAgB;IAC/D,MAAM,GAAG,GAAG,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC,CAAC,MAAM,CAAC,YAAY,CAAC;IAC3E,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,MAAM,GAAG,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,uBAAuB,CAAC,CAAC,CAAC,uBAAuB,CAAC;QACtF,MAAM,IAAI,eAAe,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAC3C,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,MAAM,OAAO,eAAgB,SAAQ,KAAK;IACZ;IAAgC;IAA5D,YAA4B,MAAc,EAAkB,KAAgB;QAC1E,KAAK,CACH,WAAW,MAAM,gDAAgD,KAAK,4BAA4B;YAChG,uDAAuD,CAC1D,CAAC;QAJwB,WAAM,GAAN,MAAM,CAAQ;QAAkB,UAAK,GAAL,KAAK,CAAW;QAK1E,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF"}
@@ -0,0 +1,128 @@
1
+ # Kelviq Documentation
2
+
3
+ Complete documentation for Kelviq, the SaaS monetization and subscription management platform.
4
+
5
+ ## Getting Started
6
+
7
+ ### For Product Teams
8
+ - [Introduction to Kelviq](getstarted/introduction-to-kelviq.mdx) - Overview and features
9
+ - [Getting Started](quickstart/dashboard-setup.mdx) - Dashboard setup and first steps
10
+ - [Review Process](getstarted/review-process.mdx) - Business verification and compliance
11
+
12
+ ### For Developers
13
+ - [Core Concepts](quickstart/core-concepts.mdx) - Key terminology and architecture
14
+ - [Integration Guide](quickstart/integrate-with-your-app.mdx) - How to integrate Kelviq
15
+ - [API Reference](api-reference/openapi.json) - Complete API documentation
16
+
17
+ ## Key Features
18
+
19
+ ### Product Management
20
+ - **[Products](/product-catalog/products)** - Create and manage your digital products
21
+ - **[Plans & Pricing](/product-catalog/plans)** - Configure flexible pricing models
22
+ - **[Features](/product-catalog/features)** - Define feature access and limits
23
+ - **[Digital Downloads](/product-catalog/digital-downloads)** - Deliver files after purchase
24
+ - **[License Keys](/product-catalog/license-keys)** - Manage software licensing
25
+ - **[Entitlements](/product-catalog/entitlements)** - Control feature access per customer
26
+
27
+ ### Monetization
28
+ - **[Checkout](/checkout/checkout-configuration)** - Configure and customize checkout
29
+ - **[Customers](customers/customers)** - Manage customer subscriptions
30
+ - **[Webhooks](webhooks/webhooks)** - Real-time event notifications
31
+ - **[Webhooks](webhooks/webhooks)** - Real-time event notifications
32
+
33
+ ### Developer Tools
34
+ - **[Authentication](api-reference/authentication)** - API key setup
35
+ - **[Error Codes](api-reference/errors)** - Error handling reference
36
+ - **[Python SDK](backend-integration/python-sdk)** - Backend integration
37
+ - **[Node.js SDK](backend-integration/node-sdk)** - Backend integration
38
+ - **[React SDK](frontend-integration/react-sdk)** - Frontend integration
39
+ - **[React UI](frontend-integration/react-ui)** - Pre-built components
40
+
41
+ ## Common Tasks
42
+
43
+ - [Set up a free trial](product-catalog/plans) for your first plan
44
+ - [Configure multi-currency pricing](product-catalog/plans) with regional pricing
45
+ - [Deliver digital files](product-catalog/digital-downloads) to customers
46
+ - [Generate license keys](product-catalog/license-keys) automatically
47
+ - [Track feature usage](product-catalog/entitlements) per customer
48
+ - [Listen to webhooks](webhooks/webhooks) for real-time events
49
+
50
+ ## Troubleshooting
51
+
52
+ Having issues? Check the [Troubleshooting Guide](troubleshooting/common-issues) for solutions to common problems.
53
+
54
+ ## Support
55
+
56
+ - **Documentation** - You're reading it!
57
+ - **API Docs** - [Full API Reference](api-reference/openapi.json)
58
+ - **Email Support** - hi@kelviq.com
59
+ - **Status Page** - status.kelviq.com
60
+
61
+ ## Local Development
62
+
63
+ To preview documentation changes locally:
64
+
65
+ ### Install Mintlify CLI
66
+ ```bash
67
+ npm i -g mint
68
+ ```
69
+
70
+ ### Run dev server
71
+ ```bash
72
+ mint dev
73
+ ```
74
+
75
+ ### View preview
76
+ Open `http://localhost:3000` in your browser.
77
+
78
+ ## Deploying Changes
79
+
80
+ Changes to the `main` branch are automatically deployed to production.
81
+
82
+ To preview changes before deployment:
83
+ 1. Create a branch
84
+ 2. Make changes
85
+ 3. Create a pull request
86
+ 4. Preview changes in the Mintlify dashboard
87
+ 5. Merge to deploy
88
+
89
+ ## Documentation Structure
90
+
91
+ ```
92
+ /docs
93
+ ├── getstarted/ # Getting started guides
94
+ ├── quickstart/ # Quickstart and core concepts
95
+ ├── product-catalog/ # Product management docs
96
+ ├── checkout/ # Checkout configuration
97
+ ├── customers/ # Customer management
98
+ ├── api-reference/ # API docs and error codes
99
+ ├── webhooks/ # Webhook documentation
100
+ ├── frontend-integration/# Frontend SDKs
101
+ ├── troubleshooting/ # Troubleshooting guides
102
+ └── docs.json # Navigation and config
103
+ ```
104
+
105
+ ## Contributing
106
+
107
+ To contribute to Kelviq docs:
108
+
109
+ 1. Make your changes in the appropriate directory
110
+ 2. Test locally with `mint dev`
111
+ 3. Create a pull request
112
+ 4. After approval, merge to `main`
113
+ 5. Changes deploy automatically
114
+
115
+ ### Style Guide
116
+
117
+ - Use clear, developer-friendly language
118
+ - Include code examples for API features
119
+ - Use Mintlify components for formatting
120
+ - Link to related documentation
121
+ - Keep sections concise and focused
122
+
123
+ ## Need Help?
124
+
125
+ - **Can't find something?** - Use the search feature (top of page)
126
+ - **Having issues?** - Check [Troubleshooting](troubleshooting/common-issues)
127
+ - **Want to report a bug?** - Email hi@kelviq.com
128
+ - **Have suggestions?** - We'd love your feedback!
@@ -0,0 +1,41 @@
1
+ ---
2
+ title: "Authentication"
3
+ slug: "api-reference/authentication"
4
+ section: "api-reference"
5
+ ---
6
+ kelviq API uses API keys to authenticate requests. All API requests must be made over HTTPS; calls made over plain HTTP will fail. API requests without authentication will also fail.
7
+
8
+ ## API Keys
9
+
10
+ kelviq provides two types of API keys for different use cases.
11
+
12
+
13
+
14
+ Used for frontend applications where the key is publicly accessible.
15
+
16
+
17
+
18
+
19
+ Used for backend implementations. This key has more privileges and must be kept secret.
20
+
21
+
22
+ **Environment Scoping:** API keys are scoped per environment. This means your **production** and **sandbox** environments will have separate and distinct API keys.
23
+
24
+ **Important Security Notice:** Do not share your **Server API Key** in any publicly accessible areas such as frontend code, client-side applications, or public repositories.
25
+
26
+ ### Obtaining Your API Key
27
+
28
+ You can get your API key from the kelviq application dashboard.
29
+
30
+ 1. Navigate to **Settings**.
31
+ 2. Go to the [**API keys**](https://app.kelviq.com/settings/api-keys) section.
32
+ 3. Copy your **Server API Key** to use in your application.
33
+
34
+ ---
35
+
36
+ ## Authorization
37
+
38
+ To authenticate your requests, pass your **Server API Key** as a Bearer token in the `Authorization` header.
39
+
40
+ ```bash
41
+ Authorization: Bearer YOUR_API_KEY