@symbo.ls/mcp-server 3.6.1

package/build.js

@@ -0,0 +1,51 @@
+/**
+ * Bundle skills from @symbo.ls/mcp into a single JS module.
+ *
+ * This pre-reads all .md files from the skills directory and writes them
+ * as a JS map so the Cloudflare Worker can use them without fs access.
+ *
+ * Run: node build.js
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { createRequire } from 'module';
+
+const require = createRequire(import.meta.url);
+
+// Resolve skills directory from the @symbo.ls/mcp package
+let skillsDir;
+try {
+  const mcpPkg = require.resolve('@symbo.ls/mcp/package.json');
+  skillsDir = path.join(path.dirname(mcpPkg), 'symbols_mcp', 'skills');
+} catch {
+  const __dirname = path.dirname(new URL(import.meta.url).pathname);
+  skillsDir = path.resolve(__dirname, '../../../symbols-mcp/symbols_mcp/skills');
+}
+
+if (!fs.existsSync(skillsDir)) {
+  console.error(`Skills directory not found: ${skillsDir}`);
+  process.exit(1);
+}
+
+const files = fs.readdirSync(skillsDir).filter((f) => f.endsWith('.md'));
+const skills = {};
+
+for (const file of files) {
+  const content = fs.readFileSync(path.join(skillsDir, file), 'utf8');
+  skills[file] = content;
+}
+
+const output = `// Auto-generated by build.js — do not edit manually
+// Source: ${skillsDir}
+// Generated: ${new Date().toISOString()}
+
+export const skills = ${JSON.stringify(skills, null, 2)};
+`;
+
+const outPath = path.join(path.dirname(new URL(import.meta.url).pathname), 'src', 'skills-data.js');
+fs.writeFileSync(outPath, output);
+
+console.log(
+  `[BUILD] Bundled ${files.length} skills into src/skills-data.js (${output.length} bytes)`,
+);

package/index.js

@@ -0,0 +1,85 @@
+/**
+ * Symbols MCP HTTP Proxy — Local Express Server
+ *
+ * Usage:
+ *   node index.js                          # start on port 3335
+ *   PORT=4000 node index.js                # custom port
+ */
+
+import express from 'express';
+import cors from 'cors';
+import {
+  handleJsonRpc,
+  TOOLS,
+  listResources,
+  readResource,
+  callTool,
+  PROMPTS,
+} from './src/mcp-handler.js';
+
+const PORT = parseInt(process.env.PORT, 10) || 3335;
+
+const app = express();
+
+app.use(cors({ origin: '*', methods: 'GET, POST' }));
+app.use(express.json());
+
+// Health check
+app.get('/health', (req, res) => {
+  res.json({ alive: true, service: 'symbols-mcp', runtime: 'node' });
+});
+
+// MCP JSON-RPC endpoint
+app.post('/mcp', (req, res) => {
+  const body = req.body;
+
+  // Batch requests
+  if (Array.isArray(body)) {
+    const results = body.map(handleJsonRpc).filter(Boolean);
+    return res.json(results);
+  }
+
+  const result = handleJsonRpc(body);
+  if (result === null) return res.status(204).end();
+  return res.json(result);
+});
+
+// REST: list tools
+app.get('/tools', (req, res) => {
+  res.json({ tools: TOOLS });
+});
+
+// REST: call a tool
+app.post('/tools/:name', (req, res) => {
+  try {
+    const result = callTool(req.params.name, req.body || {});
+    res.json({ content: [{ type: 'text', text: result }] });
+  } catch (e) {
+    res.status(404).json({ error: e.message });
+  }
+});
+
+// REST: list resources
+app.get('/resources', (req, res) => {
+  res.json({ resources: listResources() });
+});
+
+// REST: read a resource
+app.get('/resources/read', (req, res) => {
+  const uri = req.query.uri;
+  if (!uri) return res.status(400).json({ error: 'Missing ?uri= parameter' });
+  const content = readResource(uri);
+  if (content === null) return res.status(404).json({ error: `Resource not found: ${uri}` });
+  res.json({ contents: [{ uri, mimeType: 'text/markdown', text: content }] });
+});
+
+// REST: list prompts
+app.get('/prompts', (req, res) => {
+  res.json({ prompts: PROMPTS });
+});
+
+app.listen(PORT, () => {
+  console.log(`[SYMBOLS-MCP] HTTP proxy running on http://localhost:${PORT}`);
+  console.log(`[SYMBOLS-MCP] MCP endpoint: POST http://localhost:${PORT}/mcp`);
+  console.log(`[SYMBOLS-MCP] REST API: GET /tools, /resources, /prompts`);
+});

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "@symbo.ls/mcp-server",
+  "version": "3.6.1",
+  "description": "HTTP proxy for the Symbols MCP server — runs as a Cloudflare Worker",
+  "type": "module",
+  "main": "index.js",
+  "scripts": {
+    "build": "node build.js",
+    "prestart": "node build.js",
+    "start": "node index.js",
+    "dev": "node build.js && NODE_ENV=development node index.js",
+    "predeploy": "node build.js",
+    "deploy": "npx wrangler deploy",
+    "deploy:staging": "node build.js && npx wrangler deploy --env staging",
+    "deploy:production": "node build.js && npx wrangler deploy --env production",
+    "cf:dev": "node build.js && npx wrangler dev"
+  },
+  "dependencies": {
+    "@symbo.ls/mcp": "file:../../../symbols-mcp",
+    "express": "^4.18.2",
+    "cors": "^2.8.5"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/mcp-handler.js

@@ -0,0 +1,237 @@
+/**
+ * Core MCP logic for the HTTP proxy.
+ *
+ * Uses pre-bundled skills data (generated by build.js) so it works
+ * in both Node.js and Cloudflare Worker environments without fs access.
+ */
+
+import { skills } from './skills-data.js';
+
+// ---------------------------------------------------------------------------
+// Skills access
+// ---------------------------------------------------------------------------
+
+function readSkill(filename) {
+  return skills[filename] || `Skill '${filename}' not found`;
+}
+
+function listSkillFiles() {
+  return Object.keys(skills);
+}
+
+// ---------------------------------------------------------------------------
+// Tools
+// ---------------------------------------------------------------------------
+
+const TOOLS = [
+  {
+    name: 'get_project_rules',
+    description:
+      'ALWAYS call this first before any generate_* tool. Returns the mandatory Symbols.app rules that MUST be followed.',
+    inputSchema: { type: 'object', properties: {} },
+  },
+  {
+    name: 'search_symbols_docs',
+    description: 'Search the Symbols documentation knowledge base for relevant information.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: {
+          type: 'string',
+          description: 'Natural language search query about Symbols/DOMQL',
+        },
+        max_results: {
+          type: 'number',
+          description: 'Maximum number of results (1-5)',
+          default: 3,
+        },
+      },
+      required: ['query'],
+    },
+  },
+];
+
+function callTool(name, args = {}) {
+  if (name === 'get_project_rules') {
+    return readSkill('RULES.md');
+  }
+
+  if (name === 'search_symbols_docs') {
+    const query = args.query || '';
+    const maxResults = Math.min(Math.max(args.max_results || 3, 1), 5);
+    const keywords = query
+      .toLowerCase()
+      .split(/\s+/)
+      .filter((w) => w.length > 2);
+    if (!keywords.length) keywords.push(query.toLowerCase());
+
+    const results = [];
+    for (const fname of listSkillFiles()) {
+      const content = readSkill(fname);
+      const contentLower = content.toLowerCase();
+      if (!keywords.some((kw) => contentLower.includes(kw))) continue;
+
+      const lines = content.split('\n');
+      for (let i = 0; i < lines.length; i++) {
+        if (keywords.some((kw) => lines[i].toLowerCase().includes(kw))) {
+          results.push({
+            file: fname,
+            snippet: lines.slice(Math.max(0, i - 2), Math.min(lines.length, i + 20)).join('\n'),
+          });
+          break;
+        }
+      }
+      if (results.length >= maxResults) break;
+    }
+
+    return results.length
+      ? JSON.stringify(results, null, 2)
+      : `No results found for '${query}'. Try a different search term.`;
+  }
+
+  throw new Error(`Unknown tool: ${name}`);
+}
+
+// ---------------------------------------------------------------------------
+// Resources — skill files exposed as MCP resources
+// ---------------------------------------------------------------------------
+
+const SKILL_RESOURCES = {
+  'symbols://skills/rules': 'RULES.md',
+  'symbols://skills/syntax': 'SYNTAX.md',
+  'symbols://skills/components': 'COMPONENTS.md',
+  'symbols://skills/project-structure': 'PROJECT_STRUCTURE.md',
+  'symbols://skills/design-system': 'DESIGN_SYSTEM.md',
+  'symbols://skills/design-direction': 'DESIGN_DIRECTION.md',
+  'symbols://skills/patterns': 'PATTERNS.md',
+  'symbols://skills/migration': 'MIGRATION.md',
+  'symbols://skills/audit': 'AUDIT.md',
+  'symbols://skills/design-to-code': 'DESIGN_TO_CODE.md',
+  'symbols://skills/seo-metadata': 'SEO-METADATA.md',
+};
+
+function listResources() {
+  const resources = [];
+  for (const [uri, filename] of Object.entries(SKILL_RESOURCES)) {
+    if (skills[filename]) {
+      resources.push({ uri, name: filename.replace('.md', ''), mimeType: 'text/markdown' });
+    }
+  }
+  return resources;
+}
+
+function readResource(uri) {
+  const filename = SKILL_RESOURCES[uri];
+  if (filename && skills[filename]) {
+    return readSkill(filename);
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Prompts
+// ---------------------------------------------------------------------------
+
+const PROMPTS = [
+  {
+    name: 'symbols_component_prompt',
+    description: 'Prompt template for generating a Symbols.app component.',
+    arguments: [
+      { name: 'description', description: 'Component description', required: true },
+      { name: 'component_name', description: 'Component name', required: false },
+    ],
+  },
+  {
+    name: 'symbols_migration_prompt',
+    description: 'Prompt template for migrating code to Symbols.app.',
+    arguments: [
+      {
+        name: 'source_framework',
+        description: 'Source framework (React, Vue, etc.)',
+        required: false,
+      },
+    ],
+  },
+  {
+    name: 'symbols_project_prompt',
+    description: 'Prompt template for scaffolding a complete Symbols project.',
+    arguments: [{ name: 'description', description: 'Project description', required: true }],
+  },
+  {
+    name: 'symbols_review_prompt',
+    description: 'Prompt template for reviewing Symbols/DOMQL code.',
+    arguments: [],
+  },
+];
+
+// ---------------------------------------------------------------------------
+// MCP JSON-RPC handler
+// ---------------------------------------------------------------------------
+
+const SERVER_INFO = { name: 'Symbols MCP', version: '1.0.10' };
+
+export function handleJsonRpc(req) {
+  const { method, params, id } = req;
+
+  if (method === 'initialize') {
+    return {
+      jsonrpc: '2.0',
+      id,
+      result: {
+        protocolVersion: params?.protocolVersion ?? '2025-03-26',
+        capabilities: { tools: {}, resources: {}, prompts: {} },
+        serverInfo: SERVER_INFO,
+      },
+    };
+  }
+
+  if (method === 'notifications/initialized') return null;
+  if (method === 'ping') return { jsonrpc: '2.0', id, result: {} };
+
+  if (method === 'tools/list') {
+    return { jsonrpc: '2.0', id, result: { tools: TOOLS } };
+  }
+
+  if (method === 'tools/call') {
+    const { name, arguments: args = {} } = params || {};
+    try {
+      const text = callTool(name, args);
+      return { jsonrpc: '2.0', id, result: { content: [{ type: 'text', text }] } };
+    } catch (e) {
+      return {
+        jsonrpc: '2.0',
+        id,
+        result: { content: [{ type: 'text', text: e.message }], isError: true },
+      };
+    }
+  }
+
+  if (method === 'resources/list') {
+    return { jsonrpc: '2.0', id, result: { resources: listResources() } };
+  }
+
+  if (method === 'resources/read') {
+    const uri = params?.uri;
+    const content = readResource(uri);
+    if (content === null) {
+      return { jsonrpc: '2.0', id, error: { code: -32602, message: `Resource not found: ${uri}` } };
+    }
+    return {
+      jsonrpc: '2.0',
+      id,
+      result: { contents: [{ uri, mimeType: 'text/markdown', text: content }] },
+    };
+  }
+
+  if (method === 'prompts/list') {
+    return { jsonrpc: '2.0', id, result: { prompts: PROMPTS } };
+  }
+
+  if (id !== undefined) {
+    return { jsonrpc: '2.0', id, error: { code: -32601, message: 'Method not found' } };
+  }
+
+  return null;
+}
+
+export { TOOLS, listResources, readResource, callTool, PROMPTS };

package/src/worker-handler.js

@@ -0,0 +1,106 @@
+/**
+ * Cloudflare Worker request handler for Symbols MCP HTTP proxy.
+ *
+ * Exposes the MCP server over HTTP with two interfaces:
+ *   1. MCP JSON-RPC protocol (POST /mcp)
+ *   2. REST-style endpoints for direct access
+ */
+
+import {
+  handleJsonRpc,
+  TOOLS,
+  listResources,
+  readResource,
+  callTool,
+  PROMPTS,
+} from './mcp-handler.js';
+
+const CORS_HEADERS = {
+  'Access-Control-Allow-Origin': '*',
+  'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
+  'Access-Control-Allow-Headers': 'Content-Type, Authorization',
+};
+
+function json(data, status = 200) {
+  return new Response(JSON.stringify(data), {
+    status,
+    headers: { 'Content-Type': 'application/json', ...CORS_HEADERS },
+  });
+}
+
+export async function handleRequest(request) {
+  const url = new URL(request.url);
+  const { pathname } = url;
+
+  // CORS preflight
+  if (request.method === 'OPTIONS') {
+    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);
+    }
+
+    // Support batch requests
+    if (Array.isArray(body)) {
+      const results = body.map(handleJsonRpc).filter(Boolean);
+      return json(results);
+    }
+
+    const result = handleJsonRpc(body);
+    if (result === null) return new Response(null, { status: 204 });
+    return json(result);
+  }
+
+  // ── 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 = {};
+    try {
+      const text = await request.text();
+      if (text) args = JSON.parse(text);
+    } catch {
+      return json({ error: 'Invalid JSON body' }, 400);
+    }
+
+    try {
+      const result = callTool(toolName, args);
+      return json({ content: [{ type: 'text', text: result }] });
+    } catch (e) {
+      return json({ error: e.message }, 404);
+    }
+  }
+
+  // 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);
+    const content = readResource(uri);
+    if (content === null) return json({ error: `Resource not found: ${uri}` }, 404);
+    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);
+}

package/worker.js

@@ -0,0 +1,36 @@
+/**
+ * Cloudflare Worker entry point for Symbols MCP HTTP proxy.
+ *
+ * Deploy:
+ *   npx wrangler deploy                    # dev (default)
+ *   npx wrangler deploy --env staging
+ *   npx wrangler deploy --env production
+ *
+ * Dev:
+ *   npx wrangler dev
+ */
+
+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) {
+      return new Response(`Internal Server Error: ${err.message}`, { status: 500 });
+    }
+  },
+};

package/wrangler.toml

@@ -0,0 +1,50 @@
+# Cloudflare Workers configuration for Symbols MCP HTTP proxy
+#
+# Deploy:
+#   npx wrangler deploy                        # dev (default)
+#   npx wrangler deploy --env staging
+#   npx wrangler deploy --env production
+#
+# Local dev:
+#   npx wrangler dev
+
+name = "symbols-mcp-dev"
+main = "worker.js"
+compatibility_date = "2024-09-01"
+compatibility_flags = ["nodejs_compat_v2"]
+node_compat = true
+
+# Default vars (dev)
+[vars]
+NODE_ENV = "development"
+LOG_LEVEL = "debug"
+
+# ── Staging ──────────────────────────────────────────────────────────────────
+
+[env.staging]
+name = "symbols-mcp-staging"
+
+[env.staging.vars]
+NODE_ENV = "staging"
+LOG_LEVEL = "info"
+
+# ── Production ───────────────────────────────────────────────────────────────
+
+[env.production]
+name = "symbols-mcp"
+
+[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"