@symbo.ls/mcp-server 3.6.7 → 3.7.0

package/package.json

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

package/src/mcp-handler.js

@@ -15,10 +15,88 @@ function readSkill(filename) {
   return skills[filename] || `Skill '${filename}' not found`;
 }
 
+function readSkills(...filenames) {
+  return filenames
+    .map((f) => skills[f])
+    .filter(Boolean)
+    .join('\n\n---\n\n');
+}
+
 function listSkillFiles() {
   return Object.keys(skills);
 }
 
+// ---------------------------------------------------------------------------
+// Audit helpers (deterministic rule checking)
+// ---------------------------------------------------------------------------
+
+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',
+  ],
+];
+
+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',
+  ],
+];
+
+function auditCode(code) {
+  const violations = [];
+  const warnings = [];
+
+  for (const [pattern, message] of V2_PATTERNS) {
+    const regex = new RegExp(pattern.source, pattern.flags);
+    let match;
+    while ((match = regex.exec(code)) !== null) {
+      const line = code.slice(0, match.index).split('\n').length;
+      violations.push({ line, severity: 'error', message });
+    }
+  }
+
+  for (const [pattern, message] of RULE_CHECKS) {
+    const regex = new RegExp(pattern.source, pattern.flags);
+    let match;
+    while ((match = regex.exec(code)) !== null) {
+      const line = code.slice(0, match.index).split('\n').length;
+      const level = message.includes('FORBIDDEN') ? 'error' : 'warning';
+      (level === 'error' ? violations : warnings).push({ line, severity: level, message });
+    }
+  }
+
+  const totalIssues = violations.length + warnings.length;
+  const score = Math.max(1, 10 - totalIssues);
+
+  return {
+    passed: violations.length === 0,
+    score,
+    violations,
+    warnings,
+    summary: `${violations.length} errors, ${warnings.length} warnings — compliance score: ${score}/10`,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Tools
 // ---------------------------------------------------------------------------
@@ -49,6 +127,136 @@ const TOOLS = [
       required: ['query'],
     },
   },
+  {
+    name: 'generate_component',
+    description:
+      'Generate a Symbols.app DOMQL v3 component from a description. Returns rules, syntax, component catalog, cookbook examples, and default library reference as context.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        description: {
+          type: 'string',
+          description: 'What the component should do and look like',
+        },
+        component_name: {
+          type: 'string',
+          description: 'PascalCase name for the component',
+          default: 'MyComponent',
+        },
+      },
+      required: ['description'],
+    },
+  },
+  {
+    name: 'generate_page',
+    description:
+      'Generate a Symbols.app page with routing integration. Returns rules, project structure, patterns, snippets, and default library reference as context.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        description: {
+          type: 'string',
+          description: 'What the page should contain and do',
+        },
+        page_name: {
+          type: 'string',
+          description: 'camelCase name for the page',
+          default: 'home',
+        },
+      },
+      required: ['description'],
+    },
+  },
+  {
+    name: 'convert_react',
+    description:
+      'Convert React/JSX code to Symbols.app DOMQL v3. Returns migration rules, syntax reference, and examples as context.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        source_code: {
+          type: 'string',
+          description: 'The React/JSX source code to convert',
+        },
+      },
+      required: ['source_code'],
+    },
+  },
+  {
+    name: 'convert_html',
+    description:
+      'Convert raw HTML/CSS to Symbols.app DOMQL v3 components. Returns component catalog, syntax reference, and design tokens as context.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        source_code: {
+          type: 'string',
+          description: 'The HTML/CSS source code to convert',
+        },
+      },
+      required: ['source_code'],
+    },
+  },
+  {
+    name: 'audit_component',
+    description:
+      'Audit a Symbols/DOMQL component for v3 compliance and best practices. Returns a structured report with violations, warnings, and compliance score.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        component_code: {
+          type: 'string',
+          description: 'The JavaScript component code to audit',
+        },
+      },
+      required: ['component_code'],
+    },
+  },
+  {
+    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 = {}) {
@@ -89,6 +297,194 @@ function callTool(name, args = {}) {
       : `No results found for '${query}'. Try a different search term.`;
   }
 
+  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',
+    );
+    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',
+    );
+    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',
+    );
+    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',
+    );
+    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}`;
+  }
+
+  if (name === 'audit_component') {
+    const code = args.component_code || '';
+    const result = auditCode(code);
+    const rulesContext = readSkill('AUDIT.md');
+
+    let output = `# Audit Report\n\n## Summary\n${result.summary}\nPassed: ${result.passed ? 'Yes' : 'No'}\n\n## Violations (Errors)\n`;
+    if (result.violations.length) {
+      for (const v of result.violations) {
+        output += `- **Line ${v.line}**: ${v.message}\n`;
+      }
+    } else {
+      output += 'No violations found.\n';
+    }
+
+    output += '\n## Warnings\n';
+    if (result.warnings.length) {
+      for (const w of result.warnings) {
+        output += `- **Line ${w.line}**: ${w.message}\n`;
+      }
+    } else {
+      output += 'No warnings.\n';
+    }
+
+    output += `\n## Detailed Rules Reference\n\n${rulesContext}`;
+    return output;
+  }
+
+  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}`);
 }
 
@@ -108,6 +504,20 @@ const SKILL_RESOURCES = {
   'symbols://skills/audit': 'AUDIT.md',
   'symbols://skills/design-to-code': 'DESIGN_TO_CODE.md',
   'symbols://skills/seo-metadata': 'SEO-METADATA.md',
+  'symbols://skills/ssr-brender': 'SSR-BRENDER.md',
+  '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() {
@@ -162,13 +572,23 @@ const PROMPTS = [
     description: 'Prompt template for reviewing Symbols/DOMQL code.',
     arguments: [],
   },
+  {
+    name: 'symbols_convert_html_prompt',
+    description: 'Prompt template for converting HTML to Symbols.app components.',
+    arguments: [],
+  },
+  {
+    name: 'symbols_design_review_prompt',
+    description: 'Prompt template for visual/design audit against the design system.',
+    arguments: [],
+  },
 ];
 
 // ---------------------------------------------------------------------------
 // MCP JSON-RPC handler
 // ---------------------------------------------------------------------------
 
-const SERVER_INFO = { name: 'Symbols MCP', version: '1.0.10' };
+const SERVER_INFO = { name: 'Symbols MCP', version: '1.1.1' };
 
 export function handleJsonRpc(req) {
   const { method, params, id } = req;

package/src/worker-handler.js

@@ -21,7 +21,8 @@ import {
 const CORS_HEADERS = {
   'Access-Control-Allow-Origin': '*',
   'Access-Control-Allow-Methods': 'GET, POST, DELETE, OPTIONS',
-  'Access-Control-Allow-Headers': 'Content-Type, Accept, Authorization, Mcp-Session-Id, MCP-Protocol-Version',
+  'Access-Control-Allow-Headers':
+    'Content-Type, Accept, Authorization, Mcp-Session-Id, MCP-Protocol-Version',
   'Access-Control-Expose-Headers': 'Mcp-Session-Id',
 };
 
@@ -56,7 +57,7 @@ function sseResponse(data, extraHeaders = {}) {
 function generateSessionId() {
   const bytes = new Uint8Array(16);
   crypto.getRandomValues(bytes);
-  return Array.from(bytes, b => b.toString(16).padStart(2, '0')).join('');
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
 }
 
 function isNotificationOrResponse(msg) {
@@ -116,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)',