symbols-mcp-server

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:

git clone https://github.com/baronsilver/symbols-mcp-server.git
cd symbols-mcp-server

1. Install dependencies:

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

1. Configure:

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

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):

{
  "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:

{
  "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.

---