@shoppexio/mcp-theme-server 0.2.0 → 0.4.0

package/README.md

@@ -1,48 +1,104 @@
 # @shoppexio/mcp-theme-server
 
-MCP server for Shoppex theme operations.
+Model Context Protocol server for Shoppex theme operations.
 
-Use this package when you want an MCP-compatible client like Claude Code, Codex, Cursor, or OpenCode to work against hosted Shoppex themes.
+Connect any MCP-capable client — Claude Desktop, Claude Code, Cursor, Windsurf, Codex — to your Shoppex themes. Inspect, edit, validate, preview, and publish themes directly from your LLM workflow.
 
-## What It Exposes
-
-The server exposes tools for:
-- inspect and diff
-- read and search
-- apply changes
-- create sections and pages
-- validate, preview, publish, and rollback
-
-## Runtime Config
-
-Set these environment variables before starting the server:
+## Install
 
 ```bash
-export SHOPPEX_API_KEY=shx_your_key
-export SHOPPEX_API_URL=https://api.shoppex.io
+npm install -g @shoppexio/mcp-theme-server
 ```
 
-## Start
-
-Install and run from npm:
+Or run without installing:
 
 ```bash
 npx -y @shoppexio/mcp-theme-server
 ```
 
-Or, if you are working from this repo:
-
-```bash
-bun packages/mcp-theme-server/bin/shoppex-mcp-theme-server.mjs
+## Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "shoppex-themes": {
+      "command": "npx",
+      "args": ["-y", "@shoppexio/mcp-theme-server"],
+      "env": {
+        "SHOPPEX_API_KEY": "shx_your_dev_api_key"
+      }
+    }
+  }
+}
 ```
 
-## Auth
-
-Recommended scopes:
+Restart Claude Desktop. The themes tools appear under the tools menu.
+
+## Cursor / Windsurf / Other
+
+Any MCP client with stdio transport works. Set the same env var and point to `shoppex-mcp-theme-server` as the command.
+
+## Tools (19)
+
+| Tool | Purpose |
+|------|---------|
+| `theme.inspect` | Inspect theme structure and manifest |
+| `theme.diff` | Diff theme state against a target |
+| `theme.read_file` | Read one file from a theme |
+| `theme.search_files` | Search across theme files |
+| `theme.apply` | Apply a change set to a theme |
+| `theme.accept` | Accept a pending change |
+| `theme.create` | Scaffold a new theme |
+| `theme.create_section` | Add a section |
+| `theme.create_page` | Add a page |
+| `theme.update_config` | Update `theme.config.ts` |
+| `theme.preview` | Start a preview instance |
+| `theme.stop_preview` | Stop a preview instance |
+| `theme.publish` | Publish theme |
+| `theme.publish_status` | Check publish status |
+| `theme.validate` | Validate theme build |
+| `theme.settings_get` | Read theme settings |
+| `theme.settings_update` | Update theme settings |
+| `theme.backups` | List backups |
+| `theme.rollback` | Rollback to a previous version |
+| `theme.latest_run` | Inspect last run result |
+
+## Required Scopes
+
+Your Shoppex Dev API key needs:
 - `themes.read`
 - `themes.write`
 
-## Related Docs
+Create one at [dashboard.shoppex.io/developer/api](https://dashboard.shoppex.io/developer/api).
+
+## Environment Variables
+
+| Variable | Required | Default |
+|----------|----------|---------|
+| `SHOPPEX_API_KEY` | yes | — |
+| `SHOPPEX_API_URL` | no | `https://api.shoppex.io` |
+
+## Example Prompts
+
+Once connected in Claude Desktop:
+
+- "Inspect the Nebula theme and list its sections."
+- "Create a new Hero section in my Pulse theme with a purple gradient background."
+- "Preview the Classic theme with the accent color set to `#7C3AED`."
+- "Publish the current draft of my Starlight theme."
+
+## Companion
+
+Pair with [`@shoppexio/mcp-commerce-server`](https://www.npmjs.com/package/@shoppexio/mcp-commerce-server) for products, orders, customers, coupons, and payment links.
+
+## Docs
+
+- [AI Workflows](https://docs.shoppex.io/themes/ai-workflows)
+- [Build & Customize with AI](https://docs.shoppex.io/themes/build-and-customize-with-ai)
+- [Developer API](https://docs.shoppex.io/api-reference/introduction)
+
+## License
 
-- AI Workflows: `https://docs.shoppex.io/themes/ai-workflows`
-- Theme Control Plane: `https://docs.shoppex.io/themes/theme-control-plane`
+Proprietary. © Shoppex.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shoppexio/mcp-theme-server",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Shoppex MCP server for theme control plane operations",
   "type": "module",
   "repository": {
@@ -38,6 +38,6 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.28.0",
-    "@shoppexio/theme-control-client": "^0.1.0"
+    "@shoppexio/theme-control-client": "^0.3.0"
   }
 }

package/src/server.mjs

@@ -21,6 +21,12 @@ function jsonContent(value) {
 
 export function createThemeToolCatalog() {
   return [
+    {
+      name: 'theme_list',
+      description: 'List all themes belonging to the authenticated shop. Returns id, name, scheme, version, is_active, preview_url for each theme. Use this first when the user asks about a theme by name — find the id, then call theme_inspect.',
+      inputSchema: {},
+      execute: (_args, client) => client.listThemes(),
+    },
     {
       name: 'theme_inspect',
       description: 'Inspect a Shoppex theme and return editable areas, sections, settings, design tokens, and constraints.',
@@ -103,6 +109,26 @@ export function createThemeToolCatalog() {
         ...(set_as_active !== undefined ? { setAsActive: set_as_active } : {}),
       }),
     },
+    {
+      name: 'theme_ai_apply',
+      description: 'Let Shoppex\'s theme-builder agent edit a theme from a natural-language prompt. Runs plan+apply in one call: agent picks a plan, edits files, verifies the build. Returns a draft run_id + summary. Use theme_preview next to get a live URL, then theme_accept to lock it in, then theme_publish to deploy. Examples: "add a testimonials section above the footer", "switch the accent color to purple", "fix the homepage hero to center-align on mobile".',
+      inputSchema: {
+        theme_id: z.string().min(1),
+        prompt: z.string().min(1).max(2000),
+        variant_count: z.number().int().min(1).max(3).optional(),
+        mode: z.enum(['standard', 'compare_variants', 'fix_build_error', 'fix_type_error']).optional(),
+        verification_mode: z.enum(['off', 'smart', 'always']).optional(),
+        preview_notes: z.string().min(1).max(1200).optional(),
+      },
+      execute: ({ theme_id, prompt, variant_count, mode, verification_mode, preview_notes }, client) => {
+        const body = { prompt };
+        if (variant_count !== undefined) body.variant_count = variant_count;
+        if (mode !== undefined) body.mode = mode;
+        if (verification_mode !== undefined) body.verification_mode = verification_mode;
+        if (preview_notes !== undefined) body.preview_notes = preview_notes;
+        return client.aiApplyTheme(theme_id, body);
+      },
+    },
     {
       name: 'theme_create_section',
       description: 'Scaffold a new theme section and wire it into theme.config.ts.',