{
  "markdown": "# symbols-mcp\n\nmcp-name: io.github.symbo-ls/symbols-mcp\n\nMCP server for [Symbols.app](https://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.).\n\nTargets 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`.\n\nNo API keys required for documentation tools. Project management tools require a Symbols account (login or API key).\n\n---\n\n## Tools\n\n### Context — start here\n\n| Tool | Description |\n|------|-------------|\n| `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. |\n| `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. |\n| `get_cli_reference` | Complete Symbols CLI (`@symbo.ls/cli`) command reference. |\n| `get_sdk_reference` | Complete Symbols SDK (`@symbo.ls/sdk`) API reference. |\n| `search_symbols_docs` | Keyword search across all bundled Symbols documentation files. |\n| `detect_environment` | _[Legacy]_ Caller-supplied flags variant of env classification. Prefer `get_project_context`. |\n\n### Generation & conversion\n\n| Tool | Description |\n|------|-------------|\n| `generate_component` | Generate a DOMQL component from a natural language description. Returns prompt + bundled context (≈300K chars). |\n| `generate_page` | Generate a full page with routing, helmet metadata, and declarative `fetch:` integration. |\n| `convert_react` | Convert React/JSX code to Symbols DOMQL (modern smbls stack). |\n| `convert_html` | Convert raw HTML/CSS to Symbols DOMQL components. |\n| `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`. |\n\n### Audit\n\n| Tool | Description |\n|------|-------------|\n| `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. |\n| `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. |\n\nFor 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`](https://github.com/symbo-ls/smbls/tree/main/plugins/frank-audit), the AST-based engine that owns the canonical 59-rule registry, prescription generation, and verify-or-rollback fixers.\n\n`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):\n\n```js\nconst {\n  auditContent,         // audit one component string (delegates to frank-audit)\n  auditFiles,           // audit a list of {path, content}\n  auditDirectory,       // walk a symbols/ dir via `frank-audit audit <dir>`\n  mergeFindings,        // preserve status across runs\n  summarize,            // breakdown by severity / category / origin\n} = require('@symbo.ls/mcp/lib/audit')\n```\n\nFindings 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>`.\n\n### Project Management & Publishing\n\n| Tool | Description |\n|------|-------------|\n| `login` | Log in to Symbols platform — returns a JWT token. |\n| `list_projects` | List the user's projects (names, keys, IDs) to choose from. |\n| `create_project` | Create a new Symbols project on the platform. |\n| `get_project` | Get a project's current data (components, pages, design system, state). |\n| `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. |\n| `publish` | Publish a version (make it live). |\n| `push` | Deploy a project to an environment (production, staging, dev). |\n\n### End-to-End Flow (from any MCP client)\n\n```\n1. get_project_context  → resolve owner/key/env/auth state from cwd's symbols.json\n2. generate_component   → JS source code\n3. audit_component      → inline check (saves a roundtrip if violations exist)\n4. convert_to_json      → platform JSON\n5. login                → only if token_present was false in step 1\n6. create_project       → (if new project needed)\n   list_projects        → (or pick existing)\n7. save_to_project      → push JSON to platform (creates version)\n8. publish              → make version live\n7. push                → deploy to environment\n```\n\n## Resources\n\n### Skills (documentation)\n\n| URI | Description |\n|-----|-------------|\n| `symbols://skills/framework` | **Authoritative framework reference** — project structure, plugins, theming, SSR, publish pipeline (mirrors `smbls/FOR_MCP.md`) |\n| `symbols://skills/rules` | 62 strict rules for AI agents working in Symbols/DOMQL projects |\n| `symbols://skills/syntax` | Complete DOMQL syntax language reference (flat API, signal reactivity) |\n| `symbols://skills/modern-stack` | Modern smbls stack — fetch, polyglot, helmet (full metadata catalog), router, scratch theme runtime, brender SSR |\n| `symbols://skills/components` | DOMQL component reference (flat props on element, flat onX events) |\n| `symbols://skills/project-structure` | Project folder structure and file conventions |\n| `symbols://skills/shared-libraries` | sharedLibraries pattern — config, runtime merge, precedence |\n| `symbols://skills/design-system` | Design system contract + token catalog (colors, theme, typography, spacing, etc.) |\n| `symbols://skills/design` | UI/UX direction + design-to-code translator + 7 specialist personas (consolidated) |\n| `symbols://skills/patterns` | UI patterns, accessibility, AI optimization |\n| `symbols://skills/migration` | Migration guide for legacy projects + React/Angular/Vue → Symbols |\n| `symbols://skills/audit` | Full audit playbook (Phase 0–5, executable end-to-end) |\n| `symbols://skills/common-mistakes` | Wrong vs correct DOMQL patterns with zero-tolerance enforcement |\n| `symbols://skills/frankability` | Patterns that survive `frank.toJSON` — every `@symbo.ls/frank-audit` rule with wrong vs canonical examples |\n| `symbols://skills/learnings` | Framework internals, technical gotchas, deep runtime knowledge |\n| `symbols://skills/cookbook` | Cookbook of small reactive recipes (toggle, fetch, modal, tabs, etc.) |\n| `symbols://skills/snippets` | Production-ready component snippets (nav, hero, pricing card, footer, etc.) |\n| `symbols://skills/default-project` | Default starter — library catalog (127+ components) + pre-configured design system tokens |\n| `symbols://skills/default-components` | Complete source code of 130+ default template components (heavy reference, on demand) |\n| `symbols://skills/running-apps` | 4 ways to run Symbols apps (local, CDN, JSON, remote) |\n| `symbols://skills/cli` | Symbols CLI (`@symbo.ls/cli`) complete command reference |\n| `symbols://skills/sdk` | Symbols SDK (`@symbo.ls/sdk`) complete API reference |\n\n### Reference (inline)\n\n| URI | Description |\n|-----|-------------|\n| `symbols://reference/spacing-tokens` | Spacing token table (golden-ratio scale) |\n| `symbols://reference/atom-components` | Built-in atom/primitive components |\n| `symbols://reference/event-handlers` | Event handler signatures and patterns |\n\n## Prompts\n\n| Prompt | Description |\n|--------|-------------|\n| `symbols_component_prompt` | Generate a component from a description |\n| `symbols_migration_prompt` | Migrate code from React/Angular/Vue |\n| `symbols_project_prompt` | Scaffold a complete project |\n| `symbols_review_prompt` | Review code for compliance |\n| `symbols_convert_html_prompt` | Convert HTML/CSS to DOMQL |\n| `symbols_design_review_prompt` | Visual/design audit against the design system |\n\n---\n\n## Quickstart\n\nTwo commands and a one-line config — works for every major MCP client.\n\n### 1. Install\n\nPick whichever runtime you have:\n\n```bash\nuvx symbols-mcp           # uv  — recommended, zero install\npip install symbols-mcp   # pip — global binary\nnpx -y @symbo.ls/mcp      # npm — Node-friendly wrapper\n```\n\n### 2. Configure your editor\n\nThe 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):\n\n```json\n{\n  \"mcpServers\": {\n    \"symbols-mcp\": {\n      \"type\": \"stdio\",\n      \"command\": \"uvx\",\n      \"args\": [\"--refresh\", \"symbols-mcp\"]\n    }\n  }\n}\n```\n\n`--refresh` pulls the latest from PyPI on every launch (~1–2s startup tax — drop it for pinned/offline runs).\n\n### 3. Verify\n\nIn your editor's chat, ask the assistant:\n\n> Use `symbols-mcp` to call `get_project_rules`, then summarize the modern stack rules.\n\nIf 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.\n\n---\n\n## Auto-bootstrapping a Symbols project — no more \"use symbols-mcp\" reminders\n\nOnce `symbols-mcp` is configured in your editor, drop project-level rule files so every editor auto-loads the framework rules on every chat:\n\n```bash\n# from your Symbols project root\nnpx -y @symbo.ls/mcp init-rules\n```\n\nWrites `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.\n\n### Agent skills — one-shot install for every agent on your machine\n\nThe 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:\n\n```bash\nnpx -y @symbo.ls/mcp skills          # detect agents → install rules + skills for them\n# equivalent: npx -y @symbo.ls/mcp init-rules --detect\n# from the Symbols CLI: smbls skills\n```\n\nFor 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.\n\nCombined 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.\n\n### Claude Code: enforcement hooks (installed by default)\n\nProject-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:\n\n| Hook | Trigger | What it does |\n|---|---|---|\n| `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`). |\n| `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. |\n| `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. |\n\nFiles installed:\n\n```\n.claude/settings.json                       # wires the three hooks\n.claude/hooks/symbols-mcp-require.sh        # PreToolUse  — block edit until rules loaded\n.claude/hooks/symbols-mcp-reminder.sh       # UserPromptSubmit — inject directive\n.claude/hooks/symbols-mcp-audit.sh          # PostToolUse — frank-audit + FA-rule check\n```\n\nSkip hooks: `npx -y @symbo.ls/mcp init-rules --no-hooks`.\nDisable a single hook at runtime: `SYMBOLS_MCP_REQUIRE_RULES=0`, `SYMBOLS_MCP_REMINDER=0`, `SYMBOLS_MCP_POST_AUDIT=0`.\n\nHooks 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.\n\nSee [SETUP.md → Bootstrapping](SETUP.md#bootstrapping-a-new-symbols-project--auto-load-rules-in-every-editor) for the layered model and verification steps.\n\n---\n\n## What about `/symbols-audit`?\n\nThe `/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.\n\nThree patterns:\n\n1. **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`.\n2. **Custom command** — register a Cursor rule, Continue customCommand, Windsurf workflow, etc. for one-keystroke parity. Templates in [SETUP.md](SETUP.md#using-symbols-audit-and-other-tools-in-any-editor).\n3. **Pure shell** — `npx -y @symbo.ls/mcp symbols-audit ./symbols` works from any terminal, no editor needed. Strict by default, exit 1 on findings.\n\n---\n\n## Full setup guide\n\n**See [SETUP.md](SETUP.md)** for:\n\n- **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\n- **Per-tool quick-starts with workspace connection** (s1m0ne Bridge + MCP + rules): [docs.symbols.app/simone](https://docs.symbols.app/simone)\n- **Local development:** clone the repo, run from source, `.mcp.json` template\n- **Using `/symbols-audit` & other tools in non-Claude-Code editors:** natural language, custom commands per editor, shell fallback, sourcing the bundled venv directly\n- **Transport modes:** stdio (default) and SSE (for claude.ai web / remote clients)\n- **Audit CLI:** standalone `bin/symbols-audit.cjs` for CI / pre-commit\n- **Updating** and **Troubleshooting** (PATH issues, stale versions, missing tools)\n",
  "bytes": 16134,
  "sha": "c3d9a0ee381b470b7d166f66fb0eae29c584022b31cd2463e3080a4eec22f522",
  "repo_slug": "symbo-ls/symbols-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_symbo_ls_symbols_mcp_a9f4b4d3/readme"
}