@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.
Files changed (111) hide show
  1. package/README.md +40 -3
  2. package/dist/config.d.ts +5 -0
  3. package/dist/config.js +1 -0
  4. package/dist/config.js.map +1 -1
  5. package/dist/docs/ai/docs-for-agents.md +21 -0
  6. package/dist/docs/ai/overview.md +43 -0
  7. package/dist/docs/api-reference/authentication.md +9 -3
  8. package/dist/docs/api-reference/introduction.md +23 -2
  9. package/dist/docs/backend-integration/node-sdk.md +12 -6
  10. package/dist/docs/backend-integration/python-sdk.md +14 -8
  11. package/dist/docs/changelog.md +369 -3
  12. package/dist/docs/checkout/checkout-configuration.md +25 -75
  13. package/dist/docs/checkout/checkout-design.md +76 -0
  14. package/dist/docs/checkout/checkout-examples.md +212 -0
  15. package/dist/docs/checkout/checkout-metadata.md +1 -1
  16. package/dist/docs/checkout/custom-fields.md +60 -0
  17. package/dist/docs/checkout/embed-checkout.md +280 -0
  18. package/dist/docs/checkout/payment-methods/upi.md +69 -0
  19. package/dist/docs/checkout/payment-methods.md +119 -0
  20. package/dist/docs/checkout/static-checkout-url.md +3 -2
  21. package/dist/docs/cli/commands.md +57 -4
  22. package/dist/docs/cli/kelviq-config.md +1 -1
  23. package/dist/docs/cli/overview.md +1 -0
  24. package/dist/docs/customer-portal/managing-payment-methods.md +4 -4
  25. package/dist/docs/customer-portal/overview.md +7 -7
  26. package/dist/docs/customer-portal/retention.md +109 -0
  27. package/dist/docs/customers-management/overview.md +105 -0
  28. package/dist/docs/frontend-integration/js-sdk.md +11 -11
  29. package/dist/docs/frontend-integration/promotions-ui-js.md +2 -2
  30. package/dist/docs/frontend-integration/react-sdk.md +8 -49
  31. package/dist/docs/frontend-integration/react-ui.md +8 -6
  32. package/dist/docs/getstarted/fees.md +27 -11
  33. package/dist/docs/getstarted/introduction-to-kelviq.md +29 -66
  34. package/dist/docs/getstarted/merchant-of-record.md +18 -24
  35. package/dist/docs/getstarted/overview.md +98 -0
  36. package/dist/docs/getstarted/review-process.md +59 -59
  37. package/dist/docs/guides/agent-toolkit.md +14 -9
  38. package/dist/docs/guides/mcp-server.md +24 -9
  39. package/dist/docs/guides/migrate-from-lemon-squeezy.md +405 -0
  40. package/dist/docs/guides/sandbox.md +6 -4
  41. package/dist/docs/guides/set-up-with-ai.md +43 -0
  42. package/dist/docs/guides/subscription-integration-for-nextjs.md +10 -11
  43. package/dist/docs/guides/subscription-integration.md +1 -1
  44. package/dist/docs/guides/test-payments.md +640 -0
  45. package/dist/docs/guides/webhooks.md +182 -30
  46. package/dist/docs/integrations/woocommerce.md +88 -0
  47. package/dist/docs/integrations/zapier.md +22 -0
  48. package/dist/docs/legal/account-and-funds.md +59 -0
  49. package/dist/docs/legal/approved-prohibited-policy.md +32 -27
  50. package/dist/docs/legal/payment-flow-diagram.md +7 -7
  51. package/dist/docs/manifest.json +160 -41
  52. package/dist/docs/openapi.json +1359 -109
  53. package/dist/docs/payouts/overview.md +14 -12
  54. package/dist/docs/payouts/payout-account.md +1 -1
  55. package/dist/docs/payouts/transactions.md +3 -3
  56. package/dist/docs/product-catalog/create-a-feature.md +3 -3
  57. package/dist/docs/product-catalog/digital-downloads.md +5 -5
  58. package/dist/docs/product-catalog/discounts.md +2 -2
  59. package/dist/docs/product-catalog/entitlements.md +20 -27
  60. package/dist/docs/product-catalog/free-and-trials.md +5 -5
  61. package/dist/docs/product-catalog/license-keys.md +56 -29
  62. package/dist/docs/product-catalog/links.md +3 -3
  63. package/dist/docs/product-catalog/location-based-pricing.md +6 -10
  64. package/dist/docs/product-catalog/one-time-payments.md +3 -7
  65. package/dist/docs/product-catalog/pay-as-you-go.md +8 -8
  66. package/dist/docs/product-catalog/plans.md +22 -19
  67. package/dist/docs/product-catalog/products.md +11 -3
  68. package/dist/docs/product-catalog/proration.md +69 -0
  69. package/dist/docs/product-catalog/seat-based-pricing.md +7 -7
  70. package/dist/docs/product-catalog/subscriptions.md +52 -22
  71. package/dist/docs/product-catalog/tax-settings.md +8 -8
  72. package/dist/docs/product-catalog/usage-alerts.md +7 -7
  73. package/dist/docs/product-catalog/usage-based-billing.md +156 -29
  74. package/dist/docs/product-catalog/usage-limits.md +78 -0
  75. package/dist/docs/promotions/create-a-promotion.md +2 -2
  76. package/dist/docs/promotions/overview.md +1 -1
  77. package/dist/docs/quickstart/core-concepts.md +36 -30
  78. package/dist/docs/quickstart/dashboard-setup.md +26 -22
  79. package/dist/docs/quickstart/integrate-with-your-app.md +133 -52
  80. package/dist/docs/sales/abandoned-cart-recovery.md +7 -3
  81. package/dist/docs/sales/checkout-sessions.md +28 -39
  82. package/dist/docs/sales/orders.md +30 -54
  83. package/dist/docs/settings/customer-emails.md +52 -0
  84. package/dist/docs/settings/members.md +27 -0
  85. package/dist/docs/settings/profile.md +26 -0
  86. package/dist/docs/settings/zapier.md +22 -0
  87. package/dist/http/errors.d.ts +20 -1
  88. package/dist/http/errors.js +83 -31
  89. package/dist/http/errors.js.map +1 -1
  90. package/dist/schemas/kelviq.d.ts +54 -0
  91. package/dist/schemas/kelviq.js +64 -0
  92. package/dist/schemas/kelviq.js.map +1 -1
  93. package/dist/server.js +3 -2
  94. package/dist/server.js.map +1 -1
  95. package/dist/tools/_resolve.js +14 -10
  96. package/dist/tools/_resolve.js.map +1 -1
  97. package/dist/tools/features.js +9 -2
  98. package/dist/tools/features.js.map +1 -1
  99. package/dist/tools/imports.d.ts +68 -0
  100. package/dist/tools/imports.js +242 -0
  101. package/dist/tools/imports.js.map +1 -0
  102. package/dist/tools/index.d.ts +2 -1
  103. package/dist/tools/index.js +4 -1
  104. package/dist/tools/index.js.map +1 -1
  105. package/dist/tools/product-files.js +10 -3
  106. package/dist/tools/product-files.js.map +1 -1
  107. package/dist/tools/product-settings.js +10 -3
  108. package/dist/tools/product-settings.js.map +1 -1
  109. package/dist/tools/products.js +14 -4
  110. package/dist/tools/products.js.map +1 -1
  111. 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
- Because Kelviq operates as your **Merchant of Record (MOR)**, we are legally and financially responsible for every transaction processed through our platform. To ensure the safety of the ecosystem and comply with global financial regulations, we must strictly review the businesses we support.
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
- ### ⛔ The Three Fundamental Limitations
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
- Before proceeding, please note the three "Hard No" rules of our MOR service:
24
+ ### What Kelviq doesn't cover
25
25
 
26
- 1. **Digital Only:** We cannot support physical goods, shipping, or logistics.
27
- 2. **No Manual Services:** We cannot support 1-on-1 coaching, consulting, or agencies where the primary value is your manual labor.
28
- 3. **No Marketplaces:** You must be the original creator or licensed distributor. You cannot use Kelviq to process payments for other unverified sellers.
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
- The following businesses are not automatically prohibited, but they are considered high-risk and require extensive review by our compliance team. Approval is not guaranteed and may be subject to additional conditions (like holding funds in reserve).
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:** We generally **do not** allow pre-orders. This is a very high-risk category for an MOR. In rare cases, we may make an exception for established creators, but funds will be withheld until the product is verifiably shipped.
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 **90+ countries**. You can receive payouts in your local bank account in currencies including USD, EUR, GBP, CAD, AUD, INR, and more.
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 | 🇦🇬 Antigua & Barbuda | 🇦🇷 Argentina |
90
- | 🇦🇲 Armenia | 🇦🇺 Australia | 🇦🇹 Austria |
91
- | 🇧🇸 Bahamas | 🇧🇭 Bahrain | 🇧🇪 Belgium |
92
- | 🇧🇯 Benin | 🇧🇴 Bolivia | 🇧🇦 Bosnia & Herzegovina |
93
- | 🇧🇼 Botswana | 🇧🇳 Brunei | 🇧🇬 Bulgaria |
94
- | 🇰🇭 Cambodia | 🇨🇦 Canada | 🇨🇱 Chile |
95
- | 🇨🇴 Colombia | 🇨🇷 Costa Rica | 🇨🇮 Côte d'Ivoire |
96
- | 🇨🇾 Cyprus | 🇨🇿 Czech Republic | 🇩🇰 Denmark |
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 | 🇬🇲 Gambia |
100
- | 🇩🇪 Germany | 🇬🇭 Ghana | 🇬🇷 Greece |
101
- | 🇬🇹 Guatemala | 🇬🇾 Guyana | 🇭🇰 Hong Kong |
102
- | 🇭🇺 Hungary | 🇮🇳 India | 🇮🇸 Iceland |
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 | 🇱🇻 Latvia |
107
+ | 🇰🇿 Kazakhstan | 🇰🇪 Kenya | 🇰🇼 Kuwait |
108
+ | 🇱🇦 Laos | 🇱🇻 Latvia | 🇱🇮 Liechtenstein |
106
109
  | 🇱🇹 Lithuania | 🇱🇺 Luxembourg | 🇲🇴 Macao SAR China |
107
- | 🇲🇬 Madagascar | 🇲🇹 Malta | 🇲🇺 Mauritius |
108
- | 🇲🇽 Mexico | 🇲🇩 Moldova | 🇲🇨 Monaco |
109
- | 🇲🇳 Mongolia | 🇲🇦 Morocco | 🇳🇦 Namibia |
110
- | 🇳🇱 Netherlands | 🇳🇿 New Zealand | 🇳🇬 Nigeria |
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 | 🇸🇦 Saudi Arabia | 🇸🇳 Senegal |
116
- | 🇷🇸 Serbia | 🇸🇬 Singapore | 🇸🇰 Slovakia |
117
- | 🇸🇮 Slovenia | 🇿🇦 South Africa | 🇰🇷 South Korea |
118
- | 🇪🇸 Spain | 🇱🇰 Sri Lanka | 🇱🇨 St. Lucia |
119
- | 🇸🇪 Sweden | 🇨🇭 Switzerland | 🇹🇼 Taiwan |
120
- | 🇹🇿 Tanzania | 🇹🇭 Thailand | 🇹🇹 Trinidad & Tobago |
121
- | 🇹🇳 Tunisia | 🇹🇷 Turkey | 🇦🇪 United Arab Emirates |
122
- | 🇬🇧 United Kingdom | 🇺🇸 United States | 🇺🇾 Uruguay |
123
- | 🇺🇿 Uzbekistan | 🇻🇳 Vietnam | |
124
-
125
- *This list is determined by our payment provider and is subject to change. If your country is not listed here, you will not be able to complete onboarding or receive payouts.*
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
- Before you can process real payments, your account must pass our verification process. You can integrate and test in "Sandbox Mode" immediately, but "Live Mode" requires approval.
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. You can also continue from the business-verification prompt shown during onboarding.
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-prompt.png" alt="Business verification prompt shown during onboarding" />
141
+ <img src="/images/review-process/business-verification-form.webp" alt="The Business verification form in Settings" />
138
142
 
139
- Fill in your business details and click **Submit for review** when you're done. Kelviq places the country from your organization profile first in the country selector to make it easier to find. Review the country before submitting the form.
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-details-form.png" alt="Business details form" />
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 **12-24 hours**.
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
- Do not use your own real card to test payment flows.
173
+ You have two ways to test without paying yourself (a payment provider can flag your card if you do):
170
174
 
171
- For testing, you have two options:
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
- 1. **Use Sandbox Mode** - Switch to sandbox mode in your dashboard to test the entire checkout flow with test card numbers.
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 Rate Monitoring:** If your refund rate exceeds acceptable thresholds (typically >10%), we may reach out to help you improve your product quality or support.
181
- * **Chargeback Monitoring:** We maintain a strict low-tolerance policy for chargebacks. Excessive dispute levels may result in account review.
182
- * **Prohibited Activity:** If an account is found to be selling prohibited items or engaging in money laundering/fraud after approval, the account will be suspended immediately and funds may be held to cover potential disputes.
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
- We know this list is long, and the line can be blurry, especially with new AI tools. We want to support innovative products.
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
- Our simple "gut check" is: **Is this a high-quality, legitimate product that you are proud of, that you own the rights to, and that is delivered digitally?** If you can answer "yes" to all three, you are probably in the clear.
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 five **Agent Skills** that teach the agent Kelviq's workflows — behind a single install.
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 57 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.
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
- **The Agent Toolkit is new.** The skills and their names are stable, but content will keep improving alongside the platform. The bundled MCP server is always the latest published `@kelviq/mcp-server` — no toolkit update needed when the server improves.
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 five skills are available immediately.
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, 57 tools`. Then ask something Kelviq-shaped ("set up a Pro plan for my product") and watch the relevant skill activate.
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 five skills are also published through the open skills ecosystem, installable into 70+ agents (Cursor, Codex, GitHub Copilot, OpenCode, Zed, and more):
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 five skills
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 metered features, and the license key lifecycle. |
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 — 57 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.
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* five Kelviq skills that teach Claude the workflows. This page covers manual setup for every MCP client.
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
- **57 tools** spanning connection checks, customers, checkout, subscriptions, discounts, webhooks, 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.
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 a Zod schema derived from Kelviq's OpenAPI spec.
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 Keys**.
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, 57 tools`.
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; entitlements attach by feature 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.
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://tidycal.com/neravath/15-minute-meeting)
491
+ - [Book a demo](https://cal.com/alok-vats-fkpnc9/30min)