# Symbols MCP [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/symbo-ls/symbols-mcp  
**GitHub Stars:** 1  
**npm Downloads (last month):** 3005  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/symbols-mcp

## Description
MCP server for Symbols.app — documentation search and framework reference

## Tools
Capabilities this server exposes over MCP:

- **get_project_rules** — ALWAYS call this first before any generate_* tool. No arguments → the compact CORE bundle of the mandatory Symbols.app rules (RULES essentials + every STRICT rule + frankability checklist + SECTION INDEX + NEXT STEP table; under 80k chars so it fits every client tool-output cap). Then fetch sections one call each: section="SYNTAX", "COMPONENTS", "FRANKABILITY", "RULES" + part=N (16 sections; unknown names error with the valid list). full=true → legacy ~590k one-shot, capless clients only. Violations cause silent failures — black page, nothing renders.
- **search_symbols_docs** — Search the Symbols documentation knowledge base for relevant information including CLI commands, SDK services, syntax, components, and more. Ranked by section: option names (camelCase, dotted.paths, snake_case) weigh most and must be present, headings count again; at most two sections per file. Each result: file, section, line, score, snippet.
- **get_cli_reference** — Returns the complete Symbols CLI (@symbo.ls/cli) command reference — all smbls commands, options, and workflows.
- **get_sdk_reference** — Returns the complete Symbols SDK (@symbo.ls/sdk) API reference — all services, methods, and usage examples.
- **generate_component** — Generate a Symbols.app DOMQL v3 component from a description with full context (rules, syntax, cookbook, default library).
- **generate_page** — Generate a Symbols.app page with routing integration and full context.
- **convert_react** — Convert React/JSX code to Symbols.app DOMQL v3 with migration context.
- **convert_html** — Convert raw HTML/CSS to Symbols.app DOMQL v3 components with full context.
- **detect_environment** — Detect project type (local, CDN, JSON runtime, or remote server) based on project indicators.
- **audit_component** — Audit a Symbols/DOMQL file (component, page, function, …) for v3 compliance — checks for v2 syntax, raw px values, hardcoded colors, direct DOM manipulation, and more. Pass file_path so the checks that depend on the file's folder apply where it really lives; without it the code is audited as a component. Also warns on four STRICT shape rules: one condition repeated across 3+ CSS props (Rule 19 — use isX + '.isX'), an interactive element with ':hover' but no ':active' (Rule 65), a state-driven `if:` on an element in flow beside siblings (Rule 66 — keep it mounted, toggle visibility), a built-in Button call site overriding padding / height (Rule 68). Returns violations, warnings, and a score.
- **convert_to_json** — Convert DOMQL v3 JavaScript source code to platform JSON format. Parses export statements, stringifies functions, outputs JSON ready for save_to_project.
- **login** — Log in to the Symbols platform and get an access token for project operations.
- **list_projects** — List the user's Symbols 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 Symbols project. Creates a new version with change tuples, granular changes, orders, and auto-generated schema entries (mirrors CLI push pipeline).
- **publish** — Publish a version of a Symbols project. Makes the specified version (or latest) the published/live version.
- **push** — Deploy a Symbols project to an environment (production, staging, dev).

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "symbols-mcp": {
    "command": "npx",
    "args": ["-y","@symbo.ls/mcp"],
    "env": {
      "FRANK_AUDIT_URL": ""
    }
  }
}
```

**Requires environment variables:** `FRANK_AUDIT_URL` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What Symbols MCP MCP server does

Symbols MCP MCP server exposes Symbols.app capabilities through Model Context Protocol tools. It covers two broad workflows: working with the Symbols framework and managing projects on the Symbols platform. Documentation search and reference tools provide material for the CLI, SDK, DOMQL syntax, framework conventions, project structure, components, design systems, migrations, and auditing.

For implementation work, the server can generate DOMQL components or complete pages. Page generation includes routing, helmet metadata, and declarative `fetch:` integration. Conversion tools accept React or JSX and raw HTML/CSS, then produce Symbols DOMQL. Generated DOMQL can be converted to platform JSON before it is saved to a project.

## How it works

Start by calling `get_project_context`, which searches upward from the current working directory for `symbols.json`. Its result describes project ownership, the project key and directory, bundler details, shared libraries, rendering information, environment classification, and authentication state. It also returns guidance for the next action.

`get_project_rules` supplies the rules needed before generation. The default response is a compact core bundle; individual sections can be requested when more detail is needed. A client can then generate or convert code, run `audit_component`, convert the result to JSON, and use the project tools to store it. `audit_project` returns a multi-phase audit playbook, while the package also provides a command-line filesystem audit.

## Setup and configuration

Documentation and reference tools do not require API keys. Project operations require a Symbols account, using the `login` tool or an API key. The login flow returns a JWT token. After authentication, use `list_projects` to select an existing project or `create_project` to start one. `get_project` reads current project data, and `save_to_project` creates a new version containing the submitted project changes.

The repository also documents a filesystem audit command: `npx -y @symbo.ls/mcp symbols-audit <symbols-dir>`. The audit is strict by default and exits with status 1 when it finds issues. `FRANK_AUDIT_URL` may be used by the audit compatibility layer to delegate to an HTTP audit endpoint.

## Tools and capabilities

The Symbols MCP MCP server includes tools for documentation search, CLI and SDK references, environment detection, component and page generation, React and HTML conversion, JSON conversion, component validation, and project audits. Platform tools cover login, project listing and creation, project retrieval, saving, publishing, and deployment to production, staging, or development environments.

It also exposes Symbols skill and reference resources covering framework behavior, syntax, rules, components, migration, design, runtime options, and related topics. The documented target is the modern smbls stack, including signal-based reactivity, declarative fetching, routing, helmet metadata, theming, and server-side rendering.

## Limitations and notes

`detect_environment` is retained as a legacy caller-supplied variant; new code should prefer `get_project_context`. Some responses are large: generation returns bundled context, and the full rules response is intended for clients without tool-output limits only when explicitly requested. `audit_component` checks one component string, whereas filesystem-wide auditing uses the supplied CLI and the frank-audit engine. Project creation, saving, publishing, and deployment require authentication; documentation tools do not.

_Full upstream README: https://allmcps.com/mcp/symbols-mcp/readme_