@symbo.ls/mcp 1.0.5 → 1.0.8

package/README.md

@@ -2,7 +2,7 @@
 
 mcp-name: io.github.symbo-ls/symbols-mcp
 
-MCP server for [Symbols/DOMQL v3](https://symbols.so) — provides documentation search and framework reference tools for AI coding assistants (Cursor, Claude Code, Windsurf, etc.).
+MCP server for [Symbols.app](https://symbols.app) — provides documentation search and framework reference tools for AI coding assistants (Cursor, Claude Code, Windsurf, etc.).
 
 No API keys required. All tools work fully offline using bundled documentation.
 
@@ -10,7 +10,7 @@ No API keys required. All tools work fully offline using bundled documentation.
 
 ## Tools
 
-- **`get_project_rules`** — Returns mandatory Symbols/DOMQL v3 rules. Call this before any code generation task.
+- **`get_project_rules`** — Returns mandatory Symbols.app rules. Call this before any code generation task.
 - **`search_symbols_docs`** — Keyword search across all bundled Symbols documentation files.
 
 ## Resources

package/bin/symbols-mcp.js

@@ -1,17 +1,101 @@
 #!/usr/bin/env node
-const { spawn } = require('child_process')
-const { execSync } = require('child_process')
-
-let cmd, args
-
-try {
-  execSync('uvx --version', { stdio: 'ignore' })
-  cmd = 'uvx'
-  args = ['symbols-mcp']
-} catch {
-  cmd = 'python3'
-  args = ['-m', 'symbols_mcp.server']
+'use strict'
+const fs = require('fs')
+const path = require('path')
+const readline = require('readline')
+
+const SKILLS_DIR = path.join(__dirname, '..', 'symbols_mcp', 'skills')
+
+function readSkill(filename) {
+  const p = path.join(SKILLS_DIR, filename)
+  return fs.existsSync(p) ? fs.readFileSync(p, 'utf8') : `Skill '${filename}' not found`
+}
+
+function loadAgentInstructions() {
+  const ai = path.join(SKILLS_DIR, 'AGENT_INSTRUCTIONS.md')
+  return fs.existsSync(ai) ? fs.readFileSync(ai, 'utf8') : readSkill('CLAUDE.md')
+}
+
+function searchDocs(query, maxResults = 3) {
+  const keywords = query.toLowerCase().split(/\s+/).filter(w => w.length > 2)
+  if (!keywords.length) keywords.push(query.toLowerCase())
+
+  const results = []
+  for (const fname of fs.readdirSync(SKILLS_DIR)) {
+    if (!fname.endsWith('.md')) continue
+    const content = fs.readFileSync(path.join(SKILLS_DIR, fname), 'utf8')
+    if (!keywords.some(kw => content.toLowerCase().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}'`
+}
+
+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. Violations cause silent failures — black page, nothing renders.',
+    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 send(obj) {
+  process.stdout.write(JSON.stringify(obj) + '\n')
+}
+
+function handle(req) {
+  if (!req.method) return
+  if (req.method === 'initialize') {
+    return send({
+      jsonrpc: '2.0', id: req.id,
+      result: {
+        protocolVersion: req.params?.protocolVersion ?? '2025-03-26',
+        capabilities: { tools: {} },
+        serverInfo: { name: 'Symbols MCP', version: '1.0.6' }
+      }
+    })
+  }
+  if (req.method === 'notifications/initialized') return
+  if (req.method === 'ping') return send({ jsonrpc: '2.0', id: req.id, result: {} })
+  if (req.method === 'tools/list') return send({ jsonrpc: '2.0', id: req.id, result: { tools: TOOLS } })
+  if (req.method === 'tools/call') {
+    const { name, arguments: args = {} } = req.params
+    try {
+      let text
+      if (name === 'get_project_rules') text = loadAgentInstructions()
+      else if (name === 'search_symbols_docs') text = searchDocs(args.query, args.max_results || 3)
+      else throw new Error(`Unknown tool: ${name}`)
+      return send({ jsonrpc: '2.0', id: req.id, result: { content: [{ type: 'text', text }] } })
+    } catch (e) {
+      return send({ jsonrpc: '2.0', id: req.id, result: { content: [{ type: 'text', text: e.message }], isError: true } })
+    }
+  }
+  if (req.id !== undefined) {
+    send({ jsonrpc: '2.0', id: req.id, error: { code: -32601, message: 'Method not found' } })
+  }
 }
 
-const child = spawn(cmd, args, { stdio: 'inherit' })
-child.on('exit', code => process.exit(code ?? 0))
+const rl = readline.createInterface({ input: process.stdin, terminal: false })
+rl.on('line', line => {
+  if (!line.trim()) return
+  try { handle(JSON.parse(line)) } catch (e) { process.stderr.write(`Parse error: ${e.message}\n`) }
+})
+rl.on('close', () => process.exit(0))

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "@symbo.ls/mcp",
-  "version": "1.0.5",
-  "description": "MCP server for Symbols/DOMQL v3 — documentation search and framework reference",
+  "version": "1.0.8",
+  "description": "MCP server for Symbols.app — documentation search and framework reference",
   "mcpName": "io.github.symbo-ls/symbols-mcp",
+  "files": [
+    "bin/",
+    "symbols_mcp/skills/"
+  ],
   "bin": {
     "symbols-mcp": "./bin/symbols-mcp.js"
   },
@@ -10,6 +14,12 @@
     "type": "git",
     "url": "https://github.com/symbo-ls/symbols-mcp.git"
   },
-  "keywords": ["mcp", "symbols", "domql", "ai", "claude"],
+  "keywords": [
+    "mcp",
+    "symbols",
+    "domql",
+    "ai",
+    "claude"
+  ],
   "license": "MIT"
 }

package/symbols_mcp/skills/AGENT_INSTRUCTIONS.md

@@ -1,6 +1,6 @@
 # Symbols / DOMQL v3 — AI Agent Instructions
 
-You are working inside a **Symbols/DOMQL v3** project. These rules are absolute and override any general coding instincts. Violations cause silent failures (black page, nothing renders).
+You are working inside a **Symbols.app** project. These rules are absolute and override any general coding instincts. Violations cause silent failures (black page, nothing renders).
 
 ---
 
@@ -8,10 +8,10 @@ You are working inside a **Symbols/DOMQL v3** project. These rules are absolute
 
 ```js
 // CORRECT
-export const Header = { extends: 'Flex', padding: 'A' }
+export const Header = { extends: "Flex", padding: "A" };
 
 // WRONG — never
-export const Header = (el, state) => ({ padding: 'A' })
+export const Header = (el, state) => ({ padding: "A" });
 ```
 
 ---
@@ -36,11 +36,11 @@ Nav: { extends: 'Navbar' }
 
 ```js
 // CORRECT
-export * from './Navbar.js'
-export * from './PostCard.js'
+export * from "./Navbar.js";
+export * from "./PostCard.js";
 
 // WRONG — this breaks everything
-export * as Navbar from './Navbar.js'
+export * as Navbar from "./Navbar.js";
 ```
 
 ---
@@ -60,8 +60,8 @@ export const main = { extends: 'Flex', ... }
 ## 5. `pages/index.js` — imports ARE allowed here (it's the registry)
 
 ```js
-import { main } from './main.js'
-export default { '/': main }
+import { main } from "./main.js";
+export default { "/": main };
 ```
 
 This is the **only** file where cross-file imports are permitted.
@@ -96,12 +96,12 @@ export const switchView = function switchView(view) {
 ```js
 // functions/myFn.js
 export const myFn = function myFn(arg1) {
-  const node = this.node  // 'this' is the DOMQL element
-}
+  const node = this.node; // 'this' is the DOMQL element
+};
 
 // In component
-onClick: (e, el) => el.call('myFn', someArg)  // CORRECT
-onClick: (e, el) => el.call('myFn', el, someArg)  // WRONG — el passed twice
+onClick: (e, el) => el.call("myFn", someArg); // CORRECT
+onClick: (e, el) => el.call("myFn", el, someArg); // WRONG — el passed twice
 ```
 
 ---
@@ -136,8 +136,10 @@ MyBtn: { extends: 'Button', Icon: { name: 'heart' } }
 ## 10. State — use `s.update()`, never mutate directly
 
 ```js
-onClick: (e, el, s) => s.update({ count: s.count + 1 })  // CORRECT
-onClick: (e, el, s) => { s.count = s.count + 1 }          // WRONG — no re-render
+onClick: (e, el, s) => s.update({ count: s.count + 1 }); // CORRECT
+onClick: (e, el, s) => {
+  s.count = s.count + 1;
+}; // WRONG — no re-render
 ```
 
 Root-level state (global): `s.root.update({ key: val })`
@@ -146,11 +148,11 @@ Root-level state (global): `s.root.update({ key: val })`
 
 ## 11. v3 syntax — never use v2
 
-| v3 ✅ | v2 ❌ |
-|---|---|
-| `extends: 'X'` | `extend: 'X'` |
-| `childExtends: 'X'` | `childExtend: 'X'` |
-| `onClick: fn` | `on: { click: fn }` |
+| v3 ✅                   | v2 ❌                    |
+| ----------------------- | ------------------------ |
+| `extends: 'X'`          | `extend: 'X'`            |
+| `childExtends: 'X'`     | `childExtend: 'X'`       |
+| `onClick: fn`           | `on: { click: fn }`      |
 | props flattened at root | `props: { ... }` wrapper |
 
 ---
@@ -168,10 +170,10 @@ components/nav/Navbar.js   ❌
 
 ```js
 onRender: (el) => {
-  if (el.__initialized) return
-  el.__initialized = true
+  if (el.__initialized) return;
+  el.__initialized = true;
   // imperative logic here
-}
+};
 ```
 
 ---
@@ -205,17 +207,23 @@ Define named tokens in `designSystem/COLOR.js` instead:
 ```js
 // designSystem/COLOR.js
 export default {
-  whiteMuted: 'rgba(255,255,255,0.7)',
-  whiteSubtle: 'rgba(255,255,255,0.6)',
-  whiteFaint:  'rgba(255,255,255,0.5)',
-}
+  whiteMuted: "rgba(255,255,255,0.7)",
+  whiteSubtle: "rgba(255,255,255,0.6)",
+  whiteFaint: "rgba(255,255,255,0.5)",
+};
 
 // In component — CORRECT
-{ color: 'whiteMuted' }
+{
+  color: "whiteMuted";
+}
 
 // WRONG — renders as literal text, not a style
-{ color: 'white .7' }
-{ color: 'black .5' }
+{
+  color: "white .7";
+}
+{
+  color: "black .5";
+}
 ```
 
 ---

package/symbols_mcp/skills/BUILT_IN_COMPONENTS.md

@@ -1,6 +1,6 @@
 # Built-in atoms and property usage
 
-This document lists the built-in components (atoms and UI kit components) and how their properties are commonly used in Symbols/DOMQL v3.
+This document lists the built-in components (atoms and UI kit components) and how their properties are commonly used in Symbols.app.
 
 ## Built-in atoms