@symbo.ls/mcp-server 3.6.6 → 3.6.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@symbo.ls/mcp-server",
-  "version": "3.6.6",
+  "version": "3.6.8",
   "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,70 @@ 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 +109,91 @@ 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'],
+    },
+  },
 ];
 
 function callTool(name, args = {}) {
@@ -89,6 +234,59 @@ 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;
+  }
+
   throw new Error(`Unknown tool: ${name}`);
 }
 
@@ -108,6 +306,11 @@ 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/learnings': 'LEARNINGS.md',
 };
 
 function listResources() {
@@ -162,13 +365,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.0' };
 
 export function handleJsonRpc(req) {
   const { method, params, id } = req;

package/src/worker-handler.js

@@ -1,9 +1,12 @@
 /**
- * Cloudflare Worker request handler for Symbols MCP HTTP proxy.
+ * Cloudflare Worker request handler for Symbols MCP — Streamable HTTP transport.
  *
- * Exposes the MCP server over HTTP with two interfaces:
- *   1. MCP JSON-RPC protocol (POST /mcp)
- *   2. REST-style endpoints for direct access
+ * MCP endpoint is root (/):
+ *   - POST / — JSON-RPC requests/notifications/responses
+ *   - GET  / — SSE stream (returns 405, not needed for stateless server)
+ *   - DELETE / — terminate session (returns 405)
+ *
+ * Also exposes REST endpoints for direct access.
  */
 
 import {
@@ -17,15 +20,77 @@ import {
 
 const CORS_HEADERS = {
   'Access-Control-Allow-Origin': '*',
-  'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
-  'Access-Control-Allow-Headers': 'Content-Type, Authorization',
+  'Access-Control-Allow-Methods': 'GET, POST, DELETE, OPTIONS',
+  'Access-Control-Allow-Headers':
+    'Content-Type, Accept, Authorization, Mcp-Session-Id, MCP-Protocol-Version',
+  'Access-Control-Expose-Headers': 'Mcp-Session-Id',
 };
 
-function json(data, status = 200) {
+function json(data, status = 200, extraHeaders = {}) {
   return new Response(JSON.stringify(data), {
     status,
-    headers: { 'Content-Type': 'application/json', ...CORS_HEADERS },
+    headers: { 'Content-Type': 'application/json', ...CORS_HEADERS, ...extraHeaders },
+  });
+}
+
+function sseResponse(data, extraHeaders = {}) {
+  const encoder = new TextEncoder();
+  const stream = new ReadableStream({
+    start(controller) {
+      controller.enqueue(encoder.encode(`event: message\ndata: ${JSON.stringify(data)}\n\n`));
+      controller.close();
+    },
   });
+
+  return new Response(stream, {
+    status: 200,
+    headers: {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+      'Connection': 'keep-alive',
+      ...CORS_HEADERS,
+      ...extraHeaders,
+    },
+  });
+}
+
+function generateSessionId() {
+  const bytes = new Uint8Array(16);
+  crypto.getRandomValues(bytes);
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, '0')).join('');
+}
+
+function isNotificationOrResponse(msg) {
+  if (msg.method && msg.id === undefined) return true;
+  if (!msg.method && (msg.result !== undefined || msg.error !== undefined)) return true;
+  return false;
+}
+
+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);
+  if (result === null) {
+    return new Response(null, { status: 202, headers: CORS_HEADERS });
+  }
+
+  // For initialize, generate and attach session ID
+  const extraHeaders = {};
+  if (body.method === 'initialize') {
+    extraHeaders['Mcp-Session-Id'] = generateSessionId();
+  }
+
+  // Check if client accepts SSE
+  const accept = request.headers.get('Accept') || '';
+  if (accept.includes('text/event-stream')) {
+    return sseResponse(result, extraHeaders);
+  }
+
+  return json(result, 200, extraHeaders);
 }
 
 export async function handleRequest(request) {
@@ -37,34 +102,60 @@ export async function handleRequest(request) {
     return new Response(null, { status: 204, headers: CORS_HEADERS });
   }
 
-  // ── MCP JSON-RPC endpoint ──────────────────────────────────────────────
-  if (pathname === '/mcp' && request.method === 'POST') {
-    let body;
-    try {
-      body = await request.json();
-    } catch {
-      return json({ error: 'Invalid JSON body' }, 400);
+  // OAuth metadata discovery — no auth required, return 404
+  if (pathname === '/.well-known/oauth-authorization-server') {
+    return new Response('Not Found', { status: 404 });
+  }
+
+  // ── MCP Streamable HTTP transport on root (/) and /mcp ─────────────
+
+  if (pathname === '/' || pathname === '' || pathname === '/mcp') {
+    if (request.method === 'GET') {
+      const accept = request.headers.get('Accept') || '';
+      if (accept.includes('text/event-stream')) {
+        return new Response('Method Not Allowed', { status: 405, headers: CORS_HEADERS });
+      }
+      return json({
+        name: 'Symbols MCP',
+        version: '1.0.11',
+        description: 'MCP server for Symbols.app — documentation search and framework reference',
+        endpoints: {
+          mcp: 'POST / (Streamable HTTP transport)',
+          health: 'GET /health',
+          tools: 'GET /tools',
+          resources: 'GET /resources',
+          prompts: 'GET /prompts',
+        },
+      });
     }
 
-    // Support batch requests
-    if (Array.isArray(body)) {
-      const results = body.map(handleJsonRpc).filter(Boolean);
-      return json(results);
+    if (request.method === 'DELETE') {
+      return new Response(null, { status: 405, headers: CORS_HEADERS });
     }
 
-    const result = handleJsonRpc(body);
-    if (result === null) return new Response(null, { status: 204 });
-    return json(result);
+    if (request.method === 'POST') {
+      let body;
+      try {
+        body = await request.json();
+      } catch {
+        return json({ jsonrpc: '2.0', error: { code: -32700, message: 'Parse error' } }, 400);
+      }
+      return handleMcpPost(request, body);
+    }
   }
 
-  // ── REST endpoints ─────────────────────────────────────────────────────
+  // ── Health check ────────────────────────────────────────────────────
+
+  if (pathname === '/health' && request.method === 'GET') {
+    return json({ alive: true, service: 'symbols-mcp', runtime: 'cloudflare-worker' });
+  }
+
+  // ── REST endpoints ─────────────────────────────────────────────────
 
-  // GET /tools — list all tools
   if (pathname === '/tools' && request.method === 'GET') {
     return json({ tools: TOOLS });
   }
 
-  // POST /tools/:name — call a tool
   if (pathname.startsWith('/tools/') && request.method === 'POST') {
     const toolName = pathname.slice('/tools/'.length);
     let args = {};
@@ -74,7 +165,6 @@ export async function handleRequest(request) {
     } catch {
       return json({ error: 'Invalid JSON body' }, 400);
     }
-
     try {
       const result = callTool(toolName, args);
       return json({ content: [{ type: 'text', text: result }] });
@@ -83,12 +173,10 @@ export async function handleRequest(request) {
     }
   }
 
-  // GET /resources — list all resources
   if (pathname === '/resources' && request.method === 'GET') {
     return json({ resources: listResources() });
   }
 
-  // GET /resources/:uri — read a resource (uri passed as query param)
   if (pathname === '/resources/read' && request.method === 'GET') {
     const uri = url.searchParams.get('uri');
     if (!uri) return json({ error: 'Missing ?uri= parameter' }, 400);
@@ -97,10 +185,9 @@ export async function handleRequest(request) {
     return json({ contents: [{ uri, mimeType: 'text/markdown', text: content }] });
   }
 
-  // GET /prompts — list all prompts
   if (pathname === '/prompts' && request.method === 'GET') {
     return json({ prompts: PROMPTS });
   }
 
-  return json({ error: 'Not found' }, 404);
+  return new Response('Not Found', { status: 404 });
 }

package/worker.js

@@ -14,19 +14,7 @@ export default {
   async fetch(request, env) {
     const url = new URL(request.url);
 
-    // Health check
-    if (url.pathname === '/health') {
-      return Response.json({
-        alive: true,
-        service: 'symbols-mcp',
-        runtime: 'cloudflare-worker',
-      });
-    }
-
     try {
-      if (env.NODE_ENV) process.env.NODE_ENV = env.NODE_ENV;
-      if (env.LOG_LEVEL) process.env.LOG_LEVEL = env.LOG_LEVEL;
-
       const { handleRequest } = await import('./src/worker-handler.js');
       return await handleRequest(request);
     } catch (err) {

package/wrangler.toml

@@ -8,11 +8,11 @@
 # Local dev:
 #   npx wrangler dev
 
+account_id = "98091ed46ea209bb648b108950bd78e7"
 name = "symbols-mcp-dev"
 main = "worker.js"
 compatibility_date = "2024-09-01"
-compatibility_flags = ["nodejs_compat_v2"]
-node_compat = true
+compatibility_flags = ["nodejs_compat"]
 
 # Default vars (dev)
 [vars]
@@ -32,19 +32,12 @@ LOG_LEVEL = "info"
 
 [env.production]
 name = "symbols-mcp"
+workers_dev = true
 
 [env.production.vars]
 NODE_ENV = "production"
 LOG_LEVEL = "info"
 
-# ── Routes (configure once DNS is ready) ─────────────────────────────────────
-#
-# Production: mcp.symbols.app
-# [env.production.routes]
-# pattern = "mcp.symbols.app/*"
-# zone_name = "symbols.app"
-#
-# Dev: mcp.dev.symbols.app
-# [[routes]]
-# pattern = "mcp.dev.symbols.app/*"
-# zone_name = "symbols.app"
+# ── Routes ────────────────────────────────────────────────────────────────────
+
+# Route handled via Cloudflare DNS CNAME → workers.dev