@symbo.ls/mcp-server 3.8.0 → 3.8.6

package/package.json

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

package/src/mcp-handler.js

@@ -741,6 +741,7 @@ const TOOLS = [
         token: { type: 'string' },
         api_key: { type: 'string' },
         visibility: { type: 'string', default: 'private' },
+        language: { type: 'string', default: 'javascript' },
       },
       required: ['name'],
     },
@@ -866,6 +867,7 @@ async function callTool(name, args = {}) {
       'RULES.md',
       'COMMON_MISTAKES.md',
       'PROJECT_STRUCTURE.md',
+      'SHARED_LIBRARIES.md',
       'PATTERNS.md',
       'SNIPPETS.md',
       'DEFAULT_LIBRARY.md',
@@ -975,8 +977,71 @@ async function callTool(name, args = {}) {
         confidence = 'medium';
       }
     }
-    const guide = readSkill('RUNNING_APPS.md');
-    return `# Environment Detection\n\n**Detected: ${envType}** (confidence: ${confidence})\n\n${guide}`;
+    const fullGuide = readSkill('RUNNING_APPS.md');
+    let output = `# Environment Detection\n\n**Detected: ${envType}** (confidence: ${confidence})\n\n`;
+
+    if (envType === 'local_project') {
+      const structureGuide = readSkill('PROJECT_STRUCTURE.md');
+      const sharedLibsGuide = readSkill('SHARED_LIBRARIES.md');
+      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';
+      output += `### Full Project Structure Reference\n\n${structureGuide}`;
+      output += `\n\n### Shared Libraries Reference\n\n${sharedLibsGuide}`;
+    } 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";
+      output += `### Full CDN Reference\n\n${fullGuide}`;
+    } 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;
   }
 
   if (name === 'login') {
@@ -1026,7 +1091,7 @@ async function callTool(name, args = {}) {
     const body = {
       name: args.name,
       visibility: args.visibility || 'private',
-      language: 'javascript',
+      language: args.language || 'javascript',
     };
     if (args.key) body.key = args.key;
     const result = await apiRequest('POST', '/core/projects', {
@@ -1051,15 +1116,22 @@ async function callTool(name, args = {}) {
     const result = await apiRequest('GET', path, { token: args.token, api_key: args.api_key });
     if (result.success) {
       const data = result.data || {};
-      return `# Project Data (branch: ${branch})\n\n**Components (${Object.keys(data.components || {}).length}):** ${
-        Object.keys(data.components || {})
-          .slice(0, 20)
-          .join(', ') || 'none'
-      }\n**Pages (${Object.keys(data.pages || {}).length}):** ${
-        Object.keys(data.pages || {})
-          .slice(0, 20)
-          .join(', ') || 'none'
-      }\n\n\`\`\`json\n${JSON.stringify(data, null, 2).slice(0, 8000)}\n\`\`\``;
+      const components = data.components || {};
+      const pages = data.pages || {};
+      const ds = data.designSystem || {};
+      const state = data.state || {};
+      const functions = data.functions || {};
+      return `# Project Data (branch: ${branch})\n\n**Components (${Object.keys(components).length}):** ${
+        Object.keys(components).slice(0, 20).join(', ') || 'none'
+      }\n**Pages (${Object.keys(pages).length}):** ${
+        Object.keys(pages).slice(0, 20).join(', ') || 'none'
+      }\n**Design System keys:** ${
+        Object.keys(ds).slice(0, 15).join(', ') || 'none'
+      }\n**State keys:** ${
+        Object.keys(state).slice(0, 15).join(', ') || 'none'
+      }\n**Functions (${Object.keys(functions).length}):** ${
+        Object.keys(functions).slice(0, 15).join(', ') || 'none'
+      }\n\n---\n\nFull data:\n\`\`\`json\n${JSON.stringify(data, null, 2).slice(0, 8000)}\n\`\`\``;
     }
     return `Failed to get project: ${result.error || 'Unknown error'}`;
   }
@@ -1171,6 +1243,7 @@ const SKILL_RESOURCES = {
   'symbols://skills/running-apps': 'RUNNING_APPS.md',
   'symbols://skills/cli': 'CLI.md',
   'symbols://skills/sdk': 'SDK.md',
+  'symbols://skills/shared-libraries': 'SHARED_LIBRARIES.md',
   'symbols://skills/common-mistakes': 'COMMON_MISTAKES.md',
   'symbols://skills/brand-identity': 'BRAND_IDENTITY.md',
   'symbols://skills/design-critique': 'DESIGN_CRITIQUE.md',
@@ -1181,13 +1254,110 @@ const SKILL_RESOURCES = {
   'symbols://skills/presentation': 'PRESENTATION.md',
 };
 
+const INLINE_RESOURCES = {
+  'symbols://reference/spacing-tokens': `# Symbols Spacing Tokens
+
+Ratio-based system (base 16px, ratio 1.618 golden ratio):
+
+| Token | ~px  | Token | ~px  | Token | ~px  |
+|-------|------|-------|------|-------|------|
+| X     | 3    | A     | 16   | D     | 67   |
+| Y     | 6    | A1    | 20   | E     | 109  |
+| Z     | 10   | A2    | 22   | F     | 177  |
+| Z1    | 12   | B     | 26   |       |      |
+| Z2    | 14   | B1    | 32   |       |      |
+|       |      | B2    | 36   |       |      |
+|       |      | C     | 42   |       |      |
+|       |      | C1    | 52   |       |      |
+|       |      | C2    | 55   |       |      |
+
+Usage: padding: 'A B', gap: 'C', borderRadius: 'Z', fontSize: 'B1'
+Tokens work with padding, margin, gap, width, height, borderRadius, position, and any spacing property.
+Negative values: margin: '-Y1 -Z2 - auto'
+Math: padding: 'A+V2'
+`,
+  'symbols://reference/atom-components': `# Symbols Atom Components (Primitives)
+
+| Atom       | HTML Tag   | Description                   |
+|------------|------------|-------------------------------|
+| Text       | <span>     | Text content                  |
+| Box        | <div>      | Generic container             |
+| Flex       | <div>      | Flexbox container             |
+| Grid       | <div>      | CSS Grid container            |
+| Link       | <a>        | Anchor with built-in router   |
+| Input      | <input>    | Form input                    |
+| Radio      | <input>    | Radio button                  |
+| Checkbox   | <input>    | Checkbox                      |
+| Svg        | <svg>      | SVG container                 |
+| Icon       | <svg>      | Icon from icon sprite         |
+| IconText   | <div>      | Icon + text combination       |
+| Button     | <button>   | Button with icon/text support |
+| Img        | <img>      | Image element                 |
+| Iframe     | <iframe>   | Embedded frame                |
+| Video      | <video>    | Video element                 |
+
+Usage examples:
+  { Box: { padding: 'A', background: 'surface' } }
+  { Flex: { flow: 'y', gap: 'B', align: 'center center' } }
+  { Grid: { columns: 'repeat(3, 1fr)', gap: 'A' } }
+  { Link: { text: 'Click here', href: '/dashboard' } }
+  { Button: { text: 'Submit', theme: 'primary', icon: 'check' } }
+  { Icon: { name: 'chevronLeft' } }
+  { Img: { src: 'photo.png', boxSize: 'D D' } }
+`,
+  'symbols://reference/event-handlers': `# Symbols Event Handlers (v3)
+
+## Lifecycle Events
+  onInit: (el, state) => {}              // Once on creation
+  onRender: (el, state) => {}            // On each render (return fn for cleanup)
+  onUpdate: (el, state) => {}            // On props/state change
+  onStateUpdate: (changes, el, state, context) => {}
+
+## DOM Events
+  onClick: (event, el, state) => {}
+  onInput: (event, el, state) => {}
+  onKeydown: (event, el, state) => {}
+  onDblclick: (event, el, state) => {}
+  onMouseover: (event, el, state) => {}
+  onWheel: (event, el, state) => {}
+  onSubmit: (event, el, state) => {}
+  onLoad: (event, el, state) => {}
+
+## Calling Functions
+  onClick: (e, el) => el.call('functionName', args)  // Global function
+  onClick: (e, el) => el.scope.localFn(el, s)        // Scope function
+  onClick: (e, el) => el.methodName()                  // Element method
+
+## State Updates
+  onClick: (e, el, s) => s.update({ count: s.count + 1 })
+  onClick: (e, el, s) => s.toggle('isActive')
+  onClick: (e, el, s) => s.root.update({ modal: '/add-item' })
+
+## Navigation
+  onClick: (e, el) => el.router('/dashboard', el.getRoot())
+
+## Cleanup Pattern
+  onRender: (el, s) => {
+    const interval = setInterval(() => { /* ... */ }, 1000)
+    return () => clearInterval(interval)  // Called on element removal
+  }
+`,
+};
+
 function listResources() {
-  return Object.entries(SKILL_RESOURCES)
+  const skillRes = Object.entries(SKILL_RESOURCES)
     .filter(([, f]) => skills[f])
     .map(([uri, f]) => ({ uri, name: f.replace('.md', ''), mimeType: 'text/markdown' }));
+  const inlineRes = Object.keys(INLINE_RESOURCES).map((uri) => ({
+    uri,
+    name: uri.split('/').pop(),
+    mimeType: 'text/markdown',
+  }));
+  return [...skillRes, ...inlineRes];
 }
 
 function readResource(uri) {
+  if (INLINE_RESOURCES[uri]) return INLINE_RESOURCES[uri];
   const f = SKILL_RESOURCES[uri];
   return f && skills[f] ? readSkill(f) : null;
 }
@@ -1232,11 +1402,39 @@ const PROMPTS = [
   },
 ];
 
+// ---------------------------------------------------------------------------
+// Prompt implementations
+// ---------------------------------------------------------------------------
+
+function getPrompt(name, args = {}) {
+  if (name === 'symbols_component_prompt') {
+    const compName = args.component_name || 'MyComponent';
+    return `Generate a Symbols.app component with these requirements:\n\nComponent Name: ${compName}\nDescription: ${args.description || ''}\n\nFollow these strict rules:\n- Use DOMQL v3 syntax ONLY (extends, childExtends, flattened props, onX events)\n- Components are plain objects with named exports: export const ${compName} = { ... }\n- **MANDATORY: ALL values MUST use design system tokens** — spacing (A, B, C, D), colors (primary, surface, white, gray.5), typography (fontSize: 'B'). ZERO px values, ZERO hex colors, ZERO rgb/hsl\n- NO imports between files — reference components by PascalCase key name\n- All folders flat — no subfolders\n- The project likely has a default library — use Button, Avatar, Icon, Field, etc. via extends\n- Include responsive breakpoints (@tabletS, @mobileL) where appropriate\n- Follow modern UI/UX: visual hierarchy, minimal cognitive load, confident typography\n\nOutput ONLY the JavaScript code.`;
+  }
+  if (name === 'symbols_migration_prompt') {
+    const framework = args.source_framework || 'React';
+    return `You are migrating ${framework} code to Symbols.app.\n\nKey conversion rules for ${framework}:\n- Components become plain objects (never functions)\n- NO imports between project files\n- All folders are flat — no subfolders\n- Use extends/childExtends (v3 plural, never v2 singular)\n- Flatten all props directly (no props: {} wrapper)\n- Events use onX prefix (no on: {} wrapper)\n- **MANDATORY: ALL values MUST use design system tokens** — ZERO px values, ZERO hex colors, ZERO rgb/hsl\n- State: state: { key: val } + s.update({ key: newVal })\n- Effects: onRender for mount, onStateUpdate for dependency changes\n- Lists: children: (el, s) => s.items, childrenAs: 'state', childExtends: 'Item'\n- The default library provides Button, Avatar, Field, Modal, etc. — use them via extends\n\nProvide the ${framework} code to convert and I will output clean DOMQL v3.`;
+  }
+  if (name === 'symbols_project_prompt') {
+    return `Create a complete Symbols.app project:\n\nProject Description: ${args.description || ''}\n\nRequired structure (symbols/ folder):\n- index.js (entry: import create from 'smbls', import context, create(app, context))\n- app.js (root app with routes: (pages) => pages)\n- config.js ({ globalTheme: 'dark' })\n- context.js (re-exports: state, pages, designSystem, components, functions, snippets)\n- state.js (app state)\n- dependencies.js (external packages)\n- components/ (PascalCase files, named exports)\n- pages/ (dash-case files, camelCase exports, route mapping in index.js)\n- functions/ (camelCase, called via el.call())\n- designSystem/ (COLOR, THEME, TYPOGRAPHY, SPACING, FONT, ICONS)\n- snippets/ (reusable snippets)\n\nThe project uses the default library (default.symbo.ls) which provides:\nButton, Avatar, Icon, Field, Modal, Badge, Progress, TabSet, and 120+ more components.\nReference these by PascalCase key name — no imports needed.\n\nRules:\n- v3 syntax only — extends, childExtends, flattened props, onX events\n- Design tokens for all spacing/colors (padding: 'A', not padding: '16px')\n- Components are plain objects, never functions\n- No imports between project files\n- All folders completely flat\n\nGenerate all files with complete, production-ready code.`;
+  }
+  if (name === 'symbols_review_prompt') {
+    return `Review this Symbols/DOMQL code for v3 compliance and best practices.\n\nCheck for these violations:\n1. v2 syntax: extend→extends, childExtend→childExtends, props:{}, on:{}\n2. Imports between project files (FORBIDDEN)\n3. Function-based components (must be plain objects)\n4. Subfolders (must be flat)\n5. Hardcoded pixels instead of design tokens\n6. Wrong event handler signatures (lifecycle: (el, s), DOM: (event, el, s))\n7. Default exports for components (should be named)\n8. Standard HTML attrs in attr: {} (should be at root; attr: {} only for data-*/aria-*/custom)\n9. props block CSS trying to override component-level CSS (can't)\n\nProvide:\n- Issues found with line references\n- Corrected code for each issue\n- Overall v3 compliance score (1-10)\n- Improvement suggestions\n\nPaste your code below:`;
+  }
+  if (name === 'symbols_convert_html_prompt') {
+    return `Convert the provided HTML/CSS to Symbols.app DOMQL v3 components.\n\nConversion rules:\n- <div> → Box, Flex, or Grid (based on layout)\n- <span>/<p>/<h1>-<h6> → Text/P/H with tag property\n- <a> → Link (built-in SPA router, use e.preventDefault() + el.router())\n- <button> → Button\n- <input> → Input, Radio, Checkbox\n- <img> → Img\n- <form> → Form\n- <ul>/<ol> + <li> → children array with childExtends\n- CSS px → design tokens (16px→'A', 26px→'B', 42px→'C')\n- CSS colors → theme tokens\n- media queries → @tabletS, @mobileL breakpoints\n- CSS classes → flatten as component properties\n- id/class attrs → not needed\n\nOutput clean DOMQL v3 with named exports.\n\nPaste the HTML below:`;
+  }
+  if (name === 'symbols_design_review_prompt') {
+    return `Review this Symbols component for design system compliance.\n\nCheck:\n1. Spacing uses tokens (A, B, C...) not pixels\n2. Colors come from theme, not hardcoded hex/rgb\n3. Typography uses design system scale (fontSize tokens)\n4. Responsive breakpoints present (@tabletS, @mobileL)\n5. Visual hierarchy is clear (heading sizes, spacing rhythm)\n6. Interactive elements have hover/focus/active states\n7. Accessibility: focus-visible, ARIA attributes where needed\n8. Consistent use of theme variants (primary, secondary, card, dialog)\n9. Layout uses Flex/Grid with proper alignment tokens\n\nProvide design improvement suggestions with corrected code.\n\nPaste your component code below:`;
+  }
+  return null;
+}
+
 // ---------------------------------------------------------------------------
 // MCP JSON-RPC handler
 // ---------------------------------------------------------------------------
 
-const SERVER_INFO = { name: 'Symbols MCP', version: '1.0.15' };
+const SERVER_INFO = { name: 'Symbols MCP', version: '1.0.16' };
 
 export async function handleJsonRpc(req) {
   const { method, params, id } = req;
@@ -1283,9 +1481,25 @@ export async function handleJsonRpc(req) {
     };
   }
   if (method === 'prompts/list') return { jsonrpc: '2.0', id, result: { prompts: PROMPTS } };
+  if (method === 'prompts/get') {
+    const promptName = params?.name;
+    const promptArgs = params?.arguments || {};
+    const text = getPrompt(promptName, promptArgs);
+    if (text === null)
+      return {
+        jsonrpc: '2.0',
+        id,
+        error: { code: -32602, message: `Prompt not found: ${promptName}` },
+      };
+    return {
+      jsonrpc: '2.0',
+      id,
+      result: { messages: [{ role: 'user', content: { type: 'text', text } }] },
+    };
+  }
   if (id !== undefined)
     return { jsonrpc: '2.0', id, error: { code: -32601, message: 'Method not found' } };
   return null;
 }
 
-export { TOOLS, listResources, readResource, callTool, PROMPTS };
+export { TOOLS, listResources, readResource, callTool, PROMPTS, getPrompt };