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

---