@shoppexio/mcp-theme-server 0.1.1 → 0.1.2

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.1.1",
+  "version": "0.1.2",
   "description": "Shoppex MCP server for theme control plane operations",
   "type": "module",
   "repository": {
@@ -27,7 +27,7 @@
   },
   "files": [
     "bin",
-    "src",
+    "src/server.mjs",
     "README.md"
   ],
   "scripts": {
@@ -38,6 +38,6 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.28.0",
-    "@shoppexio/theme-control-client": "0.1.0"
+    "@shoppexio/theme-control-client": "workspace:*"
   }
 }

package/src/server.mjs

@@ -93,7 +93,7 @@ export function createThemeToolCatalog() {
       name: 'theme.create',
       description: 'Create a new theme scaffold from a Shoppex base theme.',
       inputSchema: {
-        base: z.enum(['default', 'classic', 'nebula', 'pulse']),
+        base: z.enum(['default', 'classic', 'nebula', 'pulse', 'phantom', 'starlight']),
         name: z.string().min(1).optional(),
         set_as_active: z.boolean().optional(),
       },

package/src/server.test.mjs

@@ -1,45 +0,0 @@
-import { describe, expect, test } from 'bun:test';
-import { createThemeToolCatalog, executeThemeTool } from './server.mjs';
-
-describe('shoppex theme mcp server', () => {
-  test('registers the expected theme tools', () => {
-    const tools = createThemeToolCatalog().map((tool) => tool.name);
-
-    expect(tools).toContain('theme.inspect');
-    expect(tools).toContain('theme.apply');
-    expect(tools).toContain('theme.create');
-    expect(tools).toContain('theme.settings_update');
-  });
-
-  test('maps theme.apply to the control plane client', async () => {
-    const client = {
-      applyThemeChanges: async (themeId, body) => ({ themeId, body }),
-    };
-
-    const result = await executeThemeTool('theme.apply', {
-      theme_id: 'theme_1',
-      changes: [
-        {
-          path: 'src/pages/Home.tsx',
-          content: 'export default function Home() { return <div>Updated</div>; }',
-        },
-      ],
-      run_typecheck: true,
-      verification_strategy: 'full',
-    }, client);
-
-    expect(result).toEqual({
-      themeId: 'theme_1',
-      body: {
-        changes: [
-          {
-            path: 'src/pages/Home.tsx',
-            content: 'export default function Home() { return <div>Updated</div>; }',
-          },
-        ],
-        runTypecheck: true,
-        verificationStrategy: 'full',
-      },
-    });
-  });
-});