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

2. 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

3. 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:

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

---