@curenorway/kode-mcp 1.3.0 → 1.4.0

package/README.md

@@ -2,42 +2,52 @@
 
 MCP (Model Context Protocol) server that enables AI agents to manage Webflow scripts via Cure Kode CDN.
 
-## What is this?
+## Features
 
-This MCP server allows AI assistants like Claude to directly interact with Cure Kode:
-- List, create, update, and delete scripts
-- Deploy to staging and production
-- Check deployment status
-- Analyze web pages for script detection
+- **Script Management** - List, create, update, and delete scripts
+- **Deployment Control** - Deploy to staging, promote to production, rollback
+- **Page Context** - Cache and retrieve page structures for development
+- **Script Analysis** - Auto-analyze scripts for metadata (selectors, triggers, dependencies)
+- **Production Safety** - Explicit enable required, confirmation for promote
 
 ## Installation
 
 ### For Claude Code
 
-Add to your Claude Code configuration (`~/.claude/claude_code_config.json`):
+The easiest way is to run `kode init` in your project, which creates `.mcp.json`:
 
 ```json
 {
   "mcpServers": {
     "cure-kode": {
+      "type": "stdio",
       "command": "npx",
-      "args": ["@curenorway/kode-mcp"]
+      "args": ["-y", "@curenorway/kode-mcp"]
     }
   }
 }
 ```
 
-### For Cursor / Other IDEs
+Then restart Claude Code and approve the MCP when prompted.
 
-Refer to your IDE's MCP configuration documentation.
+### Manual Configuration
 
-## Configuration
+Add to your Claude Code configuration (`~/.claude/claude_code_config.json`):
 
-The MCP server needs to know which site to manage. Configure via:
+```json
+{
+  "mcpServers": {
+    "cure-kode": {
+      "command": "npx",
+      "args": ["-y", "@curenorway/kode-mcp"]
+    }
+  }
+}
+```
 
-### Option 1: Project Config (Recommended)
+## Configuration
 
-Run `kode init` in your project to create `.cure-kode/config.json`:
+The MCP server reads configuration from `.cure-kode/config.json` (created by `kode init`):
 
 ```json
 {
@@ -45,46 +55,151 @@ Run `kode init` in your project to create `.cure-kode/config.json`:
   "siteSlug": "my-site",
   "siteName": "My Site",
   "apiKey": "ck_...",
-  "scriptsDir": "kode",
+  "scriptsDir": ".cure-kode-scripts",
   "environment": "staging"
 }
 ```
 
-### Option 2: Environment Variables
-
+Or via environment variables:
 ```bash
 export CURE_KODE_API_KEY="ck_..."
 export CURE_KODE_SITE_ID="your-site-uuid"
-export CURE_KODE_API_URL="https://app.cure.no"  # optional
 ```
 
 ## Available Tools
 
+### Script Management
+
 | Tool | Description |
 |------|-------------|
 | `kode_list_scripts` | List all scripts for the site |
-| `kode_get_script` | Get script content by slug |
-| `kode_create_script` | Create a new script |
-| `kode_update_script` | Update script content |
+| `kode_get_script` | Get script by slug (supports `includeContent: false` for metadata only) |
+| `kode_create_script` | Create a new script entry (metadata only, no content) |
+| `kode_update_script` | Update script settings (autoLoad, scope, purpose) |
 | `kode_delete_script` | Delete a script |
-| `kode_deploy` | Deploy to staging/production |
-| `kode_promote` | Promote staging to production |
+| `kode_push` | Upload local files from `.cure-kode-scripts/` to server |
+
+### Deployment
+
+| Tool | Description |
+|------|-------------|
+| `kode_deploy` | Deploy to staging |
+| `kode_promote` | Promote staging to production (**requires `confirmed: true`**) |
+| `kode_rollback` | Rollback to previous deployment |
 | `kode_status` | Get deployment status |
-| `kode_fetch_html` | Analyze a webpage |
-| `kode_list_pages` | List page definitions |
+
+### Production Management
+
+| Tool | Description |
+|------|-------------|
+| `kode_production_enable` | Enable production environment |
+| `kode_production_disable` | Disable production environment |
+
+### Page & HTML Analysis
+
+| Tool | Description |
+|------|-------------|
+| `kode_fetch_html` | Fetch and parse HTML from URL |
+| `kode_fetch_html_smart` | Fetch with CMS truncation for smaller context |
+| `kode_list_pages` | List page definitions for the site |
+| `kode_assign_script_to_page` | Assign script to specific pages |
+| `kode_remove_script_from_page` | Remove script from page |
+
+### Page Context (for AI Development)
+
+| Tool | Description |
+|------|-------------|
+| `kode_refresh_page` | Fetch and cache page structure |
+| `kode_get_page_context` | Get cached page context (sections, forms, CTAs, selectors) |
+| `kode_list_pages_context` | List all cached page contexts |
+
+### Script Metadata
+
+| Tool | Description |
+|------|-------------|
+| `kode_analyze_script` | Analyze script and generate metadata |
+| `kode_get_script_metadata` | Get script metadata and AI summary |
+
+### Other
+
+| Tool | Description |
+|------|-------------|
 | `kode_site_info` | Get site info and CDN URL |
+| `kode_read_context` | Read AI context file |
+| `kode_update_context` | Update AI context file |
+
+## Important: Content Workflow
+
+**MCP is the control plane - never send script content through MCP tools.**
+
+The correct workflow:
+1. Write script file locally to `.cure-kode-scripts/script-name.js`
+2. Use `kode_push` to upload local files to server
+3. Use `kode_deploy` to deploy
+
+```
+AI writes file → kode_push → kode_deploy
+```
+
+**Do NOT** pass content to `kode_create_script` or `kode_update_script` - these only handle metadata.
+
+## Safety Features
+
+### Production Confirmation
+
+`kode_promote` requires explicit confirmation to prevent accidental production deployments:
+
+```typescript
+// This will fail:
+kode_promote()
+
+// This works:
+kode_promote({ confirmed: true })
+```
+
+### Production Disabled by Default
+
+New sites start with production disabled. Must explicitly enable:
+
+```typescript
+kode_production_enable()
+// Then can promote
+kode_promote({ confirmed: true })
+```
+
+## Example Usage
 
-## Example Prompts
+### Create and Deploy a Script
 
-Once configured, you can ask Claude:
+```
+1. "Create a new script called tracking.js"
+   → kode_create_script({ name: "tracking", slug: "tracking", type: "javascript" })
+
+2. Write the file locally
+   → Write to .cure-kode-scripts/tracking.js
+
+3. "Push the changes"
+   → kode_push()
+
+4. "Deploy to staging"
+   → kode_deploy()
+
+5. "Promote to production"
+   → kode_promote({ confirmed: true })
+```
+
+### Analyze a Page and Add Functionality
 
 ```
-"List all the scripts in Cure Kode"
-"Create a new tracking script that logs page views"
-"Update the init.js script to add error handling"
-"Deploy to staging"
-"What's the current deployment status?"
-"Analyze example.com to see what scripts are loaded"
+1. "Analyze the homepage"
+   → kode_fetch_html_smart({ url: "https://mysite.com" })
+   → kode_refresh_page({ url: "https://mysite.com" })
+
+2. "What sections are on this page?"
+   → kode_get_page_context({ url: "https://mysite.com" })
+
+3. "Add a script to animate the hero section"
+   → Create script, write file, push, deploy
 ```
 
 ## How It Works
@@ -92,88 +207,73 @@ Once configured, you can ask Claude:
 ```
 ┌─────────────────┐      ┌─────────────────┐      ┌─────────────────┐
 │   AI Agent      │ MCP  │  Kode MCP       │ REST │  Cure Kode API  │
-│  (Claude/etc)   │─────▶│  Server         │─────▶│  (Railway)      │
+│  (Claude/etc)   │─────▶│  Server         │─────▶│  (app.cure.no)  │
 └─────────────────┘      └─────────────────┘      └─────────────────┘
                                 │
                                 ▼
                          ┌─────────────────┐
                          │ Local Scripts   │
-                         │ (.cure-kode/)   │
+                         │(.cure-kode-scripts/)│
                          └─────────────────┘
 ```
 
-1. AI agent calls MCP tools (e.g., `kode_create_script`)
-2. MCP server reads config from `.cure-kode/config.json`
-3. MCP server calls Cure Kode REST API with API key
-4. Results returned to AI agent
-
 ## Security
 
 ### API Key Authentication
 
-- **SHA256 Hashed Storage**: API keys are hashed before storage on the server
+- **Hashed Storage**: API keys are SHA256/HMAC hashed before server storage
 - **Site-scoped**: Each API key is bound to a specific CDN site
-- **Permission-based**: Keys have granular permissions:
-  - `read` - List/view scripts and deployments
-  - `write` - Create and update scripts
-  - `deploy` - Deploy to staging/production
-  - `delete` - Delete scripts
+- **Permission-based**: Granular permissions (read, write, deploy, delete)
 - **Expiration**: Keys can have optional expiration dates
 
-### Local Security
+### CORS Security (v2.6)
 
-- API keys stored in `.cure-kode/config.json` (auto-gitignored)
-- Never commit API keys to version control
-- Keys prefixed with `ck_` for easy identification
+Script endpoints restrict CORS to configured domains:
+- Site's domain, staging_domain, production_domain
+- Webflow preview domains (*.webflow.io)
+- Localhost for development
+- **No wildcard CORS** on script endpoints
 
-### Network Security
+### SSRF Protection
 
-- All API calls use HTTPS
-- **SSRF Protection**: HTML fetch endpoints block:
-  - Private IP ranges (127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16)
-  - Localhost and internal hostnames
-  - Cloud metadata endpoints (169.254.169.254)
-- Only HTTP/HTTPS protocols allowed
-
-### Best Practices
-
-- Generate separate API keys for different environments/developers
-- Use read-only keys when full access isn't needed
-- Rotate keys periodically
-- Revoke keys when team members leave
+HTML fetch endpoints block:
+- Private IP ranges (127.0.0.0/8, 10.0.0.0/8, etc.)
+- Cloud metadata endpoints (169.254.169.254)
+- Internal hostnames
 
 ## Troubleshooting
 
 ### "Cure Kode not configured"
 
-Either:
-1. Run `kode init` in your project directory
-2. Set `CURE_KODE_API_KEY` and `CURE_KODE_SITE_ID` environment variables
+Run `kode init` in your project directory to create configuration.
 
 ### "API key invalid"
 
-- Check your API key starts with `ck_`
-- Verify the key hasn't expired
-- Ensure the key has required permissions
+- Check key starts with `ck_`
+- Verify key hasn't expired
+- Ensure key has required permissions
 
-### Tools not appearing in Claude
+### "Production not enabled"
 
-- Restart Claude Code after configuration changes
-- Check the MCP server is running: `npx @curenorway/kode-mcp`
-- Verify config file syntax
+Use `kode_production_enable()` before promoting.
 
-## Development
+### "Promote requires confirmation"
 
-```bash
-# Install dependencies
-pnpm install
+Add `confirmed: true` parameter:
+```typescript
+kode_promote({ confirmed: true })
+```
 
-# Build
-pnpm build
+### Tools not appearing in Claude
 
-# Run locally
-node dist/index.js
-```
+1. Restart Claude Code after config changes
+2. Check `.mcp.json` syntax
+3. Verify MCP server runs: `npx @curenorway/kode-mcp`
+
+## Requirements
+
+- Node.js 18 or later
+- Cure Kode API key (from https://app.cure.no/tools/kode)
 
 ## License
 

package/dist/index.js

@@ -105,6 +105,15 @@ var KodeApiClient = class {
   async getDeploymentStatus(siteId) {
     return this.request(`/api/cdn/sites/${siteId}/deployments/status`);
   }
+  async rollback(siteId, environment = "staging") {
+    return this.request("/api/cdn/deploy/rollback", {
+      method: "POST",
+      body: JSON.stringify({
+        siteId,
+        environment
+      })
+    });
+  }
   // v2.3: Production enabled toggle
   async setProductionEnabled(siteId, enabled, productionDomain) {
     return this.request(`/api/cdn/sites/${siteId}/production`, {
@@ -408,10 +417,30 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       },
       {
         name: "kode_promote",
-        description: "Promote the latest staging deployment to production. Use this after testing on staging.",
+        description: "Promote the latest staging deployment to production. Use this after testing on staging. IMPORTANT: Requires confirmed=true to actually promote - this prevents accidental production deployments.",
         inputSchema: {
           type: "object",
-          properties: {},
+          properties: {
+            confirmed: {
+              type: "boolean",
+              description: "Safety confirmation. Must be set to true to proceed with production promotion. If false or missing, returns a preview of what would be promoted."
+            }
+          },
+          required: []
+        }
+      },
+      {
+        name: "kode_rollback",
+        description: "Rollback to the previous deployment. Copies the previous version back to the active environment. Use this if a deployment caused issues.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            environment: {
+              type: "string",
+              enum: ["staging", "production"],
+              description: "Environment to rollback. Default: staging"
+            }
+          },
           required: []
         }
       },
@@ -1009,6 +1038,7 @@ Scripts deployed (${scriptSizes.length}):`;
         };
       }
       case "kode_promote": {
+        const { confirmed } = args;
         const status = await client.getDeploymentStatus(siteId);
         if (!status.productionEnabled) {
           return {
@@ -1032,17 +1062,69 @@ Scripts deployed (${scriptSizes.length}):`;
             isError: true
           };
         }
+        if (!confirmed) {
+          const stagingVersion = status.staging.lastSuccessful?.version || "unknown";
+          const productionVersion = status.production.lastSuccessful?.version || "(none)";
+          return {
+            content: [
+              {
+                type: "text",
+                text: `\u26A0\uFE0F PRODUCTION PROMOTION CONFIRMATION REQUIRED
+
+This will deploy to production:
+  Staging version: ${stagingVersion}
+  Current production: ${productionVersion}
+
+To proceed, call kode_promote with confirmed: true
+
+Note: Always test on staging first before promoting to production.`
+              }
+            ]
+          };
+        }
         const deployment = await client.promoteToProduction(siteId);
         return {
           content: [
             {
               type: "text",
-              text: `Promoted ${deployment.version} to production
+              text: `\u2705 Promoted ${deployment.version} to production
 Status: ${deployment.status}`
             }
           ]
         };
       }
+      case "kode_rollback": {
+        const { environment = "staging" } = args;
+        if (environment === "production") {
+          const status = await client.getDeploymentStatus(siteId);
+          if (!status.productionEnabled) {
+            return {
+              content: [
+                {
+                  type: "text",
+                  text: "Cannot rollback production: Production is not enabled for this site."
+                }
+              ],
+              isError: true
+            };
+          }
+        }
+        const result = await client.rollback(siteId, environment);
+        return {
+          content: [
+            {
+              type: "text",
+              text: `\u2705 Rolled back ${environment}
+
+From: ${result.rolledBackFrom.version}
+To: ${result.rolledBackTo.version}
+
+CDN URL: ${result.cdn_url}
+Duration: ${result.duration_ms}ms`
+            }
+          ]
+        };
+      }
       case "kode_production_enable": {
         const { productionDomain } = args;
         const result = await client.setProductionEnabled(siteId, true, productionDomain);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@curenorway/kode-mcp",
-  "version": "1.3.0",
-  "description": "MCP server for Cure Kode - enables AI agents to manage Webflow scripts",
+  "version": "1.4.0",
+  "description": "MCP server for Cure Kode CDN - enables AI agents to manage, deploy, and analyze Webflow scripts",
   "type": "module",
   "bin": {
     "cure-kode-mcp": "./dist/index.js"