@kelviq/mcp-server 1.0.0 → 1.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/README.md +25 -7
- package/dist/docs/README.md +16 -0
- package/dist/docs/backend-integration/node-sdk.md +41 -17
- package/dist/docs/backend-integration/python-sdk.md +16 -17
- package/dist/docs/changelog.md +4076 -0
- package/dist/docs/cli/commands.md +140 -5
- package/dist/docs/cli/environments.md +3 -3
- package/dist/docs/cli/kelviq-config.md +28 -7
- package/dist/docs/cli/overview.md +11 -9
- package/dist/docs/guides/agent-toolkit.md +3 -3
- package/dist/docs/guides/mcp-server.md +36 -5
- package/dist/docs/guides/webhooks.md +1 -1
- package/dist/docs/manifest.json +5 -61
- package/dist/docs/product-catalog/free-and-trials.md +13 -0
- package/dist/docs/product-catalog/license-keys.md +13 -0
- package/dist/http/client.d.ts +7 -0
- package/dist/http/client.js +9 -0
- package/dist/http/client.js.map +1 -1
- package/dist/prompts/index.js +11 -11
- package/dist/prompts/index.js.map +1 -1
- package/dist/schemas/kelviq.d.ts +200 -0
- package/dist/schemas/kelviq.js +178 -3
- package/dist/schemas/kelviq.js.map +1 -1
- package/dist/server.js +2 -0
- package/dist/server.js.map +1 -1
- package/dist/tools/_resolve.d.ts +4 -0
- package/dist/tools/_resolve.js +46 -0
- package/dist/tools/_resolve.js.map +1 -0
- package/dist/tools/connection.d.ts +12 -0
- package/dist/tools/connection.js +44 -0
- package/dist/tools/connection.js.map +1 -0
- package/dist/tools/discounts.d.ts +3 -0
- package/dist/tools/discounts.js +86 -0
- package/dist/tools/discounts.js.map +1 -0
- package/dist/tools/index.js +7 -0
- package/dist/tools/index.js.map +1 -1
- package/dist/tools/offerings.js +6 -2
- package/dist/tools/offerings.js.map +1 -1
- package/dist/tools/plan-entitlements.js +11 -3
- package/dist/tools/plan-entitlements.js.map +1 -1
- package/dist/tools/plans.js +6 -2
- package/dist/tools/plans.js.map +1 -1
- package/dist/tools/webhooks.d.ts +10 -0
- package/dist/tools/webhooks.js +114 -0
- package/dist/tools/webhooks.js.map +1 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -13,7 +13,7 @@ capabilities at once:
|
|
|
13
13
|
inside the package and exposed as MCP resources plus `docs_search` /
|
|
14
14
|
`docs_read` tools, so the LLM can ground its answers in the canonical docs.
|
|
15
15
|
|
|
16
|
-
> **
|
|
16
|
+
> **57 tools** across **12 domains**, plus a resource for every docs page and
|
|
17
17
|
> the full OpenAPI spec. Works offline for docs Q&A — only API tools require a
|
|
18
18
|
> key.
|
|
19
19
|
|
|
@@ -114,6 +114,14 @@ precedence over `KELVIQ_ENV`.
|
|
|
114
114
|
|
|
115
115
|
## Tools
|
|
116
116
|
|
|
117
|
+
Tools that take a product or feature reference (`plan_create`,
|
|
118
|
+
`plan_entitlements_add`, `discount_create`, `offering_get_product`) accept
|
|
119
|
+
either the UUID or the human-readable identifier; identifiers are resolved
|
|
120
|
+
through the retrieve endpoints before anything is written.
|
|
121
|
+
|
|
122
|
+
### Connection
|
|
123
|
+
- `connection_check` — reports the environment (env, base/edge URLs) and whether the server key is accepted, without printing it
|
|
124
|
+
|
|
117
125
|
### Customers
|
|
118
126
|
- `customer_create` — create a customer
|
|
119
127
|
- `customer_update` — patch an existing customer
|
|
@@ -134,9 +142,17 @@ precedence over `KELVIQ_ENV`.
|
|
|
134
142
|
- `usage_report` — report metered usage (`SET` or `DELTA`)
|
|
135
143
|
|
|
136
144
|
### Offerings & Promotions
|
|
137
|
-
- `offering_get_product` — public pricing scoped to a product UUID
|
|
145
|
+
- `offering_get_product` — public pricing scoped to a product (UUID or identifier)
|
|
138
146
|
- `promotion_get` — resolve the active promotion for the caller's location *(uses Client API key, edge host)*
|
|
139
147
|
|
|
148
|
+
### Discounts
|
|
149
|
+
- `discount_list` / `discount_create` (`appliesTo[].product` takes a UUID or identifier) / `discount_retrieve` / `discount_archive`
|
|
150
|
+
- `discount_update` — enable or disable a code (nothing else can change after creation)
|
|
151
|
+
|
|
152
|
+
### Webhooks
|
|
153
|
+
- `webhook_endpoint_list` / `webhook_endpoint_create` / `webhook_endpoint_retrieve` / `webhook_endpoint_update` / `webhook_endpoint_delete` — signing secrets are hidden unless `revealSecret: true`
|
|
154
|
+
- `webhook_log_list` — delivery attempts from the last 30 days
|
|
155
|
+
|
|
140
156
|
### Catalog: Products
|
|
141
157
|
- `product_list` / `product_create` / `product_retrieve` / `product_update` / `product_archive`
|
|
142
158
|
- `product_settings_get` / `product_settings_update` — VPN/Tor/proxy policy, default currency, product URL
|
|
@@ -146,11 +162,11 @@ precedence over `KELVIQ_ENV`.
|
|
|
146
162
|
- `feature_list` / `feature_create` / `feature_retrieve` / `feature_archive`
|
|
147
163
|
|
|
148
164
|
### Catalog: Plans
|
|
149
|
-
- `plan_list` / `plan_create` / `plan_retrieve` / `plan_update` / `plan_archive`
|
|
165
|
+
- `plan_list` / `plan_create` (`product` takes a UUID or identifier) / `plan_retrieve` / `plan_update` / `plan_archive`
|
|
150
166
|
- `plan_publish` — release the latest draft, optionally migrate existing customers
|
|
151
167
|
- `plan_discard_draft` — drop the current draft, keep the published version
|
|
152
168
|
- `plan_prices_list` — per-currency pricing on a plan
|
|
153
|
-
- `plan_entitlements_list` / `plan_entitlements_add` / `plan_entitlement_update` / `plan_entitlement_delete`
|
|
169
|
+
- `plan_entitlements_list` / `plan_entitlements_add` (`feature` takes a UUID or identifier) / `plan_entitlement_update` / `plan_entitlement_delete`
|
|
154
170
|
- `plan_file_update` / `plan_file_delete` / `plan_file_download` — plan-attached digital deliverables
|
|
155
171
|
|
|
156
172
|
### Docs (no API key required)
|
|
@@ -172,7 +188,7 @@ Once wired into your MCP client, try prompts like:
|
|
|
172
188
|
|
|
173
189
|
- *"Search Kelviq docs for license keys"* → `docs_search` + `docs_read`
|
|
174
190
|
- *"List my Kelviq products"* → `product_list`
|
|
175
|
-
- *"Create a plan named 'Pro Monthly' under product
|
|
191
|
+
- *"Create a plan named 'Pro Monthly' under product `acme-app`, then publish it"* → `plan_create` → `plan_publish`
|
|
176
192
|
- *"What entitlements does customer `acme-42` have for `seats`?"* → `entitlements_get`
|
|
177
193
|
- *"Create a checkout session for plan `pro-monthly`, success URL `https://example.com/ok`"* → `checkout_create_session`
|
|
178
194
|
- *"What prices are configured on plan `pro-monthly`?"* → `plan_prices_list`
|
|
@@ -189,7 +205,7 @@ npx -y @modelcontextprotocol/inspector \
|
|
|
189
205
|
npx -y @kelviq/mcp-server@latest
|
|
190
206
|
```
|
|
191
207
|
|
|
192
|
-
Opens a browser UI where you can browse all
|
|
208
|
+
Opens a browser UI where you can browse all 57 tools, fill in arguments, and
|
|
193
209
|
run them against the real Kelviq API. Pre-fill env vars by exporting them
|
|
194
210
|
before the command:
|
|
195
211
|
|
|
@@ -238,7 +254,9 @@ PATH. Either:
|
|
|
238
254
|
### Tool returns `{"error": {"status": "Configuration error", …}}`
|
|
239
255
|
|
|
240
256
|
Means a required env var is missing. The error message names which one. Set
|
|
241
|
-
it in your MCP client config and reconnect.
|
|
257
|
+
it in your MCP client config and reconnect. Ask the LLM to run
|
|
258
|
+
`connection_check` to see which environment the server is using and whether
|
|
259
|
+
the server key is accepted — it never prints the key.
|
|
242
260
|
|
|
243
261
|
### API tool returns `{"error": {"status": "Bad request", "message": "Invalid product identifier"}}`
|
|
244
262
|
|
package/dist/docs/README.md
CHANGED
|
@@ -120,6 +120,22 @@ To contribute to Kelviq docs:
|
|
|
120
120
|
- Link to related documentation
|
|
121
121
|
- Keep sections concise and focused
|
|
122
122
|
|
|
123
|
+
### Changelog
|
|
124
|
+
|
|
125
|
+
All release notes live in one page, `changelog.mdx`, newest first. Add each release as an `<Update>` at the top of the page, tagged with the product exactly as it appears in the filter. The product filter above the entries matches on that tag, and so does the sidebar:
|
|
126
|
+
|
|
127
|
+
```mdx
|
|
128
|
+
<Update label="v2.9.0" description="October 1, 2026" tags={["Node SDK"]}>
|
|
129
|
+
...
|
|
130
|
+
</Update>
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
Keep the label a plain string; an expression label loses its anchor link. Products are `App`, `JS SDK`, `React SDK`, `Node SDK`, `Python SDK`, `JS Promotions UI`, `MCP Server`, `CLI`, and `API`.
|
|
134
|
+
|
|
135
|
+
The sidebar lists the same products, as anchors under the Changelog tab in `docs.json`. They must be written as absolute URLs (`https://docs.kelviq.com/changelog#node-sdk`): Mintlify rewrites a relative href containing a hash to `/`. Absolute URLs would open in a new tab, so `ChangelogFilter` rewrites them back to same-page links once the page loads. To add a product, add it in three places: the `products` list passed to `<ChangelogFilter>`, the anchors in `docs.json`, and the redirect if the product had its own page before.
|
|
136
|
+
|
|
137
|
+
Those anchors would otherwise carry an icon and no group title, so `custom.css` hides the icon, heads the list with "Changelog", and highlights whichever product is selected. Those rules only apply while `ChangelogFilter` is on screen, which it marks with `data-changelog-page` on the body.
|
|
138
|
+
|
|
123
139
|
## Need Help?
|
|
124
140
|
|
|
125
141
|
- **Can't find something?** - Use the search feature (top of page)
|
|
@@ -1506,25 +1506,38 @@ app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
|
|
|
1506
1506
|
|
|
1507
1507
|
Use `express.raw()` (not `express.json()`) so that the raw request body is preserved for signature verification. Parsing the body as JSON before verification will break the signature check.
|
|
1508
1508
|
|
|
1509
|
+
On a framework built on the Fetch API — Next.js route handlers, Hono, Remix, SvelteKit, Cloudflare Workers — `request.headers` is a `Headers` object, not a plain object. Convert it with `Object.fromEntries`, and read the body with `request.text()` so it stays unparsed:
|
|
1510
|
+
|
|
1511
|
+
```typescript
|
|
1512
|
+
import { validateEvent, WebhookVerificationError } from '@kelviq/node-sdk';
|
|
1513
|
+
|
|
1514
|
+
export async function POST(request: Request) {
|
|
1515
|
+
const body = await request.text();
|
|
1516
|
+
|
|
1517
|
+
try {
|
|
1518
|
+
const event = validateEvent(
|
|
1519
|
+
body,
|
|
1520
|
+
Object.fromEntries(request.headers),
|
|
1521
|
+
process.env.KELVIQ_WEBHOOK_SECRET!,
|
|
1522
|
+
);
|
|
1523
|
+
|
|
1524
|
+
console.log('Event type:', event.type);
|
|
1525
|
+
|
|
1526
|
+
return new Response(null, { status: 202 });
|
|
1527
|
+
} catch (err) {
|
|
1528
|
+
if (err instanceof WebhookVerificationError) {
|
|
1529
|
+
return new Response(null, { status: 403 });
|
|
1530
|
+
}
|
|
1531
|
+
throw err;
|
|
1532
|
+
}
|
|
1533
|
+
}
|
|
1534
|
+
```
|
|
1535
|
+
|
|
1536
|
+
Passing a `Headers` object straight to `validateEvent` fails with `Missing required webhook headers`, because the helper reads headers as plain object entries.
|
|
1537
|
+
|
|
1509
1538
|
### Webhook event types
|
|
1510
1539
|
|
|
1511
|
-
|
|
1512
|
-
|---|---|
|
|
1513
|
-
| `checkout.completed` | A checkout session was completed |
|
|
1514
|
-
| `customer.created` | A new customer was created |
|
|
1515
|
-
| `customer.updated` | A customer's details were updated |
|
|
1516
|
-
| `order.created` | A new order was placed |
|
|
1517
|
-
| `order.updated` | An order was updated |
|
|
1518
|
-
| `order.refunded` | An order was refunded |
|
|
1519
|
-
| `subscription.created` | A new subscription was created |
|
|
1520
|
-
| `subscription.updated` | A subscription was updated |
|
|
1521
|
-
| `subscription.cancelled` | A subscription was cancelled |
|
|
1522
|
-
| `subscription.plan_changed` | A subscription plan was changed |
|
|
1523
|
-
| `feature.usage_alert` | A feature's usage crossed a threshold configured when the entitlement was added to the plan |
|
|
1524
|
-
| `invoice.created` | A new invoice was created |
|
|
1525
|
-
| `invoice.paid` | An invoice was paid |
|
|
1526
|
-
| `refund.created` | A refund was initiated |
|
|
1527
|
-
| `refund.updated` | A refund status changed |
|
|
1540
|
+
See [Webhook event types](/guides/webhooks#event-types) for the complete list of supported events and their descriptions.
|
|
1528
1541
|
|
|
1529
1542
|
### Best practices
|
|
1530
1543
|
|
|
@@ -1547,4 +1560,15 @@ const client = new Kelviq({
|
|
|
1547
1560
|
|
|
1548
1561
|
```
|
|
1549
1562
|
|
|
1563
|
+
To pick the environment from the `KELVIQ_ENV` variable that the Kelviq CLI and MCP server also read, use `environmentFromEnv()`: it returns `'sandbox'` when `KELVIQ_ENV` is unset or empty, `'production'` or `'sandbox'` when it is set to one of those, and throws on any other value.
|
|
1564
|
+
|
|
1565
|
+
```typescript
|
|
1566
|
+
import { Kelviq, environmentFromEnv } from '@kelviq/node-sdk';
|
|
1567
|
+
|
|
1568
|
+
const client = new Kelviq({
|
|
1569
|
+
accessToken: process.env.KELVIQ_SERVER_API_KEY!,
|
|
1570
|
+
environment: environmentFromEnv(), // reads KELVIQ_ENV: sandbox when unset
|
|
1571
|
+
});
|
|
1572
|
+
```
|
|
1573
|
+
|
|
1550
1574
|
The sandbox environment is completely separate from production. You will need to use a different set of API keys, and any data created (customers, subscriptions, etc.) will only exist in the sandbox.
|
|
@@ -1774,23 +1774,7 @@ Always pass the **raw** request body (e.g. `request.data` in Flask) to `validate
|
|
|
1774
1774
|
|
|
1775
1775
|
### Webhook event types
|
|
1776
1776
|
|
|
1777
|
-
|
|
1778
|
-
|---|---|
|
|
1779
|
-
| `checkout.completed` | A checkout session was completed |
|
|
1780
|
-
| `customer.created` | A new customer was created |
|
|
1781
|
-
| `customer.updated` | A customer's details were updated |
|
|
1782
|
-
| `order.created` | A new order was placed |
|
|
1783
|
-
| `order.updated` | An order was updated |
|
|
1784
|
-
| `order.refunded` | An order was refunded |
|
|
1785
|
-
| `subscription.created` | A new subscription was created |
|
|
1786
|
-
| `subscription.updated` | A subscription was updated |
|
|
1787
|
-
| `subscription.cancelled` | A subscription was cancelled |
|
|
1788
|
-
| `subscription.plan_changed` | A subscription plan was changed |
|
|
1789
|
-
| `feature.usage_alert` | A feature's usage crossed a threshold configured when the entitlement was added to the plan |
|
|
1790
|
-
| `invoice.created` | A new invoice was created |
|
|
1791
|
-
| `invoice.paid` | An invoice was paid |
|
|
1792
|
-
| `refund.created` | A refund was initiated |
|
|
1793
|
-
| `refund.updated` | A refund status changed |
|
|
1777
|
+
See [Webhook event types](/guides/webhooks#event-types) for the complete list of supported events and their descriptions.
|
|
1794
1778
|
|
|
1795
1779
|
### Best practices
|
|
1796
1780
|
|
|
@@ -1816,5 +1800,20 @@ client = Kelviq.create_sync_client(
|
|
|
1816
1800
|
environment="sandbox"
|
|
1817
1801
|
)
|
|
1818
1802
|
```
|
|
1803
|
+
### Reading the environment from `KELVIQ_ENV`
|
|
1804
|
+
|
|
1805
|
+
`environment_from_env()` turns the `KELVIQ_ENV` convention shared with the Kelviq CLI and MCP server into the `environment` argument: `"sandbox"` when the variable is unset or empty, `"production"` or `"sandbox"` when it is set to one of those, and a `ValueError` naming any other value.
|
|
1806
|
+
|
|
1807
|
+
```python
|
|
1808
|
+
import os
|
|
1809
|
+
from kelviq_sdk import Kelviq, environment_from_env
|
|
1810
|
+
|
|
1811
|
+
client = Kelviq.create_sync_client(
|
|
1812
|
+
access_token=os.environ["KELVIQ_SERVER_API_KEY"],
|
|
1813
|
+
environment=environment_from_env(), # reads KELVIQ_ENV: sandbox when unset
|
|
1814
|
+
)
|
|
1815
|
+
```
|
|
1816
|
+
|
|
1817
|
+
`environment="production"` and `environment="prod"` mean the same thing.
|
|
1819
1818
|
|
|
1820
1819
|
The sandbox environment is completely separate from production. You will need to use a different set of API keys, and any data created (customers, subscriptions, etc.) will only exist in the sandbox.
|