@getcheddar/cheddar-mcp 1.0.4 → 1.0.5

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 (2) hide show
  1. package/README.md +289 -110
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,180 +1,357 @@
1
1
  # Cheddar MCP Server
2
2
 
3
- A Model Context Protocol (MCP) server for integrating with the Cheddar Payment Platform. This server provides AI assistants with tools to manage customers, payment methods, subscriptions, and generate checkout integration code.
3
+ A Model Context Protocol (MCP) server for integrating with the Cheddar Payment Platform. This server provides AI assistants with tools to generate payment integration code and manage Cheddar resources.
4
4
 
5
- ## Features
5
+ **Package:** `@getcheddar/cheddar-mcp`
6
+ **Version:** 1.0.5
6
7
 
7
- - **Customer Management**: Create, read, and update customers
8
- - **Payment Methods**: Tokenize cards and manage payment methods (PCI-compliant)
9
- - **Subscriptions**: View subscription details and manage promotions
10
- - **Checkout Integration**: Generate hosted checkout URLs and embedded form code
11
- - **Code Generation**: Produce framework-specific integration code (React, Vue, Next.js, Vanilla JS)
12
- - **Webhook Handling**: Validate and configure webhook endpoints
8
+ ---
13
9
 
14
- ## Installation
10
+ ## Two Modes of Operation
15
11
 
16
- ### Option 1: Run with npx (recommended)
12
+ The MCP server works in two modes depending on whether you provide API credentials:
17
13
 
18
- ```bash
19
- npx -y @getcheddar/cheddar-mcp
14
+ ### Mode A: Code Generation Only (No Auth Required)
15
+
16
+ **Use this mode to:**
17
+
18
+ - Generate integration code (React, Vue, Next.js, etc.)
19
+ - Create checkout forms and hosted page URLs
20
+ - Configure webhooks and validation logic
21
+ - Get code recommendations and best practices
22
+
23
+ **No API credentials needed!** These tools work out of the box:
24
+
25
+ | Tool | Description |
26
+ | -------------------------------------------- | ------------------------------------------------ |
27
+ | `cheddar_checkout_generate_hosted_url` | Generate hosted checkout page URLs |
28
+ | `cheddar_checkout_generate_embedded_form` | Generate embedded checkout form code |
29
+ | `cheddar_checkout_generate_integration_code` | Generate complete framework-specific integration |
30
+ | `cheddar_checkout_configure_webhook` | Generate webhook handler code |
31
+ | `cheddar_checkout_validate_webhook` | Validate webhook signatures |
32
+
33
+ **Quick Start (No Auth):**
34
+
35
+ ```json
36
+ {
37
+ "mcpServers": {
38
+ "cheddar": {
39
+ "command": "npx",
40
+ "args": ["-y", "@getcheddar/cheddar-mcp@1.0.5"]
41
+ }
42
+ }
43
+ }
20
44
  ```
21
45
 
22
- ### Option 2: Install globally
46
+ **Example Prompt for Lovable:**
23
47
 
24
- ```bash
25
- npm install -g @getcheddar/cheddar-mcp
26
- cheddar-mcp
27
48
  ```
49
+ Create a React checkout page for my SaaS using Cheddar payments.
50
+ - Collect customer email and name
51
+ - Accept credit card payments securely
52
+ - Subscribe customers to a "Pro Plan"
53
+ - Handle errors gracefully
28
54
 
29
- ### Option 3: Docker
55
+ Use cheddar_checkout_generate_integration_code with framework "react".
56
+ ```
30
57
 
31
- Build the image from this package (there is no guaranteed public image on a registry yet):
58
+ ---
32
59
 
33
- ```bash
34
- # From the repository root, or set context to this directory
35
- docker build -t cheddar-mcp ./packages/cheddar-mcp
60
+ ### Mode B: Full API Access (Auth Required)
36
61
 
37
- docker run -i --rm \
38
- -e CHEDDAR_API_URL=https://api.getcheddar.com \
39
- -e CHEDDAR_ACCESS_TOKEN=your_token \
40
- cheddar-mcp
62
+ **Use this mode to:**
63
+
64
+ - Query actual customer data from your Cheddar account
65
+ - Create and update customers, subscriptions, payment methods
66
+ - Manage billing and plan changes
67
+ - Access real-time subscription status
68
+
69
+ **Requires Cheddar API credentials.** These tools need authentication:
70
+
71
+ | Tool | Description |
72
+ | ------------------------------ | ---------------------------------- |
73
+ | `cheddar_customer_get` | Retrieve customer by ID or code |
74
+ | `cheddar_customer_create` | Create a new customer |
75
+ | `cheddar_customer_update` | Update customer information |
76
+ | `cheddar_payment_method_get` | Retrieve payment method by ID |
77
+ | `cheddar_payment_token_create` | Tokenize card data (PCI-compliant) |
78
+ | `cheddar_subscription_get` | Retrieve subscription details |
79
+ | `cheddar_plan_get` | Retrieve plan information |
80
+
81
+ **Setup with Auth:**
82
+
83
+ 1. **Sign up for Cheddar:** https://getcheddar.com/signup
84
+ 2. **Get your credentials:**
85
+ - **Username:** Your Cheddar account email
86
+ - **Secret Key:** Top navbar → Configuration → Product Settings → Secret Key
87
+
88
+ 3. **Configure MCP:**
89
+
90
+ ```json
91
+ {
92
+ "mcpServers": {
93
+ "cheddar": {
94
+ "command": "npx",
95
+ "args": ["-y", "@getcheddar/cheddar-mcp@1.0.5"],
96
+ "env": {
97
+ "CHEDDAR_API_URL": "https://api.getcheddar.com",
98
+ "CHEDDAR_USERNAME": "your-email@example.com",
99
+ "CHEDDAR_SECRET_KEY": "your-secret-key-here"
100
+ }
101
+ }
102
+ }
103
+ }
41
104
  ```
42
105
 
43
- ## Configuration
106
+ **Alternative: OAuth2 Access Token**
44
107
 
45
- Set the following environment variables:
108
+ If you have an OAuth2 access token instead:
46
109
 
47
- | Variable | Required for API calls | Description |
48
- | ------------------------- | ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
49
- | `CHEDDAR_API_URL` | No | REST API base URL. **Production:** `https://api.getcheddar.com`. If unset, the server defaults to `https://api.chdr.dev`. For local Cheddar docker development, use the API host from your stack (often `http://api.chdrdev.com` or `http://api.chdrdev.com:8888` with hosts file entries). |
50
- | `CHEDDAR_ACCESS_TOKEN` | **Yes** | OAuth2 access token, sent as `Authorization: Bearer …` on every request. |
51
- | `CHEDDAR_CLIENT_ID` | No† | OAuth2 client ID (reserved for future automatic token acquisition in this package). |
52
- | `CHEDDAR_CLIENT_SECRET` | No† | OAuth2 client secret (same as above). |
110
+ ```json
111
+ {
112
+ "mcpServers": {
113
+ "cheddar": {
114
+ "command": "npx",
115
+ "args": ["-y", "@getcheddar/cheddar-mcp@1.0.5"],
116
+ "env": {
117
+ "CHEDDAR_API_URL": "https://api.getcheddar.com",
118
+ "CHEDDAR_ACCESS_TOKEN": "your-oauth2-access-token"
119
+ }
120
+ }
121
+ }
122
+ }
123
+ ```
53
124
 
54
- †The process may start if both `CHEDDAR_CLIENT_ID` and `CHEDDAR_CLIENT_SECRET` are set without a token, but **API calls will fail** until `CHEDDAR_ACCESS_TOKEN` is set. Client-credentials exchange is not implemented in the client yet—use a bearer token.
125
+ **Example Prompt with Auth:**
55
126
 
56
- ### Getting credentials and an access token
127
+ ```
128
+ Get customer details for customer code "cust_12345" and show me their subscription status and payment methods.
57
129
 
58
- 1. Sign in to your Cheddar merchant admin (production login: [https://login.getcheddar.com](https://login.getcheddar.com)).
59
- 2. In the dashboard, open the section where **API / OAuth2** clients (or API keys) are managed, and create or copy a client that supports the **client credentials** grant.
60
- 3. Request an access token from the OAuth token endpoint:
130
+ Use cheddar_customer_get, then cheddar_subscription_get and cheddar_payment_method_get.
131
+ ```
132
+
133
+ ---
134
+
135
+ ## Configuration Reference
61
136
 
62
- - **Production:** `POST` [https://login.getcheddar.com/oauth/token](https://login.getcheddar.com/oauth/token)
63
- - **Headers:** `Content-Type: application/json`
64
- - **Body (example):**
137
+ | Variable | Mode | Description |
138
+ | ---------------------- | --------- | -------------------------------------------------------- |
139
+ | `CHEDDAR_API_URL` | Auth only | REST API base URL. Default: `https://api.getcheddar.com` |
140
+ | `CHEDDAR_USERNAME` | Auth only | Your Cheddar account email address |
141
+ | `CHEDDAR_SECRET_KEY` | Auth only | Secret Key from Product Settings |
142
+ | `CHEDDAR_ACCESS_TOKEN` | Auth only | OAuth2 Bearer token (alternative to username/secret) |
65
143
 
66
- ```json
67
- {
68
- "grant_type": "client_credentials",
69
- "client_id": "your-client-id",
70
- "client_secret": "your-client-secret"
71
- }
72
- ```
144
+ **Note:** If no auth credentials are provided, the server runs in **code generation mode only** and will return clear error messages if you try to use data access tools.
73
145
 
74
- 4. Set `CHEDDAR_ACCESS_TOKEN` to the `access_token` value from the response.
75
- 5. Set `CHEDDAR_API_URL` to the API base for that environment (production: `https://api.getcheddar.com`).
146
+ ---
76
147
 
77
148
  ## Usage with Claude Desktop
78
149
 
79
- Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS or `%APPDATA%/Claude/claude_desktop_config.json` on Windows):
150
+ Add to your Claude Desktop configuration:
151
+
152
+ **For code generation (no auth):**
80
153
 
81
154
  ```json
82
155
  {
83
156
  "mcpServers": {
84
157
  "cheddar": {
85
158
  "command": "npx",
86
- "args": ["-y", "@getcheddar/cheddar-mcp"],
159
+ "args": ["-y", "@getcheddar/cheddar-mcp@1.0.5"]
160
+ }
161
+ }
162
+ }
163
+ ```
164
+
165
+ **For full API access (with auth):**
166
+
167
+ ```json
168
+ {
169
+ "mcpServers": {
170
+ "cheddar": {
171
+ "command": "npx",
172
+ "args": ["-y", "@getcheddar/cheddar-mcp@1.0.5"],
87
173
  "env": {
88
174
  "CHEDDAR_API_URL": "https://api.getcheddar.com",
89
- "CHEDDAR_ACCESS_TOKEN": "your-access-token"
175
+ "CHEDDAR_USERNAME": "your-email@example.com",
176
+ "CHEDDAR_SECRET_KEY": "your-secret-key"
90
177
  }
91
178
  }
92
179
  }
93
180
  }
94
181
  ```
95
182
 
183
+ ---
184
+
96
185
  ## Usage with Cursor
97
186
 
98
- 1. Open Cursor Settings.
99
- 2. Navigate to **Features → MCP**.
187
+ 1. Open Cursor Settings
188
+ 2. Navigate to **Features → MCP**
100
189
  3. Add a new MCP server:
101
- - **Name:** `cheddar`
102
- - **Command:** `npx`
103
- - **Arguments:** `-y`, `@getcheddar/cheddar-mcp`
104
- - **Environment:** same variables as above (`CHEDDAR_API_URL`, `CHEDDAR_ACCESS_TOKEN`), or rely on a wrapper script that exports them.
105
190
 
106
- Prefer defining `env` in the MCP server configuration so the token is not tied to a single terminal session.
191
+ **For code generation:**
107
192
 
108
- ## Available Tools
193
+ - **Name:** `cheddar`
194
+ - **Command:** `npx`
195
+ - **Arguments:** `-y`, `@getcheddar/cheddar-mcp@1.0.5`
109
196
 
110
- ### Customer Management
197
+ **For full API access:**
111
198
 
112
- | Tool | Description |
113
- | ------------------------- | ----------------------------------- |
114
- | `cheddar_customer_get` | Retrieve a customer by ID or code |
115
- | `cheddar_customer_create` | Create a new customer |
116
- | `cheddar_customer_update` | Update customer information |
199
+ - **Name:** `cheddar`
200
+ - **Command:** `npx`
201
+ - **Arguments:** `-y`, `@getcheddar/cheddar-mcp@1.0.5`
202
+ - **Environment:** Set `CHEDDAR_USERNAME` and `CHEDDAR_SECRET_KEY`
117
203
 
118
- ### Payment Methods
204
+ ---
119
205
 
120
- | Tool | Description |
121
- | -------------------------------------------- | ---------------------------------------- |
122
- | `cheddar_payment_method_get` | Retrieve a payment method by ID |
123
- | `cheddar_payment_method_get_customer` | Get customer from payment method |
124
- | `cheddar_payment_method_get_gateway_account` | Get gateway account for payment method |
125
- | `cheddar_payment_token_create` | Tokenize card data (PCI-compliant) |
126
- | `cheddar_payment_method_add_to_customer` | Add tokenized payment method to customer |
206
+ ## Usage with Lovable.dev
207
+
208
+ ### Step 1: Get Credentials (for full API access, optional)
127
209
 
128
- ### Subscriptions & Plans
210
+ 1. Sign up at https://getcheddar.com/signup
211
+ 2. Configure your product
212
+ 3. Get your Secret Key: Top navbar → Configuration → Product Settings → Secret Key
129
213
 
130
- | Tool | Description |
131
- | ----------------------------------------- | ------------------------------------ |
132
- | `cheddar_subscription_get` | Retrieve subscription by ID |
133
- | `cheddar_subscription_get_customer` | Get customer from subscription |
134
- | `cheddar_subscription_get_plan` | Get plan from subscription |
135
- | `cheddar_subscription_get_payment_method` | Get payment method from subscription |
136
- | `cheddar_subscription_delete_promotion` | Remove promotion from subscription |
137
- | `cheddar_plan_get` | Retrieve plan by ID or code |
138
- | `cheddar_gateway_account_get` | Get gateway account details |
214
+ ### Step 2: Configure MCP in Lovable
139
215
 
140
- ### Checkout Integration
216
+ Add to your Lovable project configuration:
141
217
 
142
- | Tool | Description |
143
- | -------------------------------------------- | ------------------------------------ |
144
- | `cheddar_checkout_generate_hosted_url` | Generate hosted checkout page URL |
145
- | `cheddar_checkout_generate_embedded_form` | Generate embedded checkout form code |
146
- | `cheddar_checkout_generate_integration_code` | Generate framework-specific code |
147
- | `cheddar_checkout_validate_webhook` | Validate webhook signature |
148
- | `cheddar_checkout_configure_webhook` | Generate webhook handler code |
218
+ **Option 1: Code Generation Only (Recommended for starters)**
149
219
 
150
- ## Example Usage
220
+ ```json
221
+ {
222
+ "mcpServers": {
223
+ "cheddar": {
224
+ "command": "npx",
225
+ "args": ["-y", "@getcheddar/cheddar-mcp@1.0.5"]
226
+ }
227
+ }
228
+ }
229
+ ```
151
230
 
152
- ### Get a Customer
231
+ **Option 2: Full API Access**
153
232
 
233
+ ```json
234
+ {
235
+ "mcpServers": {
236
+ "cheddar": {
237
+ "command": "npx",
238
+ "args": ["-y", "@getcheddar/cheddar-mcp@1.0.5"],
239
+ "env": {
240
+ "CHEDDAR_API_URL": "https://api.getcheddar.com",
241
+ "CHEDDAR_USERNAME": "your-email@example.com",
242
+ "CHEDDAR_SECRET_KEY": "your-secret-key"
243
+ }
244
+ }
245
+ }
246
+ }
154
247
  ```
155
- Use the cheddar_customer_get tool with ID "cust_12345"
248
+
249
+ ### Step 3: Try These Prompts
250
+
251
+ **For code generation (no auth needed):**
252
+
253
+ ```
254
+ Create a complete payment integration for my React app:
255
+ 1. A pricing page with 3 tiers (Basic, Pro, Enterprise)
256
+ 2. Checkout flow using Cheddar's embedded form
257
+ 3. Webhook handler for subscription events
258
+ 4. Use Tailwind CSS for styling
259
+
260
+ Start with cheddar_checkout_generate_integration_code.
156
261
  ```
157
262
 
158
- ### Create a Payment Method Token
263
+ **For data access (requires auth):**
159
264
 
160
265
  ```
161
- Use the cheddar_payment_token_create tool with:
162
- - cardNumber: "4111111111111111"
163
- - expirationDate: "12/25"
164
- - cvv: "123"
165
- - cardholderName: "John Doe"
266
+ Build a customer dashboard showing:
267
+ - Customer profile from Cheddar
268
+ - Current subscription plan
269
+ - Payment methods on file
270
+ - Recent invoices
271
+
272
+ Use cheddar_customer_get and related tools.
166
273
  ```
167
274
 
168
- ### Generate React Integration
275
+ ---
276
+
277
+ ## Testing
278
+
279
+ ### Sandbox Environment
169
280
 
281
+ Use the sandbox for testing before going live:
282
+
283
+ ```json
284
+ {
285
+ "env": {
286
+ "CHEDDAR_API_URL": "https://sandbox.getcheddar.com",
287
+ "CHEDDAR_USERNAME": "your-sandbox-email",
288
+ "CHEDDAR_SECRET_KEY": "your-sandbox-secret"
289
+ }
290
+ }
170
291
  ```
171
- Use the cheddar_checkout_generate_integration_code tool with:
172
- - framework: "react"
173
- - integrationType: "embedded"
174
- - features: ["card", "subscriptions"]
175
- - styling: "tailwind"
292
+
293
+ ### Test Card Numbers
294
+
295
+ - `4111111111111111` - Visa (success)
296
+ - `4000000000000002` - Declined
297
+
298
+ ---
299
+
300
+ ## Complete Tool Reference
301
+
302
+ ### Code Generation Tools (No Auth Required)
303
+
304
+ | Tool | Description |
305
+ | -------------------------------------------- | -------------------------------------------- |
306
+ | `cheddar_checkout_generate_hosted_url` | Generate hosted checkout page URLs |
307
+ | `cheddar_checkout_generate_embedded_form` | Generate embedded checkout form code |
308
+ | `cheddar_checkout_generate_integration_code` | Generate framework-specific integration code |
309
+ | `cheddar_checkout_configure_webhook` | Generate webhook handler code |
310
+ | `cheddar_checkout_validate_webhook` | Validate webhook signatures |
311
+
312
+ ### Data Access Tools (Auth Required)
313
+
314
+ | Tool | Description |
315
+ | -------------------------------------------- | ---------------------------------------- |
316
+ | `cheddar_customer_get` | Retrieve a customer by ID or code |
317
+ | `cheddar_customer_create` | Create a new customer |
318
+ | `cheddar_customer_update` | Update customer information |
319
+ | `cheddar_payment_method_get` | Retrieve a payment method by ID |
320
+ | `cheddar_payment_method_get_customer` | Get customer from payment method |
321
+ | `cheddar_payment_method_get_gateway_account` | Get gateway account for payment method |
322
+ | `cheddar_payment_token_create` | Tokenize card data (PCI-compliant) |
323
+ | `cheddar_payment_method_add_to_customer` | Add tokenized payment method to customer |
324
+ | `cheddar_subscription_get` | Retrieve subscription by ID |
325
+ | `cheddar_subscription_get_customer` | Get customer from subscription |
326
+ | `cheddar_subscription_get_plan` | Get plan from subscription |
327
+ | `cheddar_subscription_get_payment_method` | Get payment method from subscription |
328
+ | `cheddar_subscription_delete_promotion` | Remove promotion from subscription |
329
+ | `cheddar_plan_get` | Retrieve plan by ID or code |
330
+ | `cheddar_gateway_account_get` | Get gateway account details |
331
+
332
+ ---
333
+
334
+ ## Docker Usage
335
+
336
+ Build and run with Docker:
337
+
338
+ ```bash
339
+ # Build
340
+ docker build -t cheddar-mcp ./packages/cheddar-mcp
341
+
342
+ # Run (code generation only)
343
+ docker run -i --rm cheddar-mcp
344
+
345
+ # Run with auth
346
+ docker run -i --rm \
347
+ -e CHEDDAR_API_URL=https://api.getcheddar.com \
348
+ -e CHEDDAR_USERNAME=your-email \
349
+ -e CHEDDAR_SECRET_KEY=your-secret \
350
+ cheddar-mcp
176
351
  ```
177
352
 
353
+ ---
354
+
178
355
  ## Development
179
356
 
180
357
  ```bash
@@ -195,12 +372,14 @@ npm run dev
195
372
  npm test
196
373
  ```
197
374
 
375
+ ---
376
+
198
377
  ## License
199
378
 
200
379
  MIT © Cheddar (chdr)
201
380
 
202
381
  ## Support
203
382
 
204
- - Documentation: https://docs.cheddar.com
205
- - Support: support@cheddar.com
383
+ - Documentation: https://docs.getcheddar.com
384
+ - Support: support@getcheddar.com
206
385
  - Issues: https://github.com/chdr/cheddar-ai-tools/issues
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@getcheddar/cheddar-mcp",
3
- "version": "1.0.4",
3
+ "version": "1.0.5",
4
4
  "description": "Model Context Protocol server for Cheddar Payment Platform integration",
5
5
  "publishConfig": {
6
6
  "access": "public"