@shoppexio/mcp-theme-server 0.1.0

package/README.md

@@ -0,0 +1,48 @@
+# @shoppexio/mcp-theme-server
+
+MCP server for Shoppex theme operations.
+
+Use this package when you want an MCP-compatible client like Codex, Claude Desktop, or Cursor to work against hosted Shoppex themes.
+
+## 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
+export SHOPPEX_API_KEY=shx_your_key
+export SHOPPEX_API_URL=https://api.shoppex.io
+```
+
+## Start
+
+Install and run from npm:
+
+```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
+```
+
+## Auth
+
+Recommended scopes:
+- `themes.read`
+- `themes.write`
+
+## Related Docs
+
+- AI Workflows: `https://docs.shoppex.io/themes/ai-workflows`
+- Theme Control Plane: `https://docs.shoppex.io/themes/theme-control-plane`

package/bin/shoppex-mcp-theme-server.mjs

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+import { startThemeMcpServer } from '../src/server.mjs';
+
+await startThemeMcpServer().catch((error) => {
+  console.error(error instanceof Error ? error.message : 'Failed to start Shoppex MCP server.');
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@shoppexio/mcp-theme-server",
+  "version": "0.1.0",
+  "description": "Shoppex MCP server for theme control plane operations",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ShoppexIO/shoppex.git",
+    "directory": "packages/mcp-theme-server"
+  },
+  "homepage": "https://docs.shoppex.io/themes/ai-workflows",
+  "bugs": {
+    "url": "https://github.com/ShoppexIO/shoppex/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "shoppex",
+    "mcp",
+    "theme",
+    "server",
+    "control-plane"
+  ],
+  "bin": {
+    "shoppex-mcp-theme-server": "./bin/shoppex-mcp-theme-server.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "bun test"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.28.0",
+    "@shoppexio/theme-control-client": "0.1.0"
+  }
+}

package/src/server.mjs

@@ -0,0 +1,296 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import * as z from 'zod/v4';
+import {
+  ShoppexThemeControlApiError,
+  ShoppexThemeControlClient,
+  resolveEnvThemeControlConfig,
+} from '@shoppexio/theme-control-client';
+
+function jsonContent(value) {
+  return {
+    content: [
+      {
+        type: 'text',
+        text: JSON.stringify(value, null, 2),
+      },
+    ],
+    structuredContent: value,
+  };
+}
+
+export function createThemeToolCatalog() {
+  return [
+    {
+      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),
+      },
+      execute: ({ theme_id }, client) => client.inspectTheme(theme_id),
+    },
+    {
+      name: 'theme.diff',
+      description: 'Show changes between the current draft and the latest published theme snapshot.',
+      inputSchema: {
+        theme_id: z.string().min(1),
+      },
+      execute: ({ theme_id }, client) => client.diffTheme(theme_id),
+    },
+    {
+      name: 'theme.read_file',
+      description: 'Read a single source file from a Shoppex theme.',
+      inputSchema: {
+        theme_id: z.string().min(1),
+        file_path: z.string().min(1),
+      },
+      execute: ({ theme_id, file_path }, client) => client.readThemeFile(theme_id, file_path),
+    },
+    {
+      name: 'theme.search_files',
+      description: 'Search theme files by path or content.',
+      inputSchema: {
+        theme_id: z.string().min(1),
+        query: z.string().min(1),
+        limit: z.number().int().min(1).max(100).optional(),
+      },
+      execute: ({ theme_id, query, limit }, client) => client.searchThemeFiles(theme_id, query, limit),
+    },
+    {
+      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),
+        changes: z.array(z.object({
+          path: z.string().min(1),
+          content: z.string(),
+        })).min(1).max(50),
+        run_typecheck: z.boolean().optional(),
+        verification_strategy: z.enum(['quick', 'full']).optional(),
+      },
+      execute: ({ theme_id, changes, run_typecheck, verification_strategy }, client) => client.applyThemeChanges(theme_id, {
+        changes,
+        ...(run_typecheck !== undefined ? { runTypecheck: run_typecheck } : {}),
+        ...(verification_strategy ? { verificationStrategy: verification_strategy } : {}),
+      }),
+    },
+    {
+      name: 'theme.accept',
+      description: 'Accept an already generated draft patch from a dashboard-agent run.',
+      inputSchema: {
+        theme_id: z.string().min(1),
+        run_id: z.string().uuid(),
+        assistant_message_id: z.string().uuid(),
+        variant_id: z.string().min(1).optional(),
+      },
+      execute: ({ theme_id, run_id, assistant_message_id, variant_id }, client) => client.acceptThemeDraft(theme_id, {
+        runId: run_id,
+        assistantMessageId: assistant_message_id,
+        ...(variant_id ? { variantId: variant_id } : {}),
+      }),
+    },
+    {
+      name: 'theme.create',
+      description: 'Create a new theme scaffold from a Shoppex base theme.',
+      inputSchema: {
+        base: z.enum(['default', 'classic', 'nebula', 'pulse']),
+        name: z.string().min(1).optional(),
+        set_as_active: z.boolean().optional(),
+      },
+      execute: ({ base, name, set_as_active }, client) => client.createTheme({
+        base,
+        ...(name ? { name } : {}),
+        ...(set_as_active !== undefined ? { setAsActive: set_as_active } : {}),
+      }),
+    },
+    {
+      name: 'theme.create_section',
+      description: 'Scaffold a new theme section and wire it into theme.config.ts.',
+      inputSchema: {
+        theme_id: z.string().min(1),
+        name: z.string().min(1),
+        description: z.string().optional(),
+        section_key: z.string().optional(),
+      },
+      execute: ({ theme_id, name, description, section_key }, client) => client.createThemeSection(theme_id, {
+        name,
+        ...(description ? { description } : {}),
+        ...(section_key ? { sectionKey: section_key } : {}),
+      }),
+    },
+    {
+      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),
+        name: z.string().min(1),
+        description: z.string().optional(),
+        route_path: z.string().optional(),
+      },
+      execute: ({ theme_id, name, description, route_path }, client) => client.createThemePage(theme_id, {
+        name,
+        ...(description ? { description } : {}),
+        ...(route_path ? { routePath: route_path } : {}),
+      }),
+    },
+    {
+      name: 'theme.update_config',
+      description: 'Extend theme.config.ts with a new settings field.',
+      inputSchema: {
+        theme_id: z.string().min(1),
+        group: z.string().min(1),
+        key: z.string().min(1),
+        setting: z.record(z.string(), z.any()),
+      },
+      execute: ({ theme_id, group, key, setting }, client) => client.updateThemeConfig(theme_id, {
+        group,
+        key,
+        setting,
+      }),
+    },
+    {
+      name: 'theme.preview',
+      description: 'Start or reuse a live preview session for the current theme draft.',
+      inputSchema: {
+        theme_id: z.string().min(1),
+      },
+      execute: ({ theme_id }, client) => client.startThemePreview(theme_id),
+    },
+    {
+      name: 'theme.stop_preview',
+      description: 'Stop a running live preview session.',
+      inputSchema: {
+        theme_id: z.string().min(1),
+        session_id: z.string().min(1),
+      },
+      execute: ({ theme_id, session_id }, client) => client.stopThemePreview(theme_id, session_id),
+    },
+    {
+      name: 'theme.publish',
+      description: 'Queue a publish/deploy for the current accepted theme draft.',
+      inputSchema: {
+        theme_id: z.string().min(1),
+      },
+      execute: ({ theme_id }, client) => client.publishTheme(theme_id),
+    },
+    {
+      name: 'theme.publish_status',
+      description: 'Read the current publish job status.',
+      inputSchema: {
+        theme_id: z.string().min(1),
+        job_id: z.string().uuid(),
+      },
+      execute: ({ theme_id, job_id }, client) => client.getThemePublishStatus(theme_id, job_id),
+    },
+    {
+      name: 'theme.validate',
+      description: 'Run a validation-only build and optional typecheck without publishing.',
+      inputSchema: {
+        theme_id: z.string().min(1),
+        include_typecheck: z.boolean().optional(),
+      },
+      execute: ({ theme_id, include_typecheck }, client) => client.validateTheme(theme_id, {
+        ...(include_typecheck !== undefined ? { includeTypecheck: include_typecheck } : {}),
+      }),
+    },
+    {
+      name: 'theme.settings_get',
+      description: 'Read the current builder settings values for a theme.',
+      inputSchema: {
+        theme_id: z.string().min(1),
+      },
+      execute: ({ theme_id }, client) => client.getThemeSettings(theme_id),
+    },
+    {
+      name: 'theme.settings_update',
+      description: 'Update theme builder settings without editing source files directly.',
+      inputSchema: {
+        theme_id: z.string().min(1),
+        builder_settings: z.record(z.string(), z.any()),
+      },
+      execute: ({ theme_id, builder_settings }, client) => client.updateThemeSettings(theme_id, {
+        builder_settings,
+      }),
+    },
+    {
+      name: 'theme.backups',
+      description: 'List available theme backups for rollback.',
+      inputSchema: {
+        theme_id: z.string().min(1),
+      },
+      execute: ({ theme_id }, client) => client.listThemeBackups(theme_id),
+    },
+    {
+      name: 'theme.rollback',
+      description: 'Rollback a theme to a previous backup snapshot.',
+      inputSchema: {
+        theme_id: z.string().min(1),
+        backup_id: z.string().uuid(),
+      },
+      execute: ({ theme_id, backup_id }, client) => client.rollbackTheme(theme_id, backup_id),
+    },
+    {
+      name: 'theme.latest_run',
+      description: 'Read the latest dashboard-agent run metadata for a theme.',
+      inputSchema: {
+        theme_id: z.string().min(1),
+      },
+      execute: ({ theme_id }, client) => client.getLatestThemeRun(theme_id),
+    },
+  ];
+}
+
+export async function executeThemeTool(toolName, args, client) {
+  const tool = createThemeToolCatalog().find((entry) => entry.name === toolName);
+  if (!tool) {
+    throw new Error(`Unknown tool: ${toolName}`);
+  }
+
+  return tool.execute(args, client);
+}
+
+export function createThemeMcpServer(client = new ShoppexThemeControlClient(resolveEnvThemeControlConfig())) {
+  const server = new McpServer({
+    name: 'shoppex-themes',
+    version: '0.1.0',
+  });
+
+  for (const tool of createThemeToolCatalog()) {
+    server.registerTool(tool.name, {
+      description: tool.description,
+      inputSchema: tool.inputSchema,
+    }, async (args) => {
+      try {
+        const result = await tool.execute(args, client);
+        return jsonContent(result);
+      } catch (error) {
+        if (error instanceof ShoppexThemeControlApiError) {
+          return {
+            ...jsonContent({
+              error: error.message,
+              status: error.status,
+              payload: error.payload,
+            }),
+            isError: true,
+          };
+        }
+
+        return {
+          ...jsonContent({
+            error: error instanceof Error ? error.message : 'Unknown MCP server error.',
+          }),
+          isError: true,
+        };
+      }
+    });
+  }
+
+  return server;
+}
+
+export async function startThemeMcpServer() {
+  const server = createThemeMcpServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  return server;
+}

package/src/server.test.mjs

@@ -0,0 +1,45 @@
+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',
+      },
+    });
+  });
+});