@shoppexio/mcp-theme-server 0.1.2 → 0.2.0

package/README.md

@@ -1,104 +1,48 @@
 # @shoppexio/mcp-theme-server
 
-Model Context Protocol server for Shoppex theme operations.
+MCP server for Shoppex theme operations.
 
-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.
+Use this package when you want an MCP-compatible client like Claude Code, Codex, Cursor, or OpenCode to work against hosted Shoppex themes.
 
-## Install
+## 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:
 
 ```bash
-npm install -g @shoppexio/mcp-theme-server
+export SHOPPEX_API_KEY=shx_your_key
+export SHOPPEX_API_URL=https://api.shoppex.io
 ```
 
-Or run without installing:
+## Start
+
+Install and run from npm:
 
 ```bash
 npx -y @shoppexio/mcp-theme-server
 ```
 
-## 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"
-      }
-    }
-  }
-}
+Or, if you are working from this repo:
+
+```bash
+bun packages/mcp-theme-server/bin/shoppex-mcp-theme-server.mjs
 ```
 
-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:
+## Auth
+
+Recommended scopes:
 - `themes.read`
 - `themes.write`
 
-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
+## Related Docs
 
-Proprietary. © Shoppex.
+- AI Workflows: `https://docs.shoppex.io/themes/ai-workflows`
+- Theme Control Plane: `https://docs.shoppex.io/themes/theme-control-plane`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shoppexio/mcp-theme-server",
-  "version": "0.1.2",
+  "version": "0.2.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": "workspace:*"
+    "@shoppexio/theme-control-client": "^0.1.0"
   }
 }

package/src/server.mjs

@@ -22,7 +22,7 @@ function jsonContent(value) {
 export function createThemeToolCatalog() {
   return [
     {
-      name: 'theme.inspect',
+      name: 'theme_inspect',
       description: 'Inspect a Shoppex theme and return editable areas, sections, settings, design tokens, and constraints.',
       inputSchema: {
         theme_id: z.string().min(1),
@@ -30,7 +30,7 @@ export function createThemeToolCatalog() {
       execute: ({ theme_id }, client) => client.inspectTheme(theme_id),
     },
     {
-      name: 'theme.diff',
+      name: 'theme_diff',
       description: 'Show changes between the current draft and the latest published theme snapshot.',
       inputSchema: {
         theme_id: z.string().min(1),
@@ -38,7 +38,7 @@ export function createThemeToolCatalog() {
       execute: ({ theme_id }, client) => client.diffTheme(theme_id),
     },
     {
-      name: 'theme.read_file',
+      name: 'theme_read_file',
       description: 'Read a single source file from a Shoppex theme.',
       inputSchema: {
         theme_id: z.string().min(1),
@@ -47,7 +47,7 @@ export function createThemeToolCatalog() {
       execute: ({ theme_id, file_path }, client) => client.readThemeFile(theme_id, file_path),
     },
     {
-      name: 'theme.search_files',
+      name: 'theme_search_files',
       description: 'Search theme files by path or content.',
       inputSchema: {
         theme_id: z.string().min(1),
@@ -57,7 +57,7 @@ export function createThemeToolCatalog() {
       execute: ({ theme_id, query, limit }, client) => client.searchThemeFiles(theme_id, query, limit),
     },
     {
-      name: 'theme.apply',
+      name: 'theme_apply',
       description: 'Apply one or more text-file changes to a theme draft with server-side verification.',
       inputSchema: {
         theme_id: z.string().min(1),
@@ -75,7 +75,7 @@ export function createThemeToolCatalog() {
       }),
     },
     {
-      name: 'theme.accept',
+      name: 'theme_accept',
       description: 'Accept an already generated draft patch from a dashboard-agent run.',
       inputSchema: {
         theme_id: z.string().min(1),
@@ -90,7 +90,7 @@ export function createThemeToolCatalog() {
       }),
     },
     {
-      name: 'theme.create',
+      name: 'theme_create',
       description: 'Create a new theme scaffold from a Shoppex base theme.',
       inputSchema: {
         base: z.enum(['default', 'classic', 'nebula', 'pulse', 'phantom', 'starlight']),
@@ -104,7 +104,7 @@ export function createThemeToolCatalog() {
       }),
     },
     {
-      name: 'theme.create_section',
+      name: 'theme_create_section',
       description: 'Scaffold a new theme section and wire it into theme.config.ts.',
       inputSchema: {
         theme_id: z.string().min(1),
@@ -119,7 +119,7 @@ export function createThemeToolCatalog() {
       }),
     },
     {
-      name: 'theme.create_page',
+      name: 'theme_create_page',
       description: 'Scaffold a new static page and wire its route into src/App.tsx.',
       inputSchema: {
         theme_id: z.string().min(1),
@@ -134,7 +134,7 @@ export function createThemeToolCatalog() {
       }),
     },
     {
-      name: 'theme.update_config',
+      name: 'theme_update_config',
       description: 'Extend theme.config.ts with a new settings field.',
       inputSchema: {
         theme_id: z.string().min(1),
@@ -149,7 +149,7 @@ export function createThemeToolCatalog() {
       }),
     },
     {
-      name: 'theme.preview',
+      name: 'theme_preview',
       description: 'Start or reuse a live preview session for the current theme draft.',
       inputSchema: {
         theme_id: z.string().min(1),
@@ -157,7 +157,7 @@ export function createThemeToolCatalog() {
       execute: ({ theme_id }, client) => client.startThemePreview(theme_id),
     },
     {
-      name: 'theme.stop_preview',
+      name: 'theme_stop_preview',
       description: 'Stop a running live preview session.',
       inputSchema: {
         theme_id: z.string().min(1),
@@ -166,7 +166,7 @@ export function createThemeToolCatalog() {
       execute: ({ theme_id, session_id }, client) => client.stopThemePreview(theme_id, session_id),
     },
     {
-      name: 'theme.publish',
+      name: 'theme_publish',
       description: 'Queue a publish/deploy for the current accepted theme draft.',
       inputSchema: {
         theme_id: z.string().min(1),
@@ -174,7 +174,7 @@ export function createThemeToolCatalog() {
       execute: ({ theme_id }, client) => client.publishTheme(theme_id),
     },
     {
-      name: 'theme.publish_status',
+      name: 'theme_publish_status',
       description: 'Read the current publish job status.',
       inputSchema: {
         theme_id: z.string().min(1),
@@ -183,7 +183,7 @@ export function createThemeToolCatalog() {
       execute: ({ theme_id, job_id }, client) => client.getThemePublishStatus(theme_id, job_id),
     },
     {
-      name: 'theme.validate',
+      name: 'theme_validate',
       description: 'Run a validation-only build and optional typecheck without publishing.',
       inputSchema: {
         theme_id: z.string().min(1),
@@ -194,7 +194,7 @@ export function createThemeToolCatalog() {
       }),
     },
     {
-      name: 'theme.settings_get',
+      name: 'theme_settings_get',
       description: 'Read the current builder settings values for a theme.',
       inputSchema: {
         theme_id: z.string().min(1),
@@ -202,7 +202,7 @@ export function createThemeToolCatalog() {
       execute: ({ theme_id }, client) => client.getThemeSettings(theme_id),
     },
     {
-      name: 'theme.settings_update',
+      name: 'theme_settings_update',
       description: 'Update theme builder settings without editing source files directly.',
       inputSchema: {
         theme_id: z.string().min(1),
@@ -213,7 +213,7 @@ export function createThemeToolCatalog() {
       }),
     },
     {
-      name: 'theme.backups',
+      name: 'theme_backups',
       description: 'List available theme backups for rollback.',
       inputSchema: {
         theme_id: z.string().min(1),
@@ -221,7 +221,7 @@ export function createThemeToolCatalog() {
       execute: ({ theme_id }, client) => client.listThemeBackups(theme_id),
     },
     {
-      name: 'theme.rollback',
+      name: 'theme_rollback',
       description: 'Rollback a theme to a previous backup snapshot.',
       inputSchema: {
         theme_id: z.string().min(1),
@@ -230,7 +230,7 @@ export function createThemeToolCatalog() {
       execute: ({ theme_id, backup_id }, client) => client.rollbackTheme(theme_id, backup_id),
     },
     {
-      name: 'theme.latest_run',
+      name: 'theme_latest_run',
       description: 'Read the latest dashboard-agent run metadata for a theme.',
       inputSchema: {
         theme_id: z.string().min(1),
@@ -240,8 +240,13 @@ export function createThemeToolCatalog() {
   ];
 }
 
+function normalizeToolName(name) {
+  return typeof name === 'string' ? name.replace(/\./g, '_') : name;
+}
+
 export async function executeThemeTool(toolName, args, client) {
-  const tool = createThemeToolCatalog().find((entry) => entry.name === toolName);
+  const normalized = normalizeToolName(toolName);
+  const tool = createThemeToolCatalog().find((entry) => entry.name === normalized);
   if (!tool) {
     throw new Error(`Unknown tool: ${toolName}`);
   }