symbols-mcp

# symbols-mcp

mcp-name: io.github.symbo-ls/symbols-mcp

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

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

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

```js
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:

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

```json
{
  "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.

-