symbols-mcp

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

Tools

Context — start here

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`	Bundled mandatory ruleset (FRAMEWORK + DESIGN_SYSTEM + RULES + DEFAULT_PROJECT, ≈180K chars). 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`.

Generation & conversion

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

Audit

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

const {
  auditContent,         // audit one component string (delegates to frank-audit)
  auditFiles,           // audit a list of {path, content}
  auditDirectory,       // walk a symbols/ dir via `frank-audit audit <dir>`
  mergeFindings,        // preserve status across runs
  summarize,            // breakdown by severity / category / origin
} = require('@symbo.ls/mcp/lib/audit')

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

Project Management & Publishing

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

End-to-End Flow (from any MCP client)

1. get_project_context  → resolve owner/key/env/auth state from cwd's symbols.json
2. generate_component   → JS source code
3. audit_component      → inline check (saves a roundtrip if violations exist)
4. convert_to_json      → platform JSON
5. login                → only if token_present was false in step 1
6. create_project       → (if new project needed)
   list_projects        → (or pick existing)
7. save_to_project      → push JSON to platform (creates version)
8. publish              → make version live
7. push                → deploy to environment

Resources

Skills (documentation)

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

Reference (inline)

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

Prompts

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

Quickstart

Two commands and a one-line config — works for every major MCP client.

1. Install

Pick whichever runtime you have:

uvx symbols-mcp           # uv  — recommended, zero install
pip install symbols-mcp   # pip — global binary
npx -y @symbo.ls/mcp      # npm — Node-friendly wrapper

2. Configure your editor

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

{
  "mcpServers": {
    "symbols-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--refresh", "symbols-mcp"]
    }
  }
}

--refresh pulls the latest from PyPI on every launch (~1–2s startup tax — drop it for pinned/offline runs).

3. Verify

In your editor's chat, ask the assistant:

Use symbols-mcp to call get_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.

Auto-bootstrapping a Symbols project — no more "use symbols-mcp" reminders

Once symbols-mcp is configured in your editor, drop project-level rule files so every editor auto-loads the framework rules on every chat:

# from your Symbols project root
npx -y @symbo.ls/mcp init-rules

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.

Agent skills — one-shot install for every agent on your machine

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:

npx -y @symbo.ls/mcp skills          # detect agents → install rules + skills for them
# equivalent: npx -y @symbo.ls/mcp init-rules --detect
# from the Symbols CLI: smbls skills

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.

Claude Code: enforcement hooks (installed by default)

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:

.claude/settings.json                       # wires the three hooks
.claude/hooks/symbols-mcp-require.sh        # PreToolUse  — block edit until rules loaded
.claude/hooks/symbols-mcp-reminder.sh       # UserPromptSubmit — inject directive
.claude/hooks/symbols-mcp-audit.sh          # PostToolUse — frank-audit + FA-rule check

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.

What about `/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:

Natural language (zero setup) — just say "Run a full Symbols audit on this project using symbols-mcp." The agent calls get_project_context → audit_project (playbook) → bin/symbols-audit.cjs CLI → iterates fixes with audit_component.
Custom command — register a Cursor rule, Continue customCommand, Windsurf workflow, etc. for one-keystroke parity. Templates in SETUP.md.
Pure shell — npx -y @symbo.ls/mcp symbols-audit ./symbols works from any terminal, no editor needed. Strict by default, exit 1 on findings.

Full setup guide

See SETUP.md for:

Per-editor configs: Claude Code · Claude Desktop · Claude.ai (web) · Cursor · GitHub Copilot (VS Code / CLI) · Windsurf · Zed · Cline · Continue · Roo · Cody · Gemini CLI · OpenAI Codex · Goose · Antigravity · generic clients
Per-tool quick-starts with workspace connection (s1m0ne Bridge + MCP + rules): docs.symbols.app/simone
Local development: clone the repo, run from source, .mcp.json template
Using /symbols-audit & other tools in non-Claude-Code editors: natural language, custom commands per editor, shell fallback, sourcing the bundled venv directly
Transport modes: stdio (default) and SSE (for claude.ai web / remote clients)
Audit CLI: standalone bin/symbols-audit.cjs for CI / pre-commit
Updating and Troubleshooting (PATH issues, stale versions, missing tools)

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

symbols_mcp-3.14.749.tar.gz (447.3 kB view details)

Uploaded Aug 9, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

symbols_mcp-3.14.749-py3-none-any.whl (343.4 kB view details)

Uploaded Aug 9, 2026 Python 3

File details

Details for the file symbols_mcp-3.14.749.tar.gz.

File metadata

Download URL: symbols_mcp-3.14.749.tar.gz
Upload date: Aug 9, 2026
Size: 447.3 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: uv/0.12.3 {"installer":{"name":"uv","version":"0.12.3","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for symbols_mcp-3.14.749.tar.gz
Algorithm	Hash digest
SHA256	`e051f93bd40ea039cd767098fd79eca43b14cbcf1259c268c9095b7d62585069`
MD5	`c5172730e9aeaa3e17cedadfdb44e41b`
BLAKE2b-256	`8785315647e5aceb581085188bd16bedf43971b4e4794b88482bf36083883f7c`

See more details on using hashes here.

File details

Details for the file symbols_mcp-3.14.749-py3-none-any.whl.

File metadata

Download URL: symbols_mcp-3.14.749-py3-none-any.whl
Upload date: Aug 9, 2026
Size: 343.4 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: uv/0.12.3 {"installer":{"name":"uv","version":"0.12.3","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for symbols_mcp-3.14.749-py3-none-any.whl
Algorithm	Hash digest
SHA256	`d3b181fff523059bd28a3214a18bb06379090d2b1c0dfde4d53b2d65809e4942`
MD5	`eb48bf3cc715e3d4243eb2cd7d2b1b88`
BLAKE2b-256	`0a33abfcf790444aedf0476720146096139799c89e0a009ca444e0f6b68cd135`