@symbo.ls/mcp-server 3.6.8 → 3.7.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@symbo.ls/mcp-server",
-  "version": "3.6.8",
+  "version": "3.7.3",
   "description": "HTTP proxy for the Symbols MCP server — runs as a Cloudflare Worker",
   "type": "module",
   "main": "index.js",

package/src/mcp-handler.js

@@ -33,15 +33,33 @@ function listSkillFiles() {
 const V2_PATTERNS = [
   [/\bextend\s*:/g, "v2 syntax: use 'extends' (plural) instead of 'extend'"],
   [/\bchildExtend\s*:/g, "v2 syntax: use 'childExtends' (plural) instead of 'childExtend'"],
-  [/\bon\s*:\s*\{/g, 'v2 syntax: flatten event handlers with onX prefix (e.g. onClick) instead of on: {} wrapper'],
-  [/\bprops\s*:\s*\{(?!\s*\})/g, 'v2 syntax: flatten props directly on the component instead of props: {} wrapper'],
+  [
+    /\bon\s*:\s*\{/g,
+    'v2 syntax: flatten event handlers with onX prefix (e.g. onClick) instead of on: {} wrapper',
+  ],
+  [
+    /\bprops\s*:\s*\{(?!\s*\})/g,
+    'v2 syntax: flatten props directly on the component instead of props: {} wrapper',
+  ],
 ];
 
 const RULE_CHECKS = [
-  [/\bimport\s+.*\bfrom\s+['"]\.\//, 'FORBIDDEN: No imports between project files — reference components by PascalCase key name'],
-  [/\bexport\s+default\s+\{/, 'Components should use named exports (export const Name = {}), not default exports'],
-  [/\bfunction\s+\w+\s*\(.*\)\s*\{[\s\S]*?return\s*\{/, 'Components must be plain objects, not functions that return objects'],
-  [/(?:padding|margin|gap|width|height)\s*:\s*['"]?\d+px/, 'Use design tokens (A, B, C) instead of hardcoded pixel values'],
+  [
+    /\bimport\s+.*\bfrom\s+['"]\.\//,
+    'FORBIDDEN: No imports between project files — reference components by PascalCase key name',
+  ],
+  [
+    /\bexport\s+default\s+\{/,
+    'Components should use named exports (export const Name = {}), not default exports',
+  ],
+  [
+    /\bfunction\s+\w+\s*\(.*\)\s*\{[\s\S]*?return\s*\{/,
+    'Components must be plain objects, not functions that return objects',
+  ],
+  [
+    /(?:padding|margin|gap|width|height)\s*:\s*['"]?\d+px/,
+    'Use design tokens (A, B, C) instead of hardcoded pixel values',
+  ],
 ];
 
 function auditCode(code) {
@@ -194,9 +212,187 @@ const TOOLS = [
       required: ['component_code'],
     },
   },
+  {
+    name: 'login',
+    description:
+      'Log in to the Symbols platform with email and password. Returns a JWT token for use with publish and push tools.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        email: {
+          type: 'string',
+          description: 'Symbols account email address',
+        },
+        password: {
+          type: 'string',
+          description: 'Symbols account password',
+        },
+      },
+      required: ['email', 'password'],
+    },
+  },
+  {
+    name: 'publish',
+    description:
+      'Publish a version of a Symbols project to the platform. Requires authentication via token or api_key.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        project: {
+          type: 'string',
+          description: 'Project ID (MongoDB ObjectId) or project key (pr_xxxx)',
+        },
+        token: {
+          type: 'string',
+          description: 'JWT access token from login or ~/.smblsrc',
+        },
+        api_key: {
+          type: 'string',
+          description:
+            'API key (sk_live_...) from project integration settings. Alternative to token.',
+        },
+        version: {
+          type: 'string',
+          description: 'Version string or version ID to publish. Leave empty for latest.',
+          default: '',
+        },
+        branch: {
+          type: 'string',
+          description: 'Branch to publish from',
+          default: 'main',
+        },
+      },
+      required: ['project'],
+    },
+  },
+  {
+    name: 'push',
+    description:
+      'Push/deploy a Symbols project to a specific environment. Requires authentication via token or api_key.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        project: {
+          type: 'string',
+          description: 'Project ID (MongoDB ObjectId) or project key (pr_xxxx)',
+        },
+        token: {
+          type: 'string',
+          description: 'JWT access token from login or ~/.smblsrc',
+        },
+        api_key: {
+          type: 'string',
+          description:
+            'API key (sk_live_...) from project integration settings. Alternative to token.',
+        },
+        environment: {
+          type: 'string',
+          description: 'Target environment key (e.g. "production", "staging", "dev")',
+          default: 'production',
+        },
+        mode: {
+          type: 'string',
+          description:
+            'Deploy mode — "latest" (newest from branch), "published" (current published version), "version" (specific version), or "branch" (track a branch)',
+          default: 'published',
+        },
+        version: {
+          type: 'string',
+          description: 'Required when mode is "version" — the version string or ID to deploy',
+          default: '',
+        },
+        branch: {
+          type: 'string',
+          description: 'Branch to deploy from when mode is "latest" or "branch"',
+          default: 'main',
+        },
+      },
+      required: ['project'],
+    },
+  },
+  {
+    name: 'detect_environment',
+    description:
+      'Detect what type of Symbols environment the user is working in (local project, CDN, JSON runtime, or remote server) based on project indicators, and return the appropriate setup guide and code format.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        has_symbols_json: {
+          type: 'boolean',
+          description: 'Whether symbols.json exists in the project root',
+        },
+        has_symbols_dir: {
+          type: 'boolean',
+          description: 'Whether a symbols/ directory exists with components/, pages/, etc.',
+        },
+        has_package_json: {
+          type: 'boolean',
+          description: 'Whether package.json exists with smbls dependency',
+        },
+        has_cdn_import: {
+          type: 'boolean',
+          description:
+            'Whether HTML files contain CDN imports (esm.sh/smbls, cdn.jsdelivr.net/npm/smbls, etc.)',
+        },
+        has_iife_script: {
+          type: 'boolean',
+          description: 'Whether HTML files use <script src="...smbls"> (IIFE global)',
+        },
+        has_json_data: {
+          type: 'boolean',
+          description: 'Whether the project uses frank-generated JSON data files',
+        },
+        has_mermaid_config: {
+          type: 'boolean',
+          description:
+            'Whether mermaid/wrangler config or GATEWAY_URL/JSON_PATH env vars are present',
+        },
+        file_list: {
+          type: 'string',
+          description:
+            'Comma-separated list of key files in the project root (e.g. "index.html,package.json,symbols.json")',
+        },
+      },
+    },
+  },
 ];
 
-function callTool(name, args = {}) {
+const API_BASE = 'https://api.symbols.app';
+
+const AUTH_HELP = `To authenticate, provide one of:
+- **token**: JWT from \`smbls login\` (stored in ~/.smblsrc) or env var SYMBOLS_TOKEN
+- **api_key**: API key (sk_live_...) from your project's integration settings
+
+To get a token:
+1. Run \`smbls login\` in your terminal, or
+2. Use the \`login\` tool with your email and password
+
+Your project can be identified by either:
+- **project**: MongoDB ObjectId (from project settings or symbols.json)
+- **project**: Project key (pr_xxxx, found in symbols.json or project URL)`;
+
+function authHeader(token, apiKey) {
+  if (apiKey) return { 'Authorization': `ApiKey ${apiKey}`, 'Content-Type': 'application/json' };
+  if (token) return { 'Authorization': `Bearer ${token}`, 'Content-Type': 'application/json' };
+  return null;
+}
+
+async function apiRequest(method, path, { token, api_key, body } = {}) {
+  const headers = authHeader(token, api_key);
+  if (!headers) return { success: false, error: 'No credentials provided', message: AUTH_HELP };
+  const resp = await fetch(`${API_BASE}${path}`, {
+    method,
+    headers,
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  try {
+    return await resp.json();
+  } catch {
+    return { success: false, error: `HTTP ${resp.status}`, message: await resp.text() };
+  }
+}
+
+async function callTool(name, args = {}) {
   if (name === 'get_project_rules') {
     return readSkill('RULES.md');
   }
@@ -237,26 +433,52 @@ function callTool(name, args = {}) {
   if (name === 'generate_component') {
     const desc = args.description || '';
     const compName = args.component_name || 'MyComponent';
-    const context = readSkills('RULES.md', 'COMPONENTS.md', 'SYNTAX.md', 'COOKBOOK.md', 'DEFAULT_LIBRARY.md');
+    const context = readSkills(
+      'RULES.md',
+      'COMPONENTS.md',
+      'SYNTAX.md',
+      'COOKBOOK.md',
+      'DEFAULT_LIBRARY.md',
+    );
     return `# Generate Component: ${compName}\n\n## Description\n${desc}\n\n## Requirements\n- Named export: \`export const ${compName} = { ... }\`\n- DOMQL v3 syntax only (extends, childExtends, flattened props, onX events)\n- Use design tokens for spacing (A, B, C), colors from theme\n- NO imports between files — PascalCase keys auto-extend registered components\n- Include responsive breakpoints where appropriate (@tabletS, @mobileL)\n- Use the default library components (Button, Avatar, Icon, Field, etc.) via extends\n- Follow modern UI/UX: visual hierarchy, confident typography, minimal cognitive load\n\n## Context — Rules, Syntax & Examples\n\n${context}`;
   }
 
   if (name === 'generate_page') {
     const desc = args.description || '';
     const pageName = args.page_name || 'home';
-    const context = readSkills('RULES.md', 'PROJECT_STRUCTURE.md', 'PATTERNS.md', 'SNIPPETS.md', 'DEFAULT_LIBRARY.md', 'COMPONENTS.md');
+    const context = readSkills(
+      'RULES.md',
+      'PROJECT_STRUCTURE.md',
+      'PATTERNS.md',
+      'SNIPPETS.md',
+      'DEFAULT_LIBRARY.md',
+      'COMPONENTS.md',
+    );
     return `# Generate Page: ${pageName}\n\n## Description\n${desc}\n\n## Requirements\n- Export as: \`export const ${pageName} = { ... }\`\n- Page is a plain object composing components\n- Add to pages/index.js route map: \`'/${pageName}': ${pageName}\`\n- Use components by PascalCase key (Header, Footer, Hero, etc.)\n- Use design tokens — no hardcoded pixels\n- Include responsive layout adjustments\n\n## Context — Rules, Structure, Patterns & Snippets\n\n${context}`;
   }
 
   if (name === 'convert_react') {
     const source = args.source_code || '';
-    const context = readSkills('RULES.md', 'MIGRATION.md', 'SYNTAX.md', 'COMPONENTS.md', 'LEARNINGS.md');
+    const context = readSkills(
+      'RULES.md',
+      'MIGRATION.md',
+      'SYNTAX.md',
+      'COMPONENTS.md',
+      'LEARNINGS.md',
+    );
     return `# Convert React → Symbols DOMQL v3\n\n## Source Code to Convert\n\`\`\`jsx\n${source}\n\`\`\`\n\n## Conversion Rules\n- Function/class components → plain object exports\n- JSX → nested object children (PascalCase keys auto-extend)\n- import/export between files → REMOVE (reference by key name)\n- useState → state: { key: val } + s.update({ key: newVal })\n- useEffect → onRender (mount), onStateUpdate (deps)\n- props → flattened directly on component (no props wrapper)\n- onClick={handler} → onClick: (event, el, state) => {}\n- className → use design tokens and theme directly\n- map() → children: (el, s) => s.items, childExtends, childProps\n- conditional rendering → if: (el, s) => boolean\n- CSS modules/styled → CSS-in-props with design tokens\n- React.Fragment → not needed, just nest children\n\n## Context — Migration Guide, Syntax & Rules\n\n${context}`;
   }
 
   if (name === 'convert_html') {
     const source = args.source_code || '';
-    const context = readSkills('RULES.md', 'SYNTAX.md', 'COMPONENTS.md', 'DESIGN_SYSTEM.md', 'SNIPPETS.md', 'LEARNINGS.md');
+    const context = readSkills(
+      'RULES.md',
+      'SYNTAX.md',
+      'COMPONENTS.md',
+      'DESIGN_SYSTEM.md',
+      'SNIPPETS.md',
+      'LEARNINGS.md',
+    );
     return `# Convert HTML → Symbols DOMQL v3\n\n## Source Code to Convert\n\`\`\`html\n${source}\n\`\`\`\n\n## Conversion Rules\n- <div> → Box, Flex, or Grid (based on layout purpose)\n- <span>, <p>, <h1>-<h6> → Text, P, H with tag property\n- <a> → Link (has built-in SPA router)\n- <button> → Button (has icon/text support)\n- <input> → Input, Radio, Checkbox (based on type)\n- <img> → Img\n- <form> → Form (extends Box with tag: 'form')\n- <ul>/<ol> + <li> → children array with childExtends\n- CSS classes → flatten as CSS-in-props on the component\n- CSS px values → design tokens (16px → 'A', 26px → 'B', 42px → 'C')\n- CSS colors → theme color tokens\n- media queries → @tabletS, @mobileL, @screenS breakpoints\n- id/class attributes → not needed (use key names and themes)\n- inline styles → flatten as component properties\n- <style> blocks → distribute to component-level properties\n\n## Context — Syntax, Components & Design System\n\n${context}`;
   }
 
@@ -287,6 +509,179 @@ function callTool(name, args = {}) {
     return output;
   }
 
+  if (name === 'login') {
+    const { email, password } = args;
+    if (!email || !password) return 'Error: email and password are required.';
+    const resp = await fetch(`${API_BASE}/core/auth/login`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ email, password }),
+    });
+    let result;
+    try {
+      result = await resp.json();
+    } catch {
+      return `Login failed: HTTP ${resp.status}`;
+    }
+    if (result.success) {
+      const data = result.data || {};
+      const tokens = data.tokens || {};
+      const user = data.user || {};
+      return `Logged in as ${user.name || user.email || 'unknown'}.\nToken: ${tokens.accessToken || ''}\nExpires: ${(tokens.accessTokenExp || {}).expiresAt || 'unknown'}\n\nUse this token with the \`publish\` and \`push\` tools.`;
+    }
+    return `Login failed: ${result.error || result.message || 'Unknown error'}`;
+  }
+
+  if (name === 'publish') {
+    const { project, token, api_key, version, branch = 'main' } = args;
+    if (!project) return 'Error: project (ID or key) is required.';
+    if (!token && !api_key) return `Authentication required.\n\n${AUTH_HELP}`;
+    const body = { branch };
+    if (version) body.version = version;
+    const result = await apiRequest('POST', `/${project}/publish`, { token, api_key, body });
+    if (result.success) {
+      const data = result.data || {};
+      return `Published successfully.\nVersion: ${data.value || data.id || 'unknown'}`;
+    }
+    return `Publish failed: ${result.error || 'Unknown error'}\n${result.message || ''}`;
+  }
+
+  if (name === 'push') {
+    const {
+      project,
+      token,
+      api_key,
+      environment = 'production',
+      mode = 'published',
+      version,
+      branch = 'main',
+    } = args;
+    if (!project) return 'Error: project (ID or key) is required.';
+    if (!token && !api_key) return `Authentication required.\n\n${AUTH_HELP}`;
+    const body = { mode, branch };
+    if (version) body.version = version;
+    const result = await apiRequest('POST', `/${project}/environments/${environment}/publish`, {
+      token,
+      api_key,
+      body,
+    });
+    if (result.success) {
+      const data = result.data || {};
+      const config = data.config || {};
+      return `Pushed to ${data.key || environment} successfully.\nMode: ${config.mode || mode}\nVersion: ${config.version || 'latest'}\nBranch: ${config.branch || branch}`;
+    }
+    return `Push failed: ${result.error || 'Unknown error'}\n${result.message || ''}`;
+  }
+
+  if (name === 'detect_environment') {
+    const {
+      has_symbols_json,
+      has_symbols_dir,
+      has_package_json,
+      has_cdn_import,
+      has_iife_script,
+      has_json_data,
+      has_mermaid_config,
+      file_list,
+    } = args;
+
+    // Detect environment type
+    let envType = 'unknown';
+    let confidence = 'low';
+
+    if (has_mermaid_config) {
+      envType = 'remote_server';
+      confidence = 'high';
+    } else if (has_json_data) {
+      envType = 'json_runtime';
+      confidence = 'high';
+    } else if (has_symbols_json && has_symbols_dir) {
+      envType = 'local_project';
+      confidence = 'high';
+    } else if (has_symbols_dir || (has_package_json && has_symbols_json)) {
+      envType = 'local_project';
+      confidence = 'medium';
+    } else if (has_cdn_import || has_iife_script) {
+      envType = 'cdn';
+      confidence = 'high';
+    } else if (has_package_json) {
+      envType = 'local_project';
+      confidence = 'low';
+    } else if (file_list) {
+      const files = file_list.toLowerCase();
+      if (
+        files.includes('index.html') &&
+        !files.includes('package.json') &&
+        !files.includes('symbols.json')
+      ) {
+        envType = 'cdn';
+        confidence = 'medium';
+      }
+    }
+
+    // Build response with appropriate guide
+    const fullGuide = readSkill('RUNNING_APPS.md');
+    let output = `# Environment Detection\n\n**Detected: ${envType}** (confidence: ${confidence})\n\n`;
+
+    if (envType === 'local_project') {
+      output += `## Your Environment: Local Project\n\n`;
+      output += `You're working in a standard Symbols project with file-based structure.\n\n`;
+      output += `### Code Format\n`;
+      output += `- Components: \`export const Name = { extends: 'Flex', ... }\` in \`components/\`\n`;
+      output += `- Pages: \`export const pageName = { extends: 'Page', ... }\` in \`pages/\`\n`;
+      output += `- State: \`export default { key: value }\` in \`state.js\`\n`;
+      output += `- Functions: \`export const fn = function() {}\` in \`functions/\`\n`;
+      output += `- No imports between files (except pages/index.js)\n\n`;
+      output += `### Commands\n`;
+      output += `\`\`\`bash\nnpm start          # dev server\nsmbls build        # production build\nsmbls push         # deploy to platform\nsmbls deploy       # deploy to provider\n\`\`\`\n\n`;
+      const structureGuide = readSkill('PROJECT_STRUCTURE.md');
+      output += `### Full Project Structure Reference\n\n${structureGuide}`;
+    } else if (envType === 'cdn') {
+      output += `## Your Environment: CDN (Browser-Only)\n\n`;
+      output += `You're running Symbols directly in the browser via CDN import.\n\n`;
+      output += `### Code Format\n`;
+      output += `- Single HTML file with \`<script type="module">\`\n`;
+      output += `- Import: \`import { create } from 'https://esm.sh/smbls'\`\n`;
+      output += `- Define app as inline object tree\n`;
+      output += `- Mount: \`create(App, { designSystem, components, functions, state })\`\n`;
+      output += `- Components defined as JS variables (no file-based registry)\n\n`;
+      output += `### Limitations\n`;
+      output += `- No file-based routing (use tab/view switching)\n`;
+      output += `- No SSR\n`;
+      output += `- \`childExtends: 'Name'\` needs components passed to \`create()\`\n\n`;
+      const cdnGuide = readSkill('RUNNING_APPS.md');
+      output += `### Full CDN Reference\n\n${cdnGuide}`;
+    } else if (envType === 'json_runtime') {
+      output += `## Your Environment: JSON Runtime (Frank)\n\n`;
+      output += `You're running Symbols from serialized JSON project data.\n\n`;
+      output += `### Code Format\n`;
+      output += `- Project data is a JSON object with components, pages, designSystem, state, functions\n`;
+      output += `- Functions are serialized as strings\n`;
+      output += `- Convert with: \`smbls frank to-json ./symbols\` or \`toJSON({ entry: './symbols' })\`\n`;
+      output += `- Reverse with: \`smbls frank to-fs data.json -o ./output\` or \`toFS(data, './output')\`\n`;
+      output += `- Can be loaded by Mermaid server via JSON_PATH env var\n\n`;
+      output += `### Full Reference\n\n${fullGuide}`;
+    } else if (envType === 'remote_server') {
+      output += `## Your Environment: Remote Symbols Server (Mermaid)\n\n`;
+      output += `You're working with the Mermaid rendering server for hosted Symbols apps.\n\n`;
+      output += `### URL Patterns\n`;
+      output += `- Production: \`https://app.user.preview.symbols.app/\`\n`;
+      output += `- Development: \`https://app.user.preview.dev.symbols.app/\`\n`;
+      output += `- Staging: \`https://app.user.preview.staging.symbols.app/\`\n`;
+      output += `- Legacy: \`https://app.symbo.ls/\`\n`;
+      output += `- Custom domains supported\n\n`;
+      output += `### Deployment\n`;
+      output += `\`\`\`bash\nsmbls push    # deploy to Symbols platform\n\`\`\`\n\n`;
+      output += `### Full Reference\n\n${fullGuide}`;
+    } else {
+      output += `## Could Not Determine Environment\n\n`;
+      output += `Provide more details about your project files to get specific guidance.\n\n`;
+      output += `### All 4 Ways to Run Symbols Apps\n\n${fullGuide}`;
+    }
+
+    return output;
+  }
+
   throw new Error(`Unknown tool: ${name}`);
 }
 
@@ -310,7 +705,16 @@ const SKILL_RESOURCES = {
   'symbols://skills/cookbook': 'COOKBOOK.md',
   'symbols://skills/snippets': 'SNIPPETS.md',
   'symbols://skills/default-library': 'DEFAULT_LIBRARY.md',
+  'symbols://skills/default-components': 'DEFAULT_COMPONENTS.md',
   'symbols://skills/learnings': 'LEARNINGS.md',
+  'symbols://skills/running-apps': 'RUNNING_APPS.md',
+  'symbols://skills/brand-identity': 'BRAND_IDENTITY.md',
+  'symbols://skills/design-critique': 'DESIGN_CRITIQUE.md',
+  'symbols://skills/design-system-architect': 'DESIGN_SYSTEM_ARCHITECT.md',
+  'symbols://skills/design-trend': 'DESIGN_TREND.md',
+  'symbols://skills/figma-matching': 'FIGMA_MATCHING.md',
+  'symbols://skills/marketing-assets': 'MARKETING_ASSETS.md',
+  'symbols://skills/presentation': 'PRESENTATION.md',
 };
 
 function listResources() {
@@ -381,9 +785,9 @@ const PROMPTS = [
 // MCP JSON-RPC handler
 // ---------------------------------------------------------------------------
 
-const SERVER_INFO = { name: 'Symbols MCP', version: '1.1.0' };
+const SERVER_INFO = { name: 'Symbols MCP', version: '1.1.1' };
 
-export function handleJsonRpc(req) {
+export async function handleJsonRpc(req) {
   const { method, params, id } = req;
 
   if (method === 'initialize') {
@@ -408,7 +812,7 @@ export function handleJsonRpc(req) {
   if (method === 'tools/call') {
     const { name, arguments: args = {} } = params || {};
     try {
-      const text = callTool(name, args);
+      const text = await callTool(name, args);
       return { jsonrpc: '2.0', id, result: { content: [{ type: 'text', text }] } };
     } catch (e) {
       return {

package/src/worker-handler.js

@@ -66,14 +66,14 @@ function isNotificationOrResponse(msg) {
   return false;
 }
 
-function handleMcpPost(request, body) {
+async function handleMcpPost(request, body) {
   // Notifications and responses get 202 Accepted
   if (isNotificationOrResponse(body)) {
     return new Response(null, { status: 202, headers: CORS_HEADERS });
   }
 
   // Handle JSON-RPC request
-  const result = handleJsonRpc(body);
+  const result = await handleJsonRpc(body);
   if (result === null) {
     return new Response(null, { status: 202, headers: CORS_HEADERS });
   }
@@ -117,7 +117,7 @@ export async function handleRequest(request) {
       }
       return json({
         name: 'Symbols MCP',
-        version: '1.0.11',
+        version: '1.1.1',
         description: 'MCP server for Symbols.app — documentation search and framework reference',
         endpoints: {
           mcp: 'POST / (Streamable HTTP transport)',
@@ -166,7 +166,7 @@ export async function handleRequest(request) {
       return json({ error: 'Invalid JSON body' }, 400);
     }
     try {
-      const result = callTool(toolName, args);
+      const result = await callTool(toolName, args);
       return json({ content: [{ type: 'text', text: result }] });
     } catch (e) {
       return json({ error: e.message }, 404);