@symbo.ls/mcp-server 3.6.8 → 3.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@symbo.ls/mcp-server",
-  "version": "3.6.8",
+  "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

@@ -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,6 +212,51 @@ const TOOLS = [
       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 = {}) {
@@ -237,26 +300,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 +376,115 @@ function callTool(name, args = {}) {
     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}`);
 }
 
@@ -310,7 +508,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,7 +588,7 @@ 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) {
   const { method, params, id } = req;

package/src/worker-handler.js

@@ -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)',