Symbols MCP

Apply LLM-generated edit ops to a Symbols project with verify-or-rollback. Pass `ops_json` as a JSON string of either: - { "ops": [...] } - or just an array of op objects. Each op must be one of the 8 strict kinds (see prescribe_frankability_fixes). The applier validates every op, snapshots affected files, applies, runs frank.toJSON to verify, and rolls back if the result regresses against the pre-apply state. Args: symbols_dir: Absolute path to the symbols/ directory. ops_json: JSON string containing the edit ops. Returns: JSON with applied/skipped/rolledBack/baseline/finalState.

Run frank-audit and optionally apply fixes — supports a sampling-driven LLM loop that resolves findings the mechanical fixer can't safely handle. Modes: 'report' — run audit, list findings, do not modify files 'safe-fix' — apply mechanical fixes with verify-or-rollback safety (every applied fix is verified against frank.toJSON; regressions roll back) 'full' — run safe-fix first, THEN drive an LLM loop via MCP sampling over the remaining prescriptions: 1. prescribe_frankability_fixes(dir) → JSON prescriptions 2. for each prescription (capped by max_iterations): a. ctx.session.create_message() with the strict edit-op contract prompt b. parse the LLM's JSON response c. apply_frankability_edit_ops with verify-or-rollback d. one retry on malformed JSON 3. report aggregate (mechanical + LLM fixes) Requires the host to support MCP sampling (Claude Code does; some hosts don't — falls back gracefully to safe-fix mode with a warning when ctx.session is unavailable). Args: symbols_dir: Absolute path to the symbols/ directory. mode: 'report' | 'safe-fix' | 'full' aggressive: With safe-fix or full, also apply medium-confidence fixes. max_iterations: Cap on LLM-driven prescriptions in 'full' mode (default 20). Returns: JSON-stringified result with schema, opId, findings, applied/skipped, rolledBack, baseline, finalState, and (in 'full' mode) llmRounds[].

Inline VALIDATOR for a single Symbols/DOMQL file (component, page, function, …). Runs the @symbo.ls/frank-audit rules (flat element API, signal reactivity, design system tokens, declarative fetch/polyglot/helmet/router, no DOM manipulation, Rule 62 icon ban, …) against an in-memory string of code. Returns a tight report with violations + warnings. It also warns on three 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 built-in Button call site overriding padding / height (Rule 68). Pass `file_path` so the rules that depend on the file's folder apply where the file really lives: a `functions/` file is not a component (no FA903 "exported as a function", no FA009 file-name check), `pages/` files get the page rules, a file outside every frank folder gets FA006. Without it the code is audited as a component, `components/<FirstExport>.js`. Project-level checks (the folder's `index.js` re-exports the file, `context.js` exists) need the whole project and are not reported here — run `bin/symbols-audit <symbols-dir>` for those. Use this: - During generation, to verify a freshly-generated file before saving - In any client without shell access (claude.ai web, hosted MCP) where the CLI is unreachable - On a single file's contents, not a whole project Adjacent tools — call these for different scopes: - `audit_project()` — returns the MULTI-PHASE PROJECT AUDIT PLAYBOOK (instructions for the agent to follow). Use when the user asks for a full project audit. - `bin/symbols-audit <symbols-dir>` (CLI, ships with this package) — the same rules across an entire project. Use during the playbook's static-audit phase. By default returns ONLY the findings (≈1–2K chars). Pass `include_playbook=True` to also dump the AUDIT.md playbook in the same response when you don't already have it. Args: component_code: The JavaScript/DOMQL source string to validate. include_playbook: Append the full audit playbook to the response. Default False to keep responses small. Default agents should NOT set this — call `audit_project()` separately if the playbook is needed. file_path: Where the file lives, relative to the project's symbols folder: 'functions/listQuerySet.js', 'components/SiteCover.js', 'pages/main.js', 'designSystem/color.js', 'app.js', 'state.js'. A folder ('functions/') names the kind and the file takes the name of its first export. An absolute path works too (read against the project's symbols.json `dir`). A file in a lazy route group's folder ('admin/components/AdminTable.js') is audited by its path inside the group. Empty → a component.

Returns the multi-phase PROJECT AUDIT PLAYBOOK (instructions for the agent). Strict mode is the default. Strict means EXHAUSTIVE — the agent does not stop until every finding is `resolved`, `framework_bug` (in framework_audit_results.md), or an active `🟢 ASK USER` block awaiting user input. No finding stays `open`. Two CLI flags (default ON in strict mode, both opt-out via --no-...): - `--deep-fix`: agent does NOT stop at first blocker (missing project key, auth-protected route, missing CLI subcommand). Surfaces ASK-USER blocks or runs documented fallbacks (e.g. publish blocked → local frank+brender preview). - `--deep-framework-audit`: every framework_bug entry includes a Read+Grep trace into smbls/ source identifying the suspected function, plus a suggested patch. Two report files the CLI emits + the agent appends to: - `audit/symbols_audit_results.md` — PROJECT findings + resolutions - `audit/framework_audit_results.md` — FRAMEWORK bugs + repro + smbls/ trace + suggested patch (each entry must be debuggable by someone who's never seen the code; vague "doesn't work" entries are not acceptable in strict mode) Findings have an `origin` field (project | framework | shared) classified by `bin/symbols-audit` heuristically, then refined by the agent during Phase 2. This tool is a **playbook getter**, not an executor. The agent runs the playbook itself using: - `get_project_context` — call FIRST to resolve owner/key/env. Missing values surface as `🟢 ASK USER` blocks (NEVER hardcoded). - `bin/symbols-audit <symbols-dir>` — deterministic regex sweep + dual-report template emission. Strict + deep modes default ON. - `audit_component(code, file_path)` — inline single-file validator (no filesystem). - chrome-mcp tools — for the Phase 3c local-vs-remote UI testing protocol. Phase summary: - Phase 0: setup + baseline metrics + project-context resolution. Missing owner/key resolved here via ASK-USER (not deferred). - Phase 1: static audit via `bin/symbols-audit` (creates findings.json + symbols_audit_results.md + framework_audit_results.md templates). - Phase 2: fix loop with self-test. 3 failed fix attempts → finding becomes framework_bug with deep-audit trace. Continue, never stop on first bug. - Phase 3a: build gates with fallbacks for missing CLI subcommands. - Phase 3b: publish to staging WITH FALLBACK LADDER. If publish is blocked (missing key, AUTH_REQUIRED, env doesn't exist), agent surfaces ASK-USER AND/OR falls back to local `frank to-json` + `brender` + http.server preview so Phase 3c still has a viewable artifact. NEVER silently skip publish. - Phase 3c: STRICT UI testing — local-vs-(remote OR localfallback) side-by-side, click every clickable, icon rendering verification per Rule 62, theme/lang/ active-nav/forms/responsive. - Phase 4: iterate until two consecutive runs converge — zero open findings, zero pending ASK-USER, viewable artifact exists. Deep-fix loop re-visits framework_bug entries to strengthen them and retries blockers. - Phase 5: report = record of resolutions, NOT a TODO list. Strict mode forbids "Recommended follow-up tasks" as a terminal state. Transport awareness: this playbook assumes stdio MCP transport (filesystem access). For SSE/HTTPS/CDN, the agent surfaces filesystem-dependent steps as shell commands the user runs locally, then resumes Phase 2/3 with pasted output. `audit_component` and `audit_project` are stateless and work over any transport; `get_project_context` and `bin/symbols-audit` are stdio-only. Output artifacts created in <project>/audit/: findings.json, symbols_audit_results.md (framework bugs), runs/, report.md. Use this when the user asks to audit, validate, refactor for compliance, or 'make my project publish-ready in one shot'. Returns the entire playbook so the agent has the full context. Pair with the bundled `bin/symbols-audit` CLI for the deterministic regex pass. Args: phase: 'all' (full playbook — default) | '0' | '1' | '2' | '3' | '4' | '5' (just one phase's section)

Convert raw HTML/CSS to Symbols.app DOMQL components. Provide HTML code and receive the conversion context including component catalog, syntax reference, and design system tokens. Args: source_code: The HTML/CSS source code to convert.

Convert React/JSX code to Symbols.app DOMQL. Provide React component code and receive the conversion context including migration rules, syntax reference, and examples. Args: source_code: The React/JSX source code to convert.

Convert DOMQL JavaScript source code to platform JSON format. Parses export statements from generated component/page code and converts them into the structured JSON the Symbols platform expects. Functions are automatically stringified (as the platform stores them as strings). Use this after generate_component or generate_page to get JSON that can be passed directly to save_to_project. Mirrors the @symbo.ls/frank toJSON + stringifyFunctions pipeline that the CLI uses when running `smbls push`. Args: source_code: JavaScript source code with export const/default statements. section: Target section — "components", "pages", "functions", "snippets", "designSystem", "state". Determines how exports are categorized.

Create a new Symbols project on the platform. Use this when the user wants to save generated components to a new project. Returns the project ID and key for use with save_to_project and publish. Args: name: Project display name. key: Project key (pr_xxxx format). Auto-generated from name if empty. token: JWT access token from login. api_key: API key (sk_live_...) from project integration settings. visibility: Project visibility — "private", "public", or "password-protected". language: Project language (default: "javascript").

[Legacy] Detect Symbols environment from caller-supplied file flags. **Prefer `get_project_context`** — it does the same classification by inspecting the filesystem directly (no caller-supplied flags needed) AND returns project owner/key/auth state in the same call. Kept for backward compatibility with older agent prompts. New code should call `get_project_context(cwd)` instead — its response includes `env_type`, `env_evidence`, and `env_guidance` fields equivalent to this tool's output, plus `owner`, `key`, `token_present`, and `next_step` guidance. Args: has_symbols_json: Whether symbols.json exists in the project root. has_symbols_dir: Whether a symbols/ directory exists with components/, pages/, etc. has_package_json: Whether package.json exists with smbls dependency. has_cdn_import: Whether HTML files contain CDN imports (esm.sh/smbls, etc.). has_iife_script: Whether HTML files use script src smbls (IIFE global). has_json_data: Whether the project uses frank-generated JSON data files. has_mermaid_config: Whether mermaid/wrangler config or GATEWAY_URL/JSON_PATH env vars are present. file_list: Comma-separated list of key files in the project root.

Return the documentation block for a specific frank-audit rule. Each rule (FA001 through FA902) has an `explain()` method that returns a human-readable description, examples of the bad/good patterns, and the rationale. Use this when an agent encounters an unfamiliar finding and needs context before deciding on a fix. Args: rule_id: The rule ID (e.g. 'FA301', 'FA806'). Returns: JSON with { ok, ruleId, name, severity, description, explanation }.

Tail the audit log for a Symbols project. Returns the most recent NDJSON entries from `<symbols_dir>/.frank-audit/log`. Each entry records audit/fix/apply-edits/rollback events with opId, timestamp, and outcome — useful for understanding history without re-running ops. Args: symbols_dir: Absolute path to the symbols/ directory. limit: Maximum number of entries to return (default 50). Returns: JSON with { ok, entries: [...] }.

Generate a Symbols.app DOMQL component from a description. Returns the rules, syntax reference, component catalog, cookbook examples, and default library reference as context. The calling LLM uses this context to generate a correct, compliant component. Args: description: What the component should do and look like. component_name: PascalCase name for the component.

Generate a Symbols.app DOMQL page with routing + helmet metadata + fetch integration. Returns rules, project structure, patterns, snippets, and default library reference as context for page generation. Args: description: What the page should contain and do. page_name: camelCase name for the page (used in route map).

Returns the complete `smbls` CLI reference (`@symbo.ls/cli`). Mirrors `smbls/CLI_FOR_MCP.md`. Covers: configuration files (symbols.json, .symbols_local/), API URL resolution order + env-var overrides, common flag conventions, full command map (project lifecycle, auth, sync, project mgmt, workspace ops, files & assets, integrations, GitHub, Frank JSON↔FS, dev/build/deploy, code transformation, SDK proxy, ask), publish flow (one-shot + granular), MCP/agent usage rules (--non-interactive + --yes + NODE_ENV + SYMBOLS_AUTH_TOKEN), error-handling contracts (AUTH_REQUIRED, ECONNREFUSED, missing app key), source-file map, and CLI-specific anti-patterns.

Get a Symbols project's current data (components, pages, designSystem, state). Use this to inspect what's already in a project before saving changes. Args: project: Project key (pr_xxxx) or project ID. token: JWT access token from login. api_key: API key (sk_live_...) from project integration settings. branch: Branch to read from (default: "main").

Read the current Symbols project context — START HERE for any Symbols task. Walks up from `cwd` (or the MCP process's working directory) looking for `symbols.json`, parses it, classifies the environment from filesystem signals, and returns a single JSON payload with everything an agent needs to begin work. Returns: - **owner**, **key**, **dir**, **bundler**, **sharedLibraries**, **brender** — from symbols.json - **project_root** — absolute path of the project root - **symbols_dir** — absolute path of the symbols/ source dir (or null) - **env_type** — `local | cdn | json_runtime | remote_server | unknown` - **env_evidence** — the filesystem signals that produced the classification - **env_guidance** — one-line guidance for that env type - **token_present** — whether `SYMBOLS_TOKEN` env var or `~/.smblsrc` token exists - **api_base** — the Symbols API base URL (defaults to https://api.symbols.app) - **next_step** — what the agent should do next (ask user / log in / proceed) **ALWAYS call this first** for any Symbols-project task. It replaces the older `detect_environment` tool (which required the caller to pre-compute file flags). Use this BEFORE calling any auth-required tool (save_to_project, publish, push, get_project) — combine with `token_present` to know whether to prompt for `login`. Never hardcode owner/key/credentials. If `next_step` says "ask the user", ASK. Args: cwd: Directory to start searching from. Defaults to the MCP server's process cwd. Pass an absolute path when the agent's cwd differs from the project root.

ALWAYS call this first before any generate_* tool — the mandatory Symbols.app rules. Call with NO arguments first. That returns the compact CORE bundle (well under 80k chars — it survives every client's tool-output cap): - the built-in-reuse directive (Atoms/Components catalog — REUSE via bare PascalCase keys), - RULES essentials: the RULES.md preamble (canonical-syntax table, flat API) + EVERY STRICT rule in full + an index of all rule headings, - the FRANKABILITY hard checklist (patterns that survive frank.toJSON), - a SECTION INDEX (all 16 sections, sizes, parts, how to fetch), - a NEXT STEP table telling you which sections to pull for your task. Then fetch sections on demand, one call each: get_project_rules(section="SYNTAX") → DOMQL v3.14 syntax reference get_project_rules(section="COMPONENTS") → built-in component catalog get_project_rules(section="RULES", part=2) → large sections come in parts get_project_rules(section="FRANKABILITY_CATALOG") Sections: FRAMEWORK, DESIGN_SYSTEM, RULES, COMPONENTS, DEFAULT_COMPONENTS, SYNTAX, PATTERNS, SNIPPETS, SHARED_LIBRARIES, WORKSPACE, FRANKABILITY, FRANKABILITY_CATALOG, FRANK_FIX_WORKFLOW, COMMON_MISTAKES, LEARNINGS, DEFAULT_PROJECT (case-insensitive, `.md` optional; several small sections may be comma-separated if they fit the cap). Unknown section names raise a clear error listing the valid names. full=True returns the legacy one-shot concatenation of all 16 sections (~590k chars). Use it ONLY on a client with no tool-output cap — Claude Code truncates it to a file path and the rules never reach the model. Minimum for any code-writing task: core + SYNTAX + COMPONENTS + FRANKABILITY. Violations cause silent failures — black page, nothing renders, or a working app with degraded UX you'll later have to rebuild. The single most-violated rule is reusing built-in components: a bare `Avatar: {}` renders the canonical built-in.

Returns the complete `@symbo.ls/sdk` API reference (3.14.0). Mirrors `sdk/SDK_FOR_MCP.md`. Covers all 24 services with full method lists: auth, collab, project, plan, subscription, file, payment, dns, branch, pullRequest, admin, screenshot, tracking, waitlist, metrics, integration, featureFlag, organization, workspace, workspaceData (typed wrapper for /workspace/*), kv, allocationRule, sharedAsset, credits. Plus: SDK class lifecycle, BaseService contract, TokenManager (singleton, auto-refresh), environment matrix (channel URLs), root event bus (sdk.rootBus with last-payload replay), validation surface, federation primitive (multi-Supabase registry), permissions reference (ROLE_PERMISSIONS, PROJECT_ROLE_PERMISSIONS, TIER_FEATURES), error handling contract, and MCP integration notes.

List the user's Symbols projects. Returns project names, keys, and IDs so the user can choose which project to save to or publish. Requires authentication. Args: token: JWT access token from login. api_key: API key (sk_live_...) from project integration settings.

Log in to the Symbols platform and get an access token. Use this when the user needs to authenticate before any project operation. Returns a JWT token that can be used with all project tools. Args: email: Symbols account email address. password: Symbols account password.

Generate LLM-ready prescriptions for frank-audit findings that can't be auto-fixed. Each prescription contains: - finding (rule, file, line, refusal reason) - sourceContext (~30 lines around the finding) - relatedFiles (other places that mention the same symbol) - **proposedOps** — array of edit ops the rule's helper logic produced (e.g. FA304 already mapped 36px → 'C2' from the project's spacing scale; FA301 already matched the closest palette token). The agent can submit these verbatim to apply_frankability_edit_ops, or modify before submitting. - explanation (the rule's docs) - safetyCheck (verify command run after apply) Workflow for the agent: 1. Call this tool to get prescriptions. 2. Inspect each `proposedOps` array. Either submit verbatim or modify. For findings with no proposedOps (structural refactors like FA2xx multifile-helpers, FA5xx DOM bans), construct your own ops from the 12 strict op kinds: removeImport | moveFile | addToIndexFile | addToGlobalScope | removeTopLevelDecl | addElementScope | replaceTokenValue | renameObjectKey | removeObjectKey | setObjectProperty | addDesignToken | skip 3. Call apply_frankability_edit_ops(symbols_dir, ops) — frank-audit validates every op, snapshots, applies, runs verify, rolls back on regression. Failed ops return structured details (E_OLDVALUE_NOT_FOUND with actualLine, E_KEY_NOT_FOUND with availableKeys, etc.) so you can retry intelligently. 4. Repeat until prescriptions are exhausted or no progress. Args: symbols_dir: Absolute path to the symbols/ directory. Returns: JSON with schema version, opId, list of prescriptions.

Publish a version of a Symbols project to the platform. Makes the specified version (or latest) the published/live version. Call save_to_project first to save your changes, then publish to make them live. Requires authentication — provide either token or api_key. Args: project: Project ID (MongoDB ObjectId) or project key (pr_xxxx). token: JWT access token from login or ~/.smblsrc. api_key: API key (sk_live_...) from project integration settings. Alternative to token. version: Version string or version ID to publish. Leave empty for latest. branch: Branch to publish from (default: "main").

Push/deploy a Symbols project to a specific environment. Deploys the project to a target environment (production, staging, dev). Call publish first to set the live version, then push to deploy. Requires authentication — provide either token or api_key. Args: project: Project ID (MongoDB ObjectId) or project key (pr_xxxx). token: JWT access token from login or ~/.smblsrc. api_key: API key (sk_live_...) from project integration settings. Alternative to token. environment: Target environment key (e.g. "production", "staging", "dev"). mode: Deploy mode — "latest" (newest from branch), "published" (current published version), "version" (specific version), or "branch" (track a branch). version: Required when mode is "version" — the version string or ID to deploy. branch: Branch to deploy from when mode is "latest" or "branch" (default: "main").

Restore a Symbols project to its state before a specific op ran. Every apply-edits run snapshots affected files under `<symbols_dir>/.frank-audit/snapshots/<opId>/` before mutating. Use this to undo a specific op (or a chain by walking backwards through opIds listed by `snapshots_frankability`). Args: symbols_dir: Absolute path to the symbols/ directory. op_id: The opId to roll back to (from a prior apply-edits result). Returns: JSON with { ok, restored: [...filePaths], opId }.

Save components, pages, or design system data to a Symbols project. This applies changes to the project and creates a new version. Use after generate_component/generate_page to persist the output. The changes parameter is a JSON string with the data to merge into the project. Structure mirrors the project data format: ```json { "components": { "Header": { "extends": "Flex", "props": { "flow": "x", "gap": "B", "padding": "A B" }, "Logo": { "extends": "Icon", "props": { "name": "logo" } }, "Nav": { "extends": "Flex", "gap": "A" } } }, "pages": { "home": { "extends": "Page", "Header": {}, "Hero": { "extends": "Flex" } } }, "designSystem": { ... }, "state": { ... }, "functions": { ... } } ``` Only include the sections you want to update — omitted sections are left unchanged. Args: project: Project key (pr_xxxx) or project ID. changes: JSON string with project data to save (components, pages, designSystem, state, functions). token: JWT access token from login. api_key: API key (sk_live_...) from project integration settings. message: Version commit message describing the changes. branch: Branch to save to (default: "main"). force_shared_library: Explicitly allow writing to a project flagged isSharedLibrary when this tree's .symbols_local/lock.json does not carry that record's id. Without it the server refuses such saves (403 shared_library_lock_required) — shared libraries feed every consumer project, so an accidental write is an incident.

Search the Symbols documentation knowledge base for relevant information. Args: query: Natural language search query about Symbols/DOMQL. max_results: Maximum number of results to return (1-5).

List recent snapshotted opIds for a Symbols project. Each entry corresponds to a frank-audit op that wrote files. Pass an opId to `rollback_frankability` to restore that op's pre-state. Returns: JSON with { ok, opIds: [{ opId, timestamp, files }] }.

Verify a Symbols project bundles cleanly via frank.toJSON. Independent of audit/fix — runs the same round-trip that apply-edits uses after every mutation, but as a standalone check. Useful for the agent to confirm a project is in a known-good state before starting a fix loop, or after a series of manual edits. Returns: JSON with { ok, bundleable, scanIssues, ... }.