The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Symbols MCP listing page.
mcp-name: io.github.symbo-ls/symbols-mcp
MCP server for Symbols.app — provides documentation search, code generation, conversion, auditing, project management, publishing/deployment, and CLI/SDK reference tools for AI coding assistants (Cursor, Claude Code, Windsurf, claude.ai, etc.).
Targets the modern smbls stack — flat element API, signal-based reactivity, declarative fetch: (@symbo.ls/fetch), polyglot translations (@symbo.ls/polyglot), helmet metadata (@symbo.ls/helmet), SPA routing via el.router(...), theme via @symbo.ls/scratch, and SSR via @symbo.ls/brender.
No API keys required for documentation tools. Project management tools require a Symbols account (login or API key).
| Tool | Description |
|---|---|
get_project_context | CALL FIRST. Walks up from cwd to find symbols.json, returns owner, key, dir, bundler, sharedLibraries, brender, env_type (local/cdn/json_runtime/remote_server), env_evidence, env_guidance, token_present, and a next_step hint telling the agent what to do (ask user, log in, or proceed). Replaces the older detect_environment for new code. |
get_project_rules | Mandatory ruleset. No arguments → compact CORE bundle (reuse directive + RULES essentials + every STRICT rule + frankability checklist + section index + next-step table, <80K chars — fits every client's tool-output cap). section="SYNTAX" (or COMPONENTS, FRANKABILITY, RULES + part=N, … 16 sections) fetches one section per call. full=true → legacy ~590K one-shot (capless clients only). Call before any code generation task. |
get_cli_reference | Complete Symbols CLI (@symbo.ls/cli) command reference. |
get_sdk_reference | Complete Symbols SDK (@symbo.ls/sdk) API reference. |
search_symbols_docs | Keyword search across all bundled Symbols documentation files. |
detect_environment | [Legacy] Caller-supplied flags variant of env classification. Prefer get_project_context. |
| Tool | Description |
|---|---|
generate_component | Generate a DOMQL component from a natural language description. Returns prompt + bundled context (≈300K chars). |
generate_page | Generate a full page with routing, helmet metadata, and declarative fetch: integration. |
convert_react | Convert React/JSX code to Symbols DOMQL (modern smbls stack). |
convert_html | Convert raw HTML/CSS to Symbols DOMQL components. |
convert_to_json | Convert DOMQL JS source to platform JSON (mirrors frank's toJSON pipeline). Use after generate_component / generate_page to feed save_to_project. |
| Tool | Description |
|---|---|
audit_component | Inline VALIDATOR for a single component string. Returns violations + warnings (≈1K chars). Use during generation. Pass include_playbook=True to also dump the AUDIT.md playbook. |
audit_project | Returns the multi-phase project audit PLAYBOOK (instructions for the agent — Phase 0 setup → Phase 5 report). Pair with bin/symbols-audit.cjs CLI for the static-audit phase. |
For filesystem-wide audits the package ships a CLI: npx -y @symbo.ls/mcp symbols-audit <symbols-dir> (strict by default, exit 1 on findings). Under the hood it runs frank-audit audit --strict — the audit core is now @symbo.ls/frank-audit, the AST-based engine that owns the canonical 59-rule registry, prescription generation, and verify-or-rollback fixers.
lib/audit.js is preserved as a backward-compat shim that delegates to frank-audit (subprocess CLI, or the /audit-content HTTP endpoint when FRANK_AUDIT_URL is set). The legacy programmatic API stays callable for non-CLI consumers (the @symbo.ls/cli, the MCP HTTP worker, web/edge clients):
Findings drift vs the old regex output is expected and correct — frank-audit detects more issues with higher accuracy. Field names stay the same (file, line, rule, severity, category, snippet, suggested_fix). To inspect the rule registry, query frank-audit directly: npx frank-audit explain <id>.
| Tool | Description |
|---|---|
login | Log in to Symbols platform — returns a JWT token. |
list_projects | List the user's projects (names, keys, IDs) to choose from. |
create_project | Create a new Symbols project on the platform. |
get_project | Get a project's current data (components, pages, design system, state). |
save_to_project | Save components/pages/data to a project — creates a new version with change tuples, granular changes, orders, and auto-generated schema entries. |
publish | Publish a version (make it live). |
push | Deploy a project to an environment (production, staging, dev). |
| URI | Description |
|---|---|
symbols://skills/framework | Authoritative framework reference — project structure, plugins, theming, SSR, publish pipeline (mirrors smbls/FOR_MCP.md) |
symbols://skills/rules | 62 strict rules for AI agents working in Symbols/DOMQL projects |
symbols://skills/syntax | Complete DOMQL syntax language reference (flat API, signal reactivity) |
symbols://skills/modern-stack | Modern smbls stack — fetch, polyglot, helmet (full metadata catalog), router, scratch theme runtime, brender SSR |
symbols://skills/components | DOMQL component reference (flat props on element, flat onX events) |
symbols://skills/project-structure | Project folder structure and file conventions |
symbols://skills/shared-libraries | sharedLibraries pattern — config, runtime merge, precedence |
symbols://skills/design-system | Design system contract + token catalog (colors, theme, typography, spacing, etc.) |
symbols://skills/design | UI/UX direction + design-to-code translator + 7 specialist personas (consolidated) |
symbols://skills/patterns | UI patterns, accessibility, AI optimization |
symbols://skills/migration | Migration guide for legacy projects + React/Angular/Vue → Symbols |
symbols://skills/audit | Full audit playbook (Phase 0–5, executable end-to-end) |
symbols://skills/common-mistakes | Wrong vs correct DOMQL patterns with zero-tolerance enforcement |
symbols://skills/frankability | Patterns that survive frank.toJSON — every @symbo.ls/frank-audit rule with wrong vs canonical examples |
symbols://skills/learnings | Framework internals, technical gotchas, deep runtime knowledge |
symbols://skills/cookbook | Cookbook of small reactive recipes (toggle, fetch, modal, tabs, etc.) |
symbols://skills/snippets | Production-ready component snippets (nav, hero, pricing card, footer, etc.) |
symbols://skills/default-project | Default starter — library catalog (127+ components) + pre-configured design system tokens |
symbols://skills/default-components | Complete source code of 130+ default template components (heavy reference, on demand) |
symbols://skills/running-apps | 4 ways to run Symbols apps (local, CDN, JSON, remote) |
symbols://skills/cli | Symbols CLI (@symbo.ls/cli) complete command reference |
symbols://skills/sdk | Symbols SDK (@symbo.ls/sdk) complete API reference |
| URI | Description |
|---|---|
symbols://reference/spacing-tokens | Spacing token table (golden-ratio scale) |
symbols://reference/atom-components | Built-in atom/primitive components |
symbols://reference/event-handlers | Event handler signatures and patterns |
| Prompt | Description |
|---|---|
symbols_component_prompt | Generate a component from a description |
symbols_migration_prompt | Migrate code from React/Angular/Vue |
symbols_project_prompt | Scaffold a complete project |
symbols_review_prompt | Review code for compliance |
symbols_convert_html_prompt | Convert HTML/CSS to DOMQL |
symbols_design_review_prompt | Visual/design audit against the design system |
Two commands and a one-line config — works for every major MCP client.
Pick whichever runtime you have:
The standard MCP config snippet (works for Claude Code, Claude Desktop, Cursor, Windsurf, Cline, Continue, Zed, Goose, Gemini CLI — wrap it in whatever shape that editor expects):
--refresh pulls the latest from PyPI on every launch (~1–2s startup tax — drop it for pinned/offline runs).
In your editor's chat, ask the assistant:
Use
symbols-mcpto callget_project_rules, then summarize the modern stack rules.
If that returns a long ruleset, you're set. Try audit_component on a deliberately broken snippet to confirm Rule 62 (the banned inline-SVG-for-icon rule) fires.
Once symbols-mcp is configured in your editor, drop project-level rule files so every editor auto-loads the framework rules on every chat:
Writes CLAUDE.md, .cursor/rules/symbols.md, .windsurfrules, .clinerules, and AGENTS.md — each tailored to its editor, all pointing at the symbols-mcp tools (get_project_context, get_project_rules, generate_component, audit_component, etc.). Idempotent; pass --force to overwrite or --only=cursor,claude to scope.
The wrangler-style path: detect which AI coding agents are installed (Claude Code, Cursor, Codex, GitHub Copilot, Gemini CLI, Windsurf, Cline, Goose, Warp, Antigravity, Zed, Aider) and install the Symbols rules + skills for exactly those:
For Claude Code this also installs a proper agent skill at .claude/skills/symbols/SKILL.md — it auto-loads whenever the agent works on Symbols/DOMQL (its description triggers on symbols.json projects, DOMQL components, design tokens, the smbls CLI), carrying the must-do tool sequence and the hard-rules digest. --global installs it once at ~/.claude/skills/ for every project; --no-skills opts out.
Combined with the MCP server's instructions field (auto-loaded on connect by every MCP-aware editor — Claude Code, Cursor, GitHub Copilot, Windsurf, Cline, Continue, Roo, Zed, Goose, Gemini CLI, Codex, Antigravity, Cody), this means you never have to remind the agent to "use symbols-mcp" — the workflow is bootstrapped on first interaction.
Project-level rule files (CLAUDE.md, AGENTS.md, etc.) are best-effort — long contexts dilute them and the agent can drift. For Claude Code, init-rules also installs a hooks layer that the harness enforces directly:
| Hook | Trigger | What it does |
|---|---|---|
symbols-mcp-require.sh | PreToolUse Edit|Write|MultiEdit | BLOCKS Edit/Write on *.js/*.ts/*.tsx inside any directory tree containing symbols.json, until the session has called mcp__symbols-mcp__get_project_rules (or get_project_context/generate_component/audit_component). |
symbols-mcp-reminder.sh | UserPromptSubmit | Injects the MUST-DO sequence + frankability FA-rule cheatsheet on every turn when cwd is inside a Symbols project. Per-turn injection isn't diluted by long contexts the way CLAUDE.md is. |
symbols-mcp-audit.sh | PostToolUse Edit|Write|MultiEdit | After every JS edit inside a Symbols project, runs frank-audit plus an inline FA-rule pattern check (FA101/102/103/105/106/206/207/513/514) and surfaces violations back to Claude. |
Files installed:
Skip hooks: npx -y @symbo.ls/mcp init-rules --no-hooks.
Disable a single hook at runtime: SYMBOLS_MCP_REQUIRE_RULES=0, SYMBOLS_MCP_REMINDER=0, SYMBOLS_MCP_POST_AUDIT=0.
Hooks require bash and jq on PATH (already standard on macOS / most Linux distros). frank-audit is invoked via npx -y --no-install @symbo.ls/frank-audit — if not installed, the inline pattern check still runs.
See SETUP.md → Bootstrapping for the layered model and verification steps.
/symbols-audit?The /symbols-audit slash command is Claude Code-only, but the underlying capability works in every MCP-aware editor — Cursor, GitHub Copilot, Windsurf, Cline, Continue, Roo, Zed, Goose, Gemini CLI, Codex, Antigravity (Google), Cody, Claude.ai web, and any custom MCP client.
Three patterns:
get_project_context → audit_project (playbook) → bin/symbols-audit.cjs CLI → iterates fixes with audit_component.npx -y @symbo.ls/mcp symbols-audit ./symbols works from any terminal, no editor needed. Strict by default, exit 1 on findings.See SETUP.md for:
.mcp.json template/symbols-audit & other tools in non-Claude-Code editors: natural language, custom commands per editor, shell fallback, sourcing the bundled venv directlybin/symbols-audit.cjs for CI / pre-commit