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 @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, 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).