@kelviq/mcp-server 1.2.0 → 1.3.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 +40 -3
- package/dist/config.d.ts +5 -0
- package/dist/config.js +1 -0
- package/dist/config.js.map +1 -1
- package/dist/docs/ai/docs-for-agents.md +21 -0
- package/dist/docs/ai/overview.md +43 -0
- package/dist/docs/api-reference/authentication.md +9 -3
- package/dist/docs/api-reference/introduction.md +23 -2
- package/dist/docs/backend-integration/node-sdk.md +12 -6
- package/dist/docs/backend-integration/python-sdk.md +14 -8
- package/dist/docs/changelog.md +369 -3
- package/dist/docs/checkout/checkout-configuration.md +25 -75
- package/dist/docs/checkout/checkout-design.md +76 -0
- package/dist/docs/checkout/checkout-examples.md +212 -0
- package/dist/docs/checkout/checkout-metadata.md +1 -1
- package/dist/docs/checkout/custom-fields.md +60 -0
- package/dist/docs/checkout/embed-checkout.md +280 -0
- package/dist/docs/checkout/payment-methods/upi.md +69 -0
- package/dist/docs/checkout/payment-methods.md +119 -0
- package/dist/docs/checkout/static-checkout-url.md +3 -2
- package/dist/docs/cli/commands.md +57 -4
- package/dist/docs/cli/kelviq-config.md +1 -1
- package/dist/docs/cli/overview.md +1 -0
- package/dist/docs/customer-portal/managing-payment-methods.md +4 -4
- package/dist/docs/customer-portal/overview.md +7 -7
- package/dist/docs/customer-portal/retention.md +109 -0
- package/dist/docs/customers-management/overview.md +105 -0
- package/dist/docs/frontend-integration/js-sdk.md +11 -11
- package/dist/docs/frontend-integration/promotions-ui-js.md +2 -2
- package/dist/docs/frontend-integration/react-sdk.md +8 -49
- package/dist/docs/frontend-integration/react-ui.md +8 -6
- package/dist/docs/getstarted/fees.md +27 -11
- package/dist/docs/getstarted/introduction-to-kelviq.md +29 -66
- package/dist/docs/getstarted/merchant-of-record.md +18 -24
- package/dist/docs/getstarted/overview.md +98 -0
- package/dist/docs/getstarted/review-process.md +59 -59
- package/dist/docs/guides/agent-toolkit.md +14 -9
- package/dist/docs/guides/mcp-server.md +24 -9
- package/dist/docs/guides/migrate-from-lemon-squeezy.md +405 -0
- package/dist/docs/guides/sandbox.md +6 -4
- package/dist/docs/guides/set-up-with-ai.md +43 -0
- package/dist/docs/guides/subscription-integration-for-nextjs.md +10 -11
- package/dist/docs/guides/subscription-integration.md +1 -1
- package/dist/docs/guides/test-payments.md +640 -0
- package/dist/docs/guides/webhooks.md +182 -30
- package/dist/docs/integrations/woocommerce.md +88 -0
- package/dist/docs/integrations/zapier.md +22 -0
- package/dist/docs/legal/account-and-funds.md +59 -0
- package/dist/docs/legal/approved-prohibited-policy.md +32 -27
- package/dist/docs/legal/payment-flow-diagram.md +7 -7
- package/dist/docs/manifest.json +160 -41
- package/dist/docs/openapi.json +1359 -109
- package/dist/docs/payouts/overview.md +14 -12
- package/dist/docs/payouts/payout-account.md +1 -1
- package/dist/docs/payouts/transactions.md +3 -3
- package/dist/docs/product-catalog/create-a-feature.md +3 -3
- package/dist/docs/product-catalog/digital-downloads.md +5 -5
- package/dist/docs/product-catalog/discounts.md +2 -2
- package/dist/docs/product-catalog/entitlements.md +20 -27
- package/dist/docs/product-catalog/free-and-trials.md +5 -5
- package/dist/docs/product-catalog/license-keys.md +56 -29
- package/dist/docs/product-catalog/links.md +3 -3
- package/dist/docs/product-catalog/location-based-pricing.md +6 -10
- package/dist/docs/product-catalog/one-time-payments.md +3 -7
- package/dist/docs/product-catalog/pay-as-you-go.md +8 -8
- package/dist/docs/product-catalog/plans.md +22 -19
- package/dist/docs/product-catalog/products.md +11 -3
- package/dist/docs/product-catalog/proration.md +69 -0
- package/dist/docs/product-catalog/seat-based-pricing.md +7 -7
- package/dist/docs/product-catalog/subscriptions.md +52 -22
- package/dist/docs/product-catalog/tax-settings.md +8 -8
- package/dist/docs/product-catalog/usage-alerts.md +7 -7
- package/dist/docs/product-catalog/usage-based-billing.md +156 -29
- package/dist/docs/product-catalog/usage-limits.md +78 -0
- package/dist/docs/promotions/create-a-promotion.md +2 -2
- package/dist/docs/promotions/overview.md +1 -1
- package/dist/docs/quickstart/core-concepts.md +36 -30
- package/dist/docs/quickstart/dashboard-setup.md +26 -22
- package/dist/docs/quickstart/integrate-with-your-app.md +133 -52
- package/dist/docs/sales/abandoned-cart-recovery.md +7 -3
- package/dist/docs/sales/checkout-sessions.md +28 -39
- package/dist/docs/sales/orders.md +30 -54
- package/dist/docs/settings/customer-emails.md +52 -0
- package/dist/docs/settings/members.md +27 -0
- package/dist/docs/settings/profile.md +26 -0
- package/dist/docs/settings/zapier.md +22 -0
- package/dist/http/errors.d.ts +20 -1
- package/dist/http/errors.js +83 -31
- package/dist/http/errors.js.map +1 -1
- package/dist/schemas/kelviq.d.ts +54 -0
- package/dist/schemas/kelviq.js +64 -0
- package/dist/schemas/kelviq.js.map +1 -1
- package/dist/server.js +3 -2
- package/dist/server.js.map +1 -1
- package/dist/tools/_resolve.js +14 -10
- package/dist/tools/_resolve.js.map +1 -1
- package/dist/tools/features.js +9 -2
- package/dist/tools/features.js.map +1 -1
- package/dist/tools/imports.d.ts +68 -0
- package/dist/tools/imports.js +242 -0
- package/dist/tools/imports.js.map +1 -0
- package/dist/tools/index.d.ts +2 -1
- package/dist/tools/index.js +4 -1
- package/dist/tools/index.js.map +1 -1
- package/dist/tools/product-files.js +10 -3
- package/dist/tools/product-files.js.map +1 -1
- package/dist/tools/product-settings.js +10 -3
- package/dist/tools/product-settings.js.map +1 -1
- package/dist/tools/products.js +14 -4
- package/dist/tools/products.js.map +1 -1
- package/package.json +1 -1
|
@@ -3,7 +3,7 @@ title: "Review Process"
|
|
|
3
3
|
slug: "getstarted/review-process"
|
|
4
4
|
section: "getstarted"
|
|
5
5
|
---
|
|
6
|
-
|
|
6
|
+
Kelviq is the seller of record for every sale, so we check each business before it takes live payments. You can build and test in sandbox right away. Most reviews finish within 24 hours.
|
|
7
7
|
|
|
8
8
|
This guide outlines what we support, what we prohibit, and how our review process works.
|
|
9
9
|
|
|
@@ -19,13 +19,13 @@ Kelviq is optimized for **digital products and software**. We are the best fit f
|
|
|
19
19
|
> **The Golden Rule:**
|
|
20
20
|
> Your product should be **digital**, **owned by you** (or properly licensed), and **deliverable immediately** upon purchase.
|
|
21
21
|
|
|
22
|
-
|
|
22
|
+
**AI products** are a core use case. If your product generates text, images, or voice, the review also checks that you have safeguards against harmful, deceptive, or adult output.
|
|
23
23
|
|
|
24
|
-
|
|
24
|
+
### What Kelviq doesn't cover
|
|
25
25
|
|
|
26
|
-
1. **
|
|
27
|
-
2. **
|
|
28
|
-
3. **
|
|
26
|
+
1. **Physical goods** or shipping.
|
|
27
|
+
2. **Services where the main product is your own time**, such as 1-on-1 coaching, consulting, or agency work.
|
|
28
|
+
3. **Marketplaces.** You sell products you created or are licensed to sell, not other sellers' products.
|
|
29
29
|
|
|
30
30
|
## 2. Global Compliance & High-Risk Categories (Prohibited)
|
|
31
31
|
|
|
@@ -62,11 +62,10 @@ This list is not exhaustive, and we reserve the right to review, suspend, or ter
|
|
|
62
62
|
|
|
63
63
|
## 3. Restricted Businesses (Requires Extensive Review)
|
|
64
64
|
|
|
65
|
-
|
|
65
|
+
We review each of these businesses individually. Some are approved with conditions, such as a reserve on funds. Email [hi@kelviq.com](mailto:hi@kelviq.com) early and we'll tell you what applies to your product.
|
|
66
66
|
|
|
67
|
-
* **AI-Powered Services:** Especially tools for AI-generated text, images, or voice. We need to review your product to ensure it has proper safeguards against generating harmful, deceptive, or adult content.
|
|
68
67
|
* **Marketing Services:** Some marketing tools may be allowed, but we must review them to ensure they do not facilitate spam or mass outreach.
|
|
69
|
-
* **Pre-Orders & Paid Waitlists:**
|
|
68
|
+
* **Pre-Orders & Paid Waitlists:** Pre-orders and paid waitlists need approval, which we give mainly to established creators. If approved, funds are paid out once the product ships.
|
|
70
69
|
|
|
71
70
|
## 4. Prohibited & Supported Countries
|
|
72
71
|
|
|
@@ -82,66 +81,71 @@ As a U.S. company, Kelviq is required to comply with U.S. sanctions laws (OFAC).
|
|
|
82
81
|
* The regions of Crimea, Donetsk, and Luhansk
|
|
83
82
|
|
|
84
83
|
### Supported Payout Countries
|
|
85
|
-
We support businesses registered in **
|
|
84
|
+
We support businesses registered in **120 countries**. You can receive payouts in your local bank account in currencies including USD, EUR, GBP, CAD, AUD, INR, and more.
|
|
86
85
|
|
|
87
86
|
| | | |
|
|
88
87
|
| :--- | :--- | :--- |
|
|
89
|
-
| 🇦🇱 Albania |
|
|
90
|
-
|
|
|
91
|
-
|
|
|
92
|
-
|
|
|
93
|
-
|
|
|
94
|
-
|
|
|
95
|
-
|
|
|
96
|
-
|
|
|
88
|
+
| 🇦🇱 Albania | 🇩🇿 Algeria | 🇦🇴 Angola |
|
|
89
|
+
| 🇦🇬 Antigua & Barbuda | 🇦🇷 Argentina | 🇦🇲 Armenia |
|
|
90
|
+
| 🇦🇺 Australia | 🇦🇹 Austria | 🇦🇿 Azerbaijan |
|
|
91
|
+
| 🇧🇸 Bahamas | 🇧🇭 Bahrain | 🇧🇩 Bangladesh |
|
|
92
|
+
| 🇧🇪 Belgium | 🇧🇯 Benin | 🇧🇹 Bhutan |
|
|
93
|
+
| 🇧🇴 Bolivia | 🇧🇦 Bosnia & Herzegovina | 🇧🇼 Botswana |
|
|
94
|
+
| 🇧🇳 Brunei | 🇧🇬 Bulgaria | 🇰🇭 Cambodia |
|
|
95
|
+
| 🇨🇦 Canada | 🇨🇱 Chile | 🇨🇴 Colombia |
|
|
96
|
+
| 🇨🇷 Costa Rica | 🇭🇷 Croatia | 🇨🇾 Cyprus |
|
|
97
|
+
| 🇨🇿 Czech Republic | 🇨🇮 Côte d'Ivoire | 🇩🇰 Denmark |
|
|
97
98
|
| 🇩🇴 Dominican Republic | 🇪🇨 Ecuador | 🇪🇬 Egypt |
|
|
98
99
|
| 🇸🇻 El Salvador | 🇪🇪 Estonia | 🇪🇹 Ethiopia |
|
|
99
|
-
| 🇫🇮 Finland | 🇫🇷 France |
|
|
100
|
-
| 🇩🇪 Germany | 🇬🇭 Ghana |
|
|
101
|
-
|
|
|
102
|
-
|
|
|
100
|
+
| 🇫🇮 Finland | 🇫🇷 France | 🇬🇦 Gabon |
|
|
101
|
+
| 🇬🇲 Gambia | 🇩🇪 Germany | 🇬🇭 Ghana |
|
|
102
|
+
| 🇬🇮 Gibraltar | 🇬🇷 Greece | 🇬🇹 Guatemala |
|
|
103
|
+
| 🇬🇾 Guyana | 🇭🇰 Hong Kong SAR China | 🇭🇺 Hungary |
|
|
104
|
+
| 🇮🇸 Iceland | 🇮🇳 India | 🇮🇩 Indonesia |
|
|
103
105
|
| 🇮🇪 Ireland | 🇮🇱 Israel | 🇮🇹 Italy |
|
|
104
106
|
| 🇯🇲 Jamaica | 🇯🇵 Japan | 🇯🇴 Jordan |
|
|
105
|
-
| 🇰🇪 Kenya | 🇰🇼 Kuwait |
|
|
107
|
+
| 🇰🇿 Kazakhstan | 🇰🇪 Kenya | 🇰🇼 Kuwait |
|
|
108
|
+
| 🇱🇦 Laos | 🇱🇻 Latvia | 🇱🇮 Liechtenstein |
|
|
106
109
|
| 🇱🇹 Lithuania | 🇱🇺 Luxembourg | 🇲🇴 Macao SAR China |
|
|
107
|
-
| 🇲🇬 Madagascar |
|
|
108
|
-
| 🇲🇽 Mexico | 🇲🇩 Moldova |
|
|
109
|
-
| 🇲🇳 Mongolia | 🇲🇦 Morocco |
|
|
110
|
-
|
|
|
110
|
+
| 🇲🇬 Madagascar | 🇲🇾 Malaysia | 🇲🇹 Malta |
|
|
111
|
+
| 🇲🇺 Mauritius | 🇲🇽 Mexico | 🇲🇩 Moldova |
|
|
112
|
+
| 🇲🇨 Monaco | 🇲🇳 Mongolia | 🇲🇦 Morocco |
|
|
113
|
+
| 🇲🇿 Mozambique | 🇳🇦 Namibia | 🇳🇱 Netherlands |
|
|
114
|
+
| 🇳🇿 New Zealand | 🇳🇪 Niger | 🇳🇬 Nigeria |
|
|
111
115
|
| 🇲🇰 North Macedonia | 🇳🇴 Norway | 🇴🇲 Oman |
|
|
112
116
|
| 🇵🇰 Pakistan | 🇵🇦 Panama | 🇵🇾 Paraguay |
|
|
113
117
|
| 🇵🇪 Peru | 🇵🇭 Philippines | 🇵🇱 Poland |
|
|
114
118
|
| 🇵🇹 Portugal | 🇶🇦 Qatar | 🇷🇴 Romania |
|
|
115
|
-
| 🇷🇼 Rwanda |
|
|
116
|
-
| 🇷🇸 Serbia | 🇸🇬 Singapore |
|
|
117
|
-
| 🇸🇮 Slovenia | 🇿🇦 South Africa |
|
|
118
|
-
| 🇪🇸 Spain | 🇱🇰 Sri Lanka |
|
|
119
|
-
| 🇸🇪 Sweden | 🇨🇭 Switzerland |
|
|
120
|
-
| 🇹🇿 Tanzania | 🇹🇭 Thailand |
|
|
121
|
-
|
|
|
122
|
-
| 🇬🇧 United Kingdom | 🇺🇸 United States |
|
|
123
|
-
| 🇺🇿 Uzbekistan | 🇻🇳 Vietnam |
|
|
124
|
-
|
|
125
|
-
*
|
|
119
|
+
| 🇷🇼 Rwanda | 🇸🇲 San Marino | 🇸🇦 Saudi Arabia |
|
|
120
|
+
| 🇸🇳 Senegal | 🇷🇸 Serbia | 🇸🇬 Singapore |
|
|
121
|
+
| 🇸🇰 Slovakia | 🇸🇮 Slovenia | 🇿🇦 South Africa |
|
|
122
|
+
| 🇰🇷 South Korea | 🇪🇸 Spain | 🇱🇰 Sri Lanka |
|
|
123
|
+
| 🇱🇨 St Lucia | 🇸🇪 Sweden | 🇨🇭 Switzerland |
|
|
124
|
+
| 🇹🇼 Taiwan | 🇹🇿 Tanzania | 🇹🇭 Thailand |
|
|
125
|
+
| 🇹🇹 Trinidad & Tobago | 🇹🇳 Tunisia | 🇹🇷 Türkiye |
|
|
126
|
+
| 🇦🇪 United Arab Emirates | 🇬🇧 United Kingdom | 🇺🇸 United States |
|
|
127
|
+
| 🇺🇾 Uruguay | 🇺🇿 Uzbekistan | 🇻🇳 Vietnam |
|
|
128
|
+
|
|
129
|
+
*You can get paid when your business is registered in one of these countries. The list follows our payout provider. Don't see your country? Email [hi@kelviq.com](mailto:hi@kelviq.com) before you sign up.*
|
|
126
130
|
|
|
127
131
|
## 5. The Review Process
|
|
128
132
|
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
There are two steps to complete before you can start accepting real payments:
|
|
133
|
+
You can integrate and test in sandbox right away. Taking live payments needs approval, in two steps:
|
|
132
134
|
|
|
133
135
|
### Step 1: Business Verification
|
|
134
136
|
|
|
135
|
-
Open **Settings → Business details** in the Kelviq dashboard.
|
|
137
|
+
Open **Settings → Business details** in the Kelviq dashboard.
|
|
138
|
+
|
|
139
|
+
Fill in your business details: logo, country, website, a support email that buyers will see, a short overview of what you sell, your estimated monthly revenue, and your social profiles. Kelviq places the country from your organization profile first in the country selector. Check it before you save.
|
|
136
140
|
|
|
137
|
-
<img src="/images/review-process/business-verification-
|
|
141
|
+
<img src="/images/review-process/business-verification-form.webp" alt="The Business verification form in Settings" />
|
|
138
142
|
|
|
139
|
-
|
|
143
|
+
Click **Save details**. The page then shows that your details are under review, and you can carry on creating products and testing in sandbox while you wait.
|
|
140
144
|
|
|
141
|
-
<img src="/images/review-process/business-
|
|
145
|
+
<img src="/images/review-process/business-verification-reviewing.webp" alt="Business verification page showing that the details are under review" />
|
|
142
146
|
|
|
143
147
|
**What happens next:**
|
|
144
|
-
- Most reviews are completed within **
|
|
148
|
+
- Most reviews are completed within **24 hours**.
|
|
145
149
|
- If we need more information, we'll reach out to you via email.
|
|
146
150
|
- Once your verification is approved, you'll receive a confirmation email.
|
|
147
151
|
|
|
@@ -166,25 +170,21 @@ Once both steps are completed (Business Verification and Payout Setup), you can
|
|
|
166
170
|
|
|
167
171
|
## 6. Testing Payments
|
|
168
172
|
|
|
169
|
-
|
|
173
|
+
You have two ways to test without paying yourself (a payment provider can flag your card if you do):
|
|
170
174
|
|
|
171
|
-
|
|
175
|
+
1. **Sandbox** - Switch to sandbox in your dashboard to test the whole checkout flow with test card numbers.
|
|
176
|
+
2. **A 100% discount code** - Create a discount code for 100% off to test checkout in live mode without being charged.
|
|
172
177
|
|
|
173
|
-
|
|
174
|
-
2. **Use 100% Discount Coupons** - Create a discount coupon with 100% off to test the checkout workflow in live mode without being charged.
|
|
175
|
-
|
|
176
|
-
## 7. Enforcement & Monitoring
|
|
178
|
+
## 7. Staying in good standing
|
|
177
179
|
|
|
178
180
|
Once you are live, we continuously monitor account activity to prevent fraud and ensure ongoing compliance.
|
|
179
181
|
|
|
180
|
-
* **Refund
|
|
181
|
-
* **
|
|
182
|
-
* **Prohibited
|
|
182
|
+
* **Refund rate:** We monitor refund rates on every live account. If your refund rate goes above 10%, we'll contact you to help with product or support issues.
|
|
183
|
+
* **Disputes:** A high dispute rate starts an account review.
|
|
184
|
+
* **Prohibited activity:** Selling prohibited products, money laundering, or fraud leads to suspension, and funds can be held to cover open disputes.
|
|
183
185
|
|
|
184
186
|
## 8. Have a Question About Your Product?
|
|
185
187
|
|
|
186
|
-
|
|
187
|
-
|
|
188
|
-
If you are unsure if your product is allowed, **please contact us at hi@kelviq.com *before* you launch.**
|
|
188
|
+
Our simple gut check: **Is this a high-quality, legitimate product that you are proud of, that you own the rights to, and that is delivered digitally?** If the answer to all three is yes, your product is a good fit.
|
|
189
189
|
|
|
190
|
-
|
|
190
|
+
If you're unsure, email [hi@kelviq.com](mailto:hi@kelviq.com) before you launch.
|
|
@@ -4,11 +4,11 @@ slug: "guides/agent-toolkit"
|
|
|
4
4
|
section: "guides"
|
|
5
5
|
description: "Install Kelviq into Claude Code with one plugin — or add the Kelviq skills to any of 70+ AI coding agents."
|
|
6
6
|
---
|
|
7
|
-
The [Kelviq Agent Toolkit](https://github.com/kelviq/agent-toolkit) packages everything an AI coding agent needs to work with Kelviq — the full [MCP server](/guides/mcp-server) plus
|
|
7
|
+
The [Kelviq Agent Toolkit](https://github.com/kelviq/agent-toolkit) packages everything an AI coding agent needs to work with Kelviq — the full [MCP server](/guides/mcp-server) plus six **Agent Skills** that teach the agent Kelviq's workflows — behind a single install.
|
|
8
8
|
|
|
9
|
-
Skills are the missing half of tool access. The MCP server gives your agent
|
|
9
|
+
Skills are the missing half of tool access. The MCP server gives your agent 58 typed tools, but tools alone don't tell it that a new plan sits in DRAFT until published, that checkout is the default way to charge a customer, or that a retried usage report can double-count. The skills carry exactly that working knowledge, and they load automatically whenever a task looks Kelviq-shaped.
|
|
10
10
|
|
|
11
|
-
|
|
11
|
+
The bundled MCP server is always the latest published `@kelviq/mcp-server`, so server updates need no toolkit update.
|
|
12
12
|
|
|
13
13
|
---
|
|
14
14
|
|
|
@@ -21,7 +21,7 @@ Two commands, in any Claude Code session:
|
|
|
21
21
|
/plugin install kelviq@kelviq
|
|
22
22
|
```
|
|
23
23
|
|
|
24
|
-
This installs the full bundle: the MCP server is configured for you (no `claude mcp add`, no `--` separator gotchas) and all
|
|
24
|
+
This installs the full bundle: the MCP server is configured for you (no `claude mcp add`, no `--` separator gotchas) and all six skills are available immediately.
|
|
25
25
|
|
|
26
26
|
The server reads your API keys from environment variables. It uses your **sandbox** environment unless `KELVIQ_ENV=production`, so start with sandbox keys. Set them in your shell profile before starting Claude Code:
|
|
27
27
|
|
|
@@ -32,7 +32,7 @@ export KELVIQ_CLIENT_API_KEY="<your-sandbox-client-key>" # only needed for pro
|
|
|
32
32
|
|
|
33
33
|
Get keys at [app.kelviq.com/settings/api-keys](https://app.kelviq.com/settings/api-keys).
|
|
34
34
|
|
|
35
|
-
**Verify**: run `/mcp` — you should see `kelviq ✓ Connected,
|
|
35
|
+
**Verify**: run `/mcp` — you should see `kelviq ✓ Connected, 58 tools`. Then ask something Kelviq-shaped ("set up a Pro plan for my product") and watch the relevant skill activate.
|
|
36
36
|
|
|
37
37
|
No keys yet? Install anyway. The docs tools (`docs_search`, `docs_read`) work without any credentials, so your agent can answer Kelviq questions from the documentation immediately. API tools return a clear `Configuration error` until a key is set.
|
|
38
38
|
|
|
@@ -40,7 +40,7 @@ No keys yet? Install anyway. The docs tools (`docs_search`, `docs_read`) work wi
|
|
|
40
40
|
|
|
41
41
|
## Install — any other agent
|
|
42
42
|
|
|
43
|
-
The
|
|
43
|
+
The six skills are also published through the open skills ecosystem, installable into 70+ agents (Cursor, Codex, GitHub Copilot, OpenCode, Zed, and more):
|
|
44
44
|
|
|
45
45
|
```bash
|
|
46
46
|
npx skills add kelviq/agent-toolkit
|
|
@@ -56,15 +56,16 @@ This path installs **skills only** — it doesn't configure an MCP server for yo
|
|
|
56
56
|
|
|
57
57
|
---
|
|
58
58
|
|
|
59
|
-
## The
|
|
59
|
+
## The six skills
|
|
60
60
|
|
|
61
61
|
| Skill | What it teaches |
|
|
62
62
|
|---|---|
|
|
63
63
|
| `kelviq` | The hub. Connecting any agent to Kelviq, the ground rules (docs-first, error handling, confirm-before-destructive), the concept model (identifiers vs UUIDs, feature types, plan lifecycle, environments), and routing to the right skill or prompt for the task. |
|
|
64
64
|
| `pricing-plans` | Designing and publishing the catalog: products, features, plans, entitlements, the DRAFT → publish lifecycle, and customer-migration decisions on publish. |
|
|
65
65
|
| `setup-payments` | Selling plans and managing subscribers: checkout sessions, subscriptions, trials, upgrades, cancellation, and authenticated customer portal links. |
|
|
66
|
-
| `usage-based-billing` | Enforcing what was sold: runtime entitlement checks served from the edge, safe usage reporting for
|
|
66
|
+
| `usage-based-billing` | Enforcing what was sold: runtime entitlement checks served from the edge, safe usage reporting for Meter features, and the license key lifecycle. |
|
|
67
67
|
| `pricing-as-code` | The [Kelviq CLI](/cli/overview) workflow: pull the live catalog into `kelviq.config.ts`, edit in git, preview the diff, apply, and promote sandbox to production. |
|
|
68
|
+
| `migrate-to-kelviq` | Moving an app from another platform. Lemon Squeezy is supported: dry-run the store import, read the report, run it with your approval, then add Kelviq checkout, webhook, license and portal code beside the old platform's. |
|
|
68
69
|
|
|
69
70
|
### `kelviq` — the hub
|
|
70
71
|
|
|
@@ -92,13 +93,17 @@ Runtime enforcement. Entitlement checks via the edge-served `entitlements_get` (
|
|
|
92
93
|
|
|
93
94
|
Wraps the [Kelviq CLI](/cli/overview) loop for agents: `kelviq pull` → edit `kelviq.config.ts` in a branch → `kelviq push --dry-run` → review → apply → `kelviq promote` from sandbox to production. The skill has a built-in safety rule: an agent may run dry-runs and show you diffs freely, but **applying a real change always requires your explicit approval** — it will never chain a dry-run into an unattended `--yes`.
|
|
94
95
|
|
|
96
|
+
### `migrate-to-kelviq`
|
|
97
|
+
|
|
98
|
+
Walks an agent through a move from another platform. It first lists every place your app talks to the old platform and shows you before changing anything. It then previews the [store import](/guides/migrate-from-lemon-squeezy) with a dry run, reads the emailed report with you, and starts the real import only on your say-so. After that it adds Kelviq checkout, webhook, license and customer portal code, and leaves the old platform's code in place for subscribers who still renew there. The source platform's key stays in your env file and never enters the conversation.
|
|
99
|
+
|
|
95
100
|
---
|
|
96
101
|
|
|
97
102
|
## Skills, prompts, and tools — how they fit
|
|
98
103
|
|
|
99
104
|
The toolkit layers three things, each doing what it's best at:
|
|
100
105
|
|
|
101
|
-
1. **Tools** (from the MCP server) do the work —
|
|
106
|
+
1. **Tools** (from the MCP server) do the work — 58 typed API calls, each carrying [safety annotations](https://modelcontextprotocol.io/docs/concepts/tools#tool-annotations) so clients can auto-approve reads and confirm destructive writes.
|
|
102
107
|
2. **Skills** (from this toolkit) supply the judgment — which tool, in what order, with which confirmations. They activate automatically based on what you ask.
|
|
103
108
|
3. **Prompts** (from the MCP server) are guided, step-by-step flows you invoke explicitly — `setup_product`, `launch_plan`, and `diagnose_customer`. The skills route to them rather than duplicating them.
|
|
104
109
|
|
|
@@ -4,13 +4,13 @@ slug: "guides/mcp-server"
|
|
|
4
4
|
section: "guides"
|
|
5
5
|
description: "Control Kelviq from Claude, Cursor, and any AI assistant that speaks the Model Context Protocol."
|
|
6
6
|
---
|
|
7
|
-
`@kelviq/mcp-server` is the official [Model Context Protocol](https://modelcontextprotocol.io) server for Kelviq. It plugs into any MCP-compatible client — Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, Antigravity — and exposes the full Kelviq API as **typed tools** that the LLM can call directly, plus the entire Kelviq documentation as **searchable resources**.
|
|
7
|
+
`@kelviq/mcp-server` is the official [Model Context Protocol](https://modelcontextprotocol.io) server for Kelviq. It plugs into any MCP-compatible client — Claude Code, Claude Desktop, Cursor, Devin Desktop (formerly Windsurf), VS Code, Antigravity — and exposes the full Kelviq API as **typed tools** that the LLM can call directly, plus the entire Kelviq documentation as **searchable resources**.
|
|
8
8
|
|
|
9
9
|
Instead of asking your assistant to "write me a curl command," you describe the outcome ("create a Pro plan under product X and publish it") and it does the work in a single turn.
|
|
10
10
|
|
|
11
|
-
**Using Claude Code?** The fastest install is the [Agent Toolkit](/guides/agent-toolkit) plugin — two commands set up this MCP server *and*
|
|
11
|
+
**Using Claude Code?** The fastest install is the [Agent Toolkit](/guides/agent-toolkit) plugin — two commands set up this MCP server *and* six Kelviq skills that teach Claude the workflows. This page covers manual setup for every MCP client.
|
|
12
12
|
|
|
13
|
-
**
|
|
13
|
+
**58 tools** spanning connection checks, customers, checkout, subscriptions, discounts, webhooks, store imports, entitlements, licenses, usage, offerings, promotions, the customer portal, and full catalog management (products, plans, features) — plus a resource for every docs page and the full OpenAPI spec, and **3 guided prompts** for the most common workflows. Every tool carries [MCP safety annotations](https://modelcontextprotocol.io/docs/concepts/tools#tool-annotations), so clients can auto-approve read-only calls while confirming destructive ones.
|
|
14
14
|
|
|
15
15
|
---
|
|
16
16
|
|
|
@@ -20,7 +20,7 @@ The server runs locally on your machine as a Node process started by your AI cli
|
|
|
20
20
|
|
|
21
21
|
When the LLM decides to call a Kelviq tool, the server:
|
|
22
22
|
|
|
23
|
-
1. Validates the LLM-provided arguments against
|
|
23
|
+
1. Validates the LLM-provided arguments against the tool's Zod schema.
|
|
24
24
|
2. Adds your API key as a Bearer token and sends the HTTPS request to the appropriate Kelviq host.
|
|
25
25
|
3. Returns the JSON response (or a structured `{"error": {...}}` object) back to the LLM.
|
|
26
26
|
|
|
@@ -31,7 +31,7 @@ API errors are returned as content, not exceptions — the LLM reads them and re
|
|
|
31
31
|
## Step 1: Get Your API Keys
|
|
32
32
|
|
|
33
33
|
1. Sign in at [app.kelviq.com](https://app.kelviq.com).
|
|
34
|
-
2. Navigate to **Settings → API
|
|
34
|
+
2. Navigate to **Settings → API keys**.
|
|
35
35
|
3. Copy:
|
|
36
36
|
- **Server API Key** — required for all API tools.
|
|
37
37
|
- **Client API Key** — required only for the `promotion_get` tool.
|
|
@@ -56,7 +56,7 @@ claude mcp add kelviq \
|
|
|
56
56
|
|
|
57
57
|
The `--` separator is required so that `claude` doesn't intercept `-y` as one of its own flags. Put all `--env` arguments **before** the `--`.
|
|
58
58
|
|
|
59
|
-
Verify the connection with `/mcp` inside a Claude Code session — you should see `kelviq ✓ Connected,
|
|
59
|
+
Verify the connection with `/mcp` inside a Claude Code session — you should see `kelviq ✓ Connected, 58 tools`.
|
|
60
60
|
|
|
61
61
|
Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or the equivalent for your OS:
|
|
62
62
|
|
|
@@ -144,7 +144,7 @@ Add a `.vscode/mcp.json` in your workspace, or run **"MCP: Open User Configurati
|
|
|
144
144
|
|
|
145
145
|
Save, then click the **Start** CodeLens above the `kelviq` entry (or reload the window) and confirm it under the tools icon in Copilot Chat's Agent mode.
|
|
146
146
|
|
|
147
|
-
Already have Kelviq configured in Cursor or Windsurf? Under **Settings → Chat → MCP → Discovery**, check the matching box (e.g. "Windsurf configurations") to auto-import that server instead of retyping it. You can also use the `inputs` array to be prompted for the keys instead of storing them in plaintext.
|
|
147
|
+
Already have Kelviq configured in Cursor or Devin Desktop (formerly Windsurf)? Under **Settings → Chat → MCP → Discovery**, check the matching box (e.g. "Windsurf configurations") to auto-import that server instead of retyping it. You can also use the `inputs` array to be prompted for the keys instead of storing them in plaintext.
|
|
148
148
|
|
|
149
149
|
Open the "..." menu in the Agent panel → **MCP Servers** → **Manage MCP Servers** → **View raw config**. This opens `mcp_config.json` at:
|
|
150
150
|
|
|
@@ -199,6 +199,7 @@ Your AI client should pick the right tool, call it, and show the result inline.
|
|
|
199
199
|
|----------|----------|---------|---------|
|
|
200
200
|
| `KELVIQ_SERVER_API_KEY` | Yes, for all API tools | — | Server API key (Bearer token for the core API) |
|
|
201
201
|
| `KELVIQ_CLIENT_API_KEY` | Only for `promotion_get` | — | Client API key (Bearer token for the edge host) |
|
|
202
|
+
| `LEMONSQUEEZY_API_KEY` | Only for `import_start` with the `lemon-squeezy` source | — | Your Lemon Squeezy API key. Set it where `KELVIQ_SERVER_API_KEY` is set, then restart the client. The server reads it from here so it never passes through the conversation. |
|
|
202
203
|
| `KELVIQ_ENV` | No | `sandbox` | `sandbox` or `production`. Set to `production` to work with live data — switches both API hosts automatically. Use a key from the same environment: keys only work against their own environment. |
|
|
203
204
|
| `KELVIQ_BASE_URL` | No | per `KELVIQ_ENV` | Advanced: override the core API host |
|
|
204
205
|
| `KELVIQ_EDGE_URL` | No | per `KELVIQ_ENV` | Advanced: override the edge host (entitlements + promotions) |
|
|
@@ -282,6 +283,16 @@ Wherever a tool takes a product or feature reference (`plan_create`, `plan_entit
|
|
|
282
283
|
|
|
283
284
|
Signing secrets are hidden in webhook tool results. Pass `revealSecret: true` only when you need the value — your app reads the secret from its env file, so it rarely needs to appear in a conversation.
|
|
284
285
|
|
|
286
|
+
### Imports
|
|
287
|
+
|
|
288
|
+
| Tool | Description |
|
|
289
|
+
|------|-------------|
|
|
290
|
+
| `import_start` | Start an import of an existing store into your organization. `source` picks the platform (`lemon-squeezy`), and `dryRun` is required: `true` saves nothing and emails a report of what a real run would do. `storeId` is required for Lemon Squeezy. The import runs in the background and the report arrives by email, so the tool returns `queued`, not a finished import. The result names the environment the import was queued in and carries a note that there is nothing to poll. |
|
|
291
|
+
|
|
292
|
+
`import_start` is annotated as destructive, because a real run publishes the imported plans, so clients ask you to confirm it.
|
|
293
|
+
|
|
294
|
+
The source platform's key comes from the server's environment, not from a tool argument. Set `LEMONSQUEEZY_API_KEY` where `KELVIQ_SERVER_API_KEY` is set, then restart the client. The Kelviq key must be a Server API Key created by the organization owner. See [Migrate from Lemon Squeezy](/guides/migrate-from-lemon-squeezy).
|
|
295
|
+
|
|
285
296
|
### Catalog: Products
|
|
286
297
|
|
|
287
298
|
| Tool | Description |
|
|
@@ -352,7 +363,7 @@ For exhaustive per-endpoint request/response shapes, the **OpenAPI spec is the s
|
|
|
352
363
|
|
|
353
364
|
## Built-in Prompts
|
|
354
365
|
|
|
355
|
-
The server ships three MCP prompts that encode Kelviq's golden-path workflows — including the gotchas (plans start as invisible drafts until published;
|
|
366
|
+
The server ships three MCP prompts that encode Kelviq's golden-path workflows — including the gotchas (plans start as invisible drafts until published; features attach by identifier or UUID; pricing is set in the dashboard or with the [Kelviq CLI](/cli/overview), not through the MCP server). In Claude Code they appear as slash commands (e.g. `/kelviq:setup_product`); other MCP clients list them under prompts.
|
|
356
367
|
|
|
357
368
|
| Prompt | Arguments | What it guides |
|
|
358
369
|
|--------|-----------|----------------|
|
|
@@ -380,6 +391,10 @@ Calls: `license_activate` → `license_validate`.
|
|
|
380
391
|
|
|
381
392
|
Calls: `subscription_list` → `entitlements_get`.
|
|
382
393
|
|
|
394
|
+
> *Do a dry run of importing my Lemon Squeezy store 12345 into Kelviq.*
|
|
395
|
+
|
|
396
|
+
Calls: `import_start` with `dryRun: true`. Read the emailed report, then ask for the real import. A real run publishes the imported plans and switches on the discount codes.
|
|
397
|
+
|
|
383
398
|
> *How do digital downloads work in Kelviq? What's the file-size limit?*
|
|
384
399
|
|
|
385
400
|
Calls: `docs_search` → `docs_read`. No API key needed — works offline.
|
|
@@ -473,4 +488,4 @@ The repo is the canonical reference for tool schemas, build process, and contrib
|
|
|
473
488
|
## Need Help?
|
|
474
489
|
|
|
475
490
|
- Email us at **hi@kelviq.com**
|
|
476
|
-
- [Book a demo](https://
|
|
491
|
+
- [Book a demo](https://cal.com/alok-vats-fkpnc9/30min)
|