@symbo.ls/mcp 1.0.0

package/.env.example

@@ -0,0 +1,16 @@
+# OPTION 1: Use public MCP server (no API key needed - easiest for users)
+# Contact the maintainer for the public server URL
+SYMBOLS_MCP_URL=your_mcp_server_url_here
+
+# OPTION 2: Use your own OpenRouter API key (for advanced users)
+# OPENROUTER_API_KEY=your_openrouter_api_key_here
+
+# Optional — Supabase for vector search (falls back to local skills search if not set)
+# SUPABASE_URL=your_supabase_url_here
+# SUPABASE_KEY=your_supabase_key_here
+
+# Optional — AI model to use (default: openai/gpt-4.1-mini)
+# LLM_MODEL=openai/gpt-4.1-mini
+
+# Optional — Path to skills directory (defaults to bundled skills)
+# SYMBOLS_SKILLS_DIR=C:\repos\symbols\skills

package/.env.railway

@@ -0,0 +1,13 @@
+# Railway Environment Variables
+RAILWAY_ENVIRONMENT=production
+PORT=8080
+
+# Required — OpenRouter API key (add in Railway dashboard)
+OPENROUTER_API_KEY=your_openrouter_api_key_here
+
+# Optional — Supabase for vector search (add in Railway dashboard)
+SUPABASE_URL=your_supabase_url_here
+SUPABASE_KEY=your_supabase_key_here
+
+# Optional — AI model (add in Railway dashboard)
+LLM_MODEL=openai/gpt-5.2-codex

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 baronsilver
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,184 @@
+# Symbols MCP Server
+
+An MCP (Model Context Protocol) server that exposes the Symbols/DOMQL v3 AI assistant capabilities to any MCP-compatible platform — **Cursor**, **Claude Code**, **Windsurf**, and more.
+
+## Features
+
+### Tools
+| Tool | Description |
+|------|-------------|
+| `generate_component` | Generate a Symbols/DOMQL v3 component from natural language |
+| `generate_page` | Generate a full page with routing support |
+| `generate_project` | Scaffold a complete multi-file Symbols project |
+| `convert_to_symbols` | Convert React/Angular/Vue/HTML to Symbols/DOMQL v3 |
+| `search_symbols_docs` | Search Symbols documentation (vector or local) |
+| `explain_symbols_concept` | Explain any Symbols concept with examples |
+| `review_symbols_code` | Review code for v3 compliance and best practices |
+| `create_design_system` | Generate design system files (colors, spacing, themes, icons) |
+
+### Resources
+| Resource URI | Description |
+|-------------|-------------|
+| `symbols://skills/domql-v3-reference` | Complete DOMQL v3 syntax reference |
+| `symbols://skills/project-structure` | Project folder structure conventions |
+| `symbols://skills/design-direction` | Modern UI/UX design direction |
+| `symbols://skills/migration-guide` | React/Angular/Vue → Symbols migration |
+| `symbols://skills/v2-to-v3-migration` | DOMQL v2 → v3 changes |
+| `symbols://skills/quickstart` | CLI setup and quickstart |
+| `symbols://reference/spacing-tokens` | Spacing token reference table |
+| `symbols://reference/atom-components` | Built-in primitive components |
+| `symbols://reference/event-handlers` | Event handler reference |
+
+### Prompts
+| Prompt | Description |
+|--------|-------------|
+| `symbols_component_prompt` | Template for component generation |
+| `symbols_migration_prompt` | Template for framework migration |
+| `symbols_project_prompt` | Template for project scaffolding |
+| `symbols_review_prompt` | Template for code review |
+
+---
+
+## Installation
+
+### Quick Start (No API Keys Required!)
+
+1. **Clone the repository**:
+```bash
+git clone https://github.com/baronsilver/symbols-mcp-server.git
+cd symbols-mcp-server
+```
+
+2. **Install dependencies**:
+```bash
+pip install uv
+uv sync
+npm i @symbo.ls/cli -g
+smbls create your-project
+```
+IMPORTANT: For now, delete the docs folder inside your project folder after creation
+
+3. **Configure**:
+```bash
+cp .env.example .env
+# Edit .env and add both:
+# - SYMBOLS_MCP_URL (contact maintainer for public server URL)
+# - LLM_MODEL=google/gemini-3-flash-preview
+```
+
+## Platform Integration
+
+### Claude Code
+
+```bash
+claude mcp add symbols-mcp -- uv run --directory C:\repos\symbols-mcp-server symbols-mcp
+```
+
+Or manually edit `~/UserName/.claude.json`:
+```json
+{
+  "mcpServers": {
+    "symbols-mcp": {
+      "command": "python",
+      "args": [
+        "-m",
+        "uv",
+        "run",
+        "--directory",
+        "C:\\repos\\symbols-mcp-server",
+        "symbols-mcp"
+      ]
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to your Cursor MCP settings (`.cursor/mcp.json` in your project or global settings):
+
+```json
+{
+  "mcpServers": {
+    "symbols-mcp": {
+      "command": "python",
+      "args": [
+        "-m",
+        "uv",
+        "run",
+        "--directory",
+        "C:\\repos\\symbols-mcp-server",
+        "symbols-mcp"
+      ]
+    }
+  }
+}
+```
+
+### Windsurf
+
+Add to `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "symbols-mcp": {
+      "command": "python",
+      "args": [
+        "-m",
+        "uv",
+        "run",
+        "--directory",
+        "C:\\repos\\symbols-mcp-server",
+        "symbols-mcp"
+      ]
+    }
+  }
+}
+```
+
+
+## Development
+
+Restart your platforms after updating the MCP settings. Once loaded, it should automatically run the MCP. Ask your AI to do the quick test with the MCP to see if it works properly.
+
+---
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `OPENROUTER_API_KEY` | **Yes** | — | API key for OpenRouter (powers AI generation) |
+| `SUPABASE_URL` | No | — | Supabase project URL for vector search |
+| `SUPABASE_KEY` | No | — | Supabase service role key |
+| `LLM_MODEL` | No | `openai/gpt-4.1-mini` | AI model to use via OpenRouter |
+| `SYMBOLS_SKILLS_DIR` | No | `./symbols_mcp/skills` | Path to skills markdown files |
+
+---
+
+## Architecture
+
+```
+symbols-mcp-server/
+├── pyproject.toml              # Project config and dependencies
+├── .env.example                # Environment variable template
+├── README.md                   # This file
+└── symbols_mcp/
+    ├── __init__.py
+    ├── server.py               # MCP server with tools, resources, prompts
+    └── skills/                 # Bundled Symbols knowledge base
+        ├── CLAUDE.md           # DOMQL v3 complete reference
+        ├── SYMBOLS_LOCAL_INSTRUCTIONS.md  # Project structure rules
+        ├── DESIGN_DIRECTION.md # UI/UX design direction
+        ├── MIGRATE_TO_SYMBOLS.md # Framework migration guide
+        ├── DOMQL_v2-v3_MIGRATION.md # v2→v3 changes
+        └── QUICKSTART.md       # CLI quickstart
+```
+
+The server reads skills files at startup and uses them as context for all AI-powered tools.
+When Supabase is configured, the `search_symbols_docs` tool also queries the vector database
+for additional documentation matches.
+
+---
+
+

package/mcp.json

@@ -0,0 +1,57 @@
+{
+  "name": "symbols-mcp",
+  "version": "1.0.0",
+  "description": "AI-powered assistant for the Symbols design-system framework. Generates DOMQL v3 components, pages, and full projects; converts React/Angular/Vue code to Symbols; searches Symbols documentation; and provides comprehensive framework reference.",
+  "author": "baronsilver",
+  "license": "MIT",
+  "homepage": "https://github.com/baronsilver/symbols-mcp-server",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/baronsilver/symbols-mcp-server.git"
+  },
+  "capabilities": {
+    "tools": [
+      {
+        "name": "generate_component",
+        "description": "Generate a Symbols/DOMQL v3 component from a natural-language description"
+      },
+      {
+        "name": "generate_page",
+        "description": "Generate a Symbols/DOMQL v3 page with routing support"
+      },
+      {
+        "name": "generate_project",
+        "description": "Generate a complete multi-file Symbols/DOMQL v3 project structure"
+      },
+      {
+        "name": "convert_to_symbols",
+        "description": "Convert React, Angular, Vue, or HTML code to Symbols/DOMQL v3 format"
+      },
+      {
+        "name": "search_symbols_docs",
+        "description": "Search the Symbols documentation knowledge base for relevant information"
+      },
+      {
+        "name": "explain_symbols_concept",
+        "description": "Explain a Symbols/DOMQL concept with examples (state, routing, events, design tokens, etc.)"
+      },
+      {
+        "name": "review_symbols_code",
+        "description": "Review Symbols/DOMQL code for correctness, best practices, and v3 compliance"
+      },
+      {
+        "name": "create_design_system",
+        "description": "Generate Symbols design system files (colors, spacing, typography, theme, icons)"
+      }
+    ],
+    "resources": 9,
+    "prompts": 4
+  },
+  "installation": {
+    "command": "python",
+    "args": ["-m", "uv", "run", "--directory", "{INSTALL_DIR}", "symbols-mcp"],
+    "env": {
+      "OPENROUTER_API_KEY": "required"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@symbo.ls/mcp",
+  "version": "1.0.0",
+  "description": "An MCP (Model Context Protocol) server that exposes the Symbols/DOMQL v3 AI assistant capabilities to any MCP-compatible platform — **Cursor**, **Claude Code**, **Windsurf**, and more.",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/symbo-ls/symbols-mcp-server.git"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "bugs": {
+    "url": "https://github.com/symbo-ls/symbols-mcp-server/issues"
+  },
+  "homepage": "https://github.com/symbo-ls/symbols-mcp-server#readme"
+}

package/pyproject.toml

@@ -0,0 +1,25 @@
+[project]
+name = "symbols-mcp-server"
+version = "1.0.0"
+description = "MCP server for the Symbols AI assistant - provides DOMQL/Symbols code generation, migration, and documentation tools"
+requires-python = ">=3.10"
+dependencies = [
+    "mcp[cli]>=1.9.0",
+    "httpx[http2]>=0.27.0",
+    "python-dotenv>=1.0.0",
+    "pydantic>=2.0.0",
+    "fastapi>=0.104.0",
+    "uvicorn[standard]>=0.24.0",
+    "flask>=3.0.0",
+    "flask-cors>=4.0.0",
+]
+
+[project.scripts]
+symbols-mcp = "symbols_mcp.server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["symbols_mcp"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

package/railway.toml

@@ -0,0 +1,26 @@
+[build]
+builder = "NIXPACKS"
+nixpacksPlan = { providers = ["python"] }
+
+[deploy]
+startCommand = "python -m symbols_mcp.server"
+healthcheckPath = "/health"
+healthcheckTimeout = 100
+restartPolicyType = "ON_FAILURE"
+restartPolicyMaxRetries = 10
+
+[[services]]
+name = "symbols-mcp"
+source = "."
+
+[services.variables]
+PORT = "8080"
+PYTHON_VERSION = "3.11"
+RAILWAY_ENVIRONMENT = "production"
+
+# Environment variables should be set in Railway dashboard
+# Do not reference them here to avoid secret detection
+
+[[services.ports]]
+port = 8080
+protocol = "HTTP"

package/run.sh

@@ -0,0 +1,17 @@
+#!/bin/bash
+# Wrapper script for running symbols-mcp server
+
+# Check if Python is available
+if ! command -v python &> /dev/null; then
+    echo "Error: Python is not installed"
+    exit 1
+fi
+
+# Check if uv is available
+if ! command -v uv &> /dev/null; then
+    echo "Installing uv..."
+    pip install uv
+fi
+
+# Run the MCP server
+exec python -m uv run symbols-mcp

package/symbols_mcp/__init__.py

@@ -0,0 +1 @@
+# Symbols MCP Server