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

Generation & conversion

Audit

For filesystem-wide audits the package ships a CLI: npx -y -p @symbo.ls/mcp symbols-audit <symbols-dir> (strict by default, exit 1 on findings). -p names the package and runs its symbols-audit bin; every release supports it. The short form npx -y @symbo.ls/mcp symbols-audit <symbols-dir> (and npx -y @symbo.ls/mcp init-rules) needs a release with the package's mcp bin — on an older one npx answers "could not determine executable to run"; use npx -y -p @symbo.ls/mcp symbols-audit / npx -y -p @symbo.ls/mcp symbols-mcp-init-rules there. 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

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)

Reference (inline)

Prompts

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:

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:

1. 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.
2. Custom command — register a Cursor rule, Continue customCommand, Windsurf workflow, etc. for one-keystroke parity. Templates in SETUP.md.
3. Pure shell — npx -y -p @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](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)