@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.
- package/LICENSE +21 -0
- package/README.md +322 -0
- package/dist/config.d.ts +16 -0
- package/dist/config.js +45 -0
- package/dist/config.js.map +1 -0
- package/dist/docs/README.md +128 -0
- package/dist/docs/api-reference/authentication.md +41 -0
- package/dist/docs/backend-integration/node-sdk.md +1040 -0
- package/dist/docs/backend-integration/python-sdk.md +1198 -0
- package/dist/docs/changelog/app.md +80 -0
- package/dist/docs/changelog/checkout-api.md +59 -0
- package/dist/docs/changelog/js-promotions-ui.md +14 -0
- package/dist/docs/changelog/js-sdk.md +281 -0
- package/dist/docs/changelog/node-sdk.md +378 -0
- package/dist/docs/changelog/python-sdk.md +456 -0
- package/dist/docs/changelog/react-sdk.md +580 -0
- package/dist/docs/checkout/checkout-configuration.md +434 -0
- package/dist/docs/coustomers-management/overview.md +111 -0
- package/dist/docs/customer-portal/overview.md +81 -0
- package/dist/docs/frontend-integration/js-sdk.md +676 -0
- package/dist/docs/frontend-integration/promotions-ui-js.md +265 -0
- package/dist/docs/frontend-integration/react-promotions-ui.md +361 -0
- package/dist/docs/frontend-integration/react-sdk.md +1187 -0
- package/dist/docs/frontend-integration/react-ui.md +771 -0
- package/dist/docs/getstarted/fees.md +160 -0
- package/dist/docs/getstarted/introduction-to-kelviq.md +80 -0
- package/dist/docs/getstarted/merchant-of-record.md +64 -0
- package/dist/docs/getstarted/review-process.md +190 -0
- package/dist/docs/guides/subscription-integration-for-nextjs.md +512 -0
- package/dist/docs/guides/subscription-integration.md +291 -0
- package/dist/docs/guides/webhooks.md +963 -0
- package/dist/docs/legal/approved-prohibited-policy.md +252 -0
- package/dist/docs/legal/buyer-terms.md +177 -0
- package/dist/docs/legal/compliant-user-flow.md +216 -0
- package/dist/docs/legal/master-service-agreement.md +404 -0
- package/dist/docs/legal/payment-flow-diagram.md +188 -0
- package/dist/docs/legal/seller-terms.md +169 -0
- package/dist/docs/manifest.json +415 -0
- package/dist/docs/monetization/offerings.md +156 -0
- package/dist/docs/monetization/pricing-tables.md +226 -0
- package/dist/docs/monetization/targeting-rules.md +278 -0
- package/dist/docs/openapi.json +5479 -0
- package/dist/docs/payouts/overview.md +43 -0
- package/dist/docs/payouts/payout-account.md +12 -0
- package/dist/docs/payouts/transactions.md +23 -0
- package/dist/docs/product-catalog/digital-downloads.md +117 -0
- package/dist/docs/product-catalog/discounts.md +69 -0
- package/dist/docs/product-catalog/entitlements.md +428 -0
- package/dist/docs/product-catalog/free-and-trials.md +36 -0
- package/dist/docs/product-catalog/license-keys.md +324 -0
- package/dist/docs/product-catalog/links.md +92 -0
- package/dist/docs/product-catalog/location-based-pricing.md +41 -0
- package/dist/docs/product-catalog/one-time-payments.md +24 -0
- package/dist/docs/product-catalog/plans.md +199 -0
- package/dist/docs/product-catalog/products.md +60 -0
- package/dist/docs/product-catalog/subscriptions.md +29 -0
- package/dist/docs/product-catalog/tax-settings.md +37 -0
- package/dist/docs/product-catalog/usage-based-billing.md +119 -0
- package/dist/docs/promotions/create-a-promotion.md +75 -0
- package/dist/docs/promotions/customize-banner.md +41 -0
- package/dist/docs/promotions/integrate.md +38 -0
- package/dist/docs/promotions/overview.md +51 -0
- package/dist/docs/quickstart/core-concepts.md +146 -0
- package/dist/docs/quickstart/dashboard-setup.md +129 -0
- package/dist/docs/quickstart/integrate-with-your-app.md +149 -0
- package/dist/docs/sales/checkout-sessions.md +58 -0
- package/dist/docs/sales/orders.md +76 -0
- package/dist/http/client.d.ts +28 -0
- package/dist/http/client.js +76 -0
- package/dist/http/client.js.map +1 -0
- package/dist/http/errors.d.ts +20 -0
- package/dist/http/errors.js +58 -0
- package/dist/http/errors.js.map +1 -0
- package/dist/resources/docs-index.d.ts +25 -0
- package/dist/resources/docs-index.js +109 -0
- package/dist/resources/docs-index.js.map +1 -0
- package/dist/resources/index.d.ts +2 -0
- package/dist/resources/index.js +73 -0
- package/dist/resources/index.js.map +1 -0
- package/dist/schemas/kelviq.d.ts +1304 -0
- package/dist/schemas/kelviq.js +468 -0
- package/dist/schemas/kelviq.js.map +1 -0
- package/dist/server.d.ts +2 -0
- package/dist/server.js +41 -0
- package/dist/server.js.map +1 -0
- package/dist/tools/_util.d.ts +15 -0
- package/dist/tools/_util.js +15 -0
- package/dist/tools/_util.js.map +1 -0
- package/dist/tools/checkout.d.ts +3 -0
- package/dist/tools/checkout.js +18 -0
- package/dist/tools/checkout.js.map +1 -0
- package/dist/tools/customers.d.ts +3 -0
- package/dist/tools/customers.js +32 -0
- package/dist/tools/customers.js.map +1 -0
- package/dist/tools/docs.d.ts +2 -0
- package/dist/tools/docs.js +43 -0
- package/dist/tools/docs.js.map +1 -0
- package/dist/tools/entitlements.d.ts +3 -0
- package/dist/tools/entitlements.js +22 -0
- package/dist/tools/entitlements.js.map +1 -0
- package/dist/tools/features.d.ts +3 -0
- package/dist/tools/features.js +55 -0
- package/dist/tools/features.js.map +1 -0
- package/dist/tools/index.d.ts +3 -0
- package/dist/tools/index.js +44 -0
- package/dist/tools/index.js.map +1 -0
- package/dist/tools/licenses.d.ts +3 -0
- package/dist/tools/licenses.js +44 -0
- package/dist/tools/licenses.js.map +1 -0
- package/dist/tools/media.d.ts +3 -0
- package/dist/tools/media.js +18 -0
- package/dist/tools/media.js.map +1 -0
- package/dist/tools/offerings.d.ts +3 -0
- package/dist/tools/offerings.js +21 -0
- package/dist/tools/offerings.js.map +1 -0
- package/dist/tools/partner.d.ts +3 -0
- package/dist/tools/partner.js +55 -0
- package/dist/tools/partner.js.map +1 -0
- package/dist/tools/plan-entitlements.d.ts +3 -0
- package/dist/tools/plan-entitlements.js +56 -0
- package/dist/tools/plan-entitlements.js.map +1 -0
- package/dist/tools/plan-files.d.ts +3 -0
- package/dist/tools/plan-files.js +43 -0
- package/dist/tools/plan-files.js.map +1 -0
- package/dist/tools/plans.d.ts +3 -0
- package/dist/tools/plans.js +120 -0
- package/dist/tools/plans.js.map +1 -0
- package/dist/tools/portal.d.ts +3 -0
- package/dist/tools/portal.js +18 -0
- package/dist/tools/portal.js.map +1 -0
- package/dist/tools/product-files.d.ts +3 -0
- package/dist/tools/product-files.js +31 -0
- package/dist/tools/product-files.js.map +1 -0
- package/dist/tools/product-settings.d.ts +3 -0
- package/dist/tools/product-settings.js +31 -0
- package/dist/tools/product-settings.js.map +1 -0
- package/dist/tools/products.d.ts +3 -0
- package/dist/tools/products.js +69 -0
- package/dist/tools/products.js.map +1 -0
- package/dist/tools/promotions.d.ts +3 -0
- package/dist/tools/promotions.js +19 -0
- package/dist/tools/promotions.js.map +1 -0
- package/dist/tools/subscriptions.d.ts +3 -0
- package/dist/tools/subscriptions.js +63 -0
- package/dist/tools/subscriptions.js.map +1 -0
- package/dist/tools/usage.d.ts +3 -0
- package/dist/tools/usage.js +18 -0
- package/dist/tools/usage.js.map +1 -0
- 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)
|
package/dist/config.d.ts
ADDED
|
@@ -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
|