Symbols MCP

symbols-mcp

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

适用于 Symbols.app 的 MCP 服务，为 AI 编码助手（Cursor、Claude Code、Windsurf、claude.ai 等）提供文档搜索、代码生成、转换、审计、项目管理、发布/部署以及 CLI/SDK 参考工具。

面向现代 smbls 技术栈——扁平元素 API、基于信号的响应式、声明式 fetch:（@symbo.ls/fetch）、多语言翻译（@symbo.ls/polyglot）、helmet 元数据（@symbo.ls/helmet）、通过 el.router(...) 实现 SPA 路由、通过 @symbo.ls/scratch 设置主题，以及通过 @symbo.ls/brender 实现 SSR。

文档工具无需 API 密钥。项目管理工具需要 Symbols 账户（登录或使用 API 密钥）。

---

工具

上下文 — 从这里开始

工具	说明
get_project_context	首先调用。 从 cwd 向上遍历以查找 symbols.json，返回 owner、key、dir、bundler、sharedLibraries、brender、env_type（local/cdn/json_runtime/remote_server）、env_evidence、env_guidance、token_present，以及告知 Agent 下一步操作（询问用户、登录或继续）的 next_step 提示。新代码应使用此工具代替旧版 detect_environment。
get_project_rules	必须遵循的规则集。不带参数 → 精简 CORE 捆绑包（复用指令 + RULES 要点 + 每条 STRICT 规则 + frankability 检查清单 + 章节索引 + 后续步骤表，<80K 字符——适用于每个客户端的工具输出上限）。section="SYNTAX"（或 COMPONENTS、FRANKABILITY、RULES + part=N，……共 16 个章节）每次调用获取一个章节。full=true → 旧版约 590K 的一次性内容（仅适用于没有上限的客户端）。执行任何代码生成任务前都要调用。
get_cli_reference	完整的 Symbols CLI（@symbo.ls/cli）命令参考。
get_sdk_reference	完整的 Symbols SDK（@symbo.ls/sdk）API 参考。
search_symbols_docs	在所有捆绑的 Symbols 文档文件中按关键字搜索。
detect_environment	[旧版] 由调用方提供标志的环境分类变体。优先使用 get_project_context。

生成与转换

工具	说明
generate_component	根据自然语言描述生成 DOMQL 组件。返回提示词 + 捆绑上下文（约 300K 字符）。
generate_page	生成完整页面，包含路由、helmet 元数据和声明式 fetch: 集成。
convert_react	将 React/JSX 代码转换为 Symbols DOMQL（现代 smbls 技术栈）。
convert_html	将原始 HTML/CSS 转换为 Symbols DOMQL 组件。
convert_to_json	将 DOMQL JS 源码转换为平台 JSON（对应 frank 的 toJSON 流程）。在 generate_component / generate_page 后使用，以便传入 save_to_project。

审计

工具	描述
audit_component	单个文件代码（组件、页面、函数等）的内联验证器。返回违规项和警告（约 1K 字符）。生成过程中使用。传入 file_path（例如 'functions/listQuerySet.js'），即可应用依赖文件夹位置的规则；不传入时，代码会作为组件接受审计。此外，它还会针对默认项目审计不会运行的四项严格结构规则发出警告（frank-audit 的可选 FA810–FA813）：同一条件重复用于 3 个或更多 CSS 属性（规则 19）、交互元素有 :hover 但没有 :active（规则 65）、元素在同级元素旁的文档流中使用由状态驱动的 if:（规则 66）、内置 Button 的调用处覆盖了 padding/height（规则 68）。传入 include_playbook=True 还会输出 AUDIT.md 操作手册。
audit_project	返回多阶段项目审计操作手册（Agent 的操作说明——阶段 0 设置 → 阶段 5 报告）。静态审计阶段需配合 bin/symbols-audit.cjs CLI 使用。

对于整个文件系统的审计，此软件包提供了一个 CLI：npx -y -p @symbo.ls/mcp symbols-audit <symbols-dir>（默认严格模式，发现问题时退出码为 1）。-p 指定软件包并运行其 symbols-audit bin；每个版本均支持此方式。简写形式 npx -y @symbo.ls/mcp symbols-audit <symbols-dir>（以及 npx -y @symbo.ls/mcp init-rules）需要使用包含该软件包 mcp bin 的版本；较旧版本中，npx 会提示“could not determine executable to run”，此时请改用 npx -y -p @symbo.ls/mcp symbols-audit / npx -y -p @symbo.ls/mcp symbols-mcp-init-rules。底层运行的是 frank-audit audit --strict——审计核心现在是 @symbo.ls/frank-audit，这是一个基于 AST 的引擎，负责维护规范的 59 条规则注册表、生成修复方案以及执行验证或回滚修复。

lib/audit.js 保留为向后兼容的垫片，负责委托给 frank-audit（子进程 CLI，或在设置了 FRANK_AUDIT_URL 时使用 /audit-content HTTP 端点）。旧版程序化 API 仍可供非 CLI 调用方（@symbo.ls/cli、MCP HTTP 工作线程、Web/边缘客户端）调用：

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')

与旧版正则表达式输出相比，发现结果有所变化是预期且正确的——frank-audit 能以更高准确度检测出更多问题。字段名称保持不变（file、line、rule、severity、category、snippet、suggested_fix）。如需查看规则注册表，请直接查询 frank-audit：npx frank-audit explain <id>。

项目管理与发布

工具	描述
login	登录 Symbols 平台——返回 JWT 令牌。
list_projects	列出用户的项目（名称、键、ID），供选择。
create_project	在平台上创建新的 Symbols 项目。
get_project	获取项目当前数据（组件、页面、设计系统、状态）。
save_to_project	将组件/页面/数据保存到项目——创建新版本，并包含变更元组、细粒度变更、顺序和自动生成的架构条目。
publish	发布一个版本（使其上线）。
push	将项目部署到某个环境（生产、预发布、开发）。

端到端流程（适用于任意 MCP 客户端）

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

资源

Skills（文档）

URI	描述
symbols://skills/framework	权威框架参考 — 项目结构、插件、主题、SSR、发布流程（镜像自 smbls/FOR_MCP.md）
symbols://skills/rules	AI Agent 在 Symbols/DOMQL 项目中工作的 62 条严格规则
symbols://skills/syntax	完整的 DOMQL 语法语言参考（扁平 API、信号响应式）
symbols://skills/modern-stack	现代 smbls 技术栈 — fetch、polyglot、helmet（完整元数据目录）、router、scratch 主题运行时、brender SSR
symbols://skills/components	DOMQL 组件参考（元素上的扁平属性、扁平 onX 事件）
symbols://skills/project-structure	项目文件夹结构和文件约定
symbols://skills/shared-libraries	sharedLibraries 模式 — 配置、运行时合并、优先级
symbols://skills/design-system	设计系统规范 + 令牌目录（颜色、主题、排版、间距等）
symbols://skills/design	UI/UX 方向 + 设计转代码转换器 + 7 个专业角色（整合版）
symbols://skills/patterns	UI 模式、无障碍设计、AI 优化
symbols://skills/migration	旧项目迁移指南 + React/Angular/Vue → Symbols
symbols://skills/audit	完整审计手册（Phase 0–5，可端到端执行）
symbols://skills/common-mistakes	错误与正确的 DOMQL 模式，零容忍执行
symbols://skills/frankability	能通过 frank.toJSON 的模式 — @symbo.ls/frank-audit 的每条规则均附有错误与规范示例
symbols://skills/learnings	框架内部机制、技术注意事项、深入的运行时知识
symbols://skills/cookbook	小型响应式配方集（切换、fetch、模态框、标签页等）
symbols://skills/snippets	可用于生产环境的组件代码片段（导航、主视觉区、价格卡片、页脚等）
symbols://skills/default-project	默认起始项目 — 库目录（127+ 个组件）+ 预配置的设计系统令牌
symbols://skills/default-components	130+ 个默认模板组件的完整源代码（内容较多，按需查阅）
symbols://skills/running-apps	运行 Symbols 应用的 4 种方式（本地、CDN、JSON、远程）
symbols://skills/cli	Symbols CLI（@symbo.ls/cli）完整命令参考
symbols://skills/sdk	Symbols SDK（@symbo.ls/sdk）完整 API 参考

参考资料（内联）

URI	描述
symbols://reference/spacing-tokens	间距令牌表（黄金比例刻度）
symbols://reference/atom-components	内置原子/基础组件
symbols://reference/event-handlers	事件处理程序签名和模式

提示词

提示词	描述
symbols_component_prompt	根据描述生成组件
symbols_migration_prompt	从 React/Angular/Vue 迁移代码
symbols_project_prompt	搭建完整项目
symbols_review_prompt	审查代码是否符合规范
symbols_convert_html_prompt	将 HTML/CSS 转换为 DOMQL
symbols_design_review_prompt	根据设计系统进行视觉/设计审计

---

快速开始

只需两条命令和一行配置 — 适用于所有主流 MCP 客户端。

1. 安装

选择你已有的运行时：

uvx symbols-mcp           # uv  — recommended, zero install
pip install symbols-mcp   # pip — global binary
npx -y @symbo.ls/mcp      # npm — Node-friendly wrapper

2. 配置编辑器

标准 MCP 配置代码段（适用于 Claude Code、Claude Desktop、Cursor、Windsurf、Cline、Continue、Zed、Goose、Gemini CLI — 按编辑器所需的格式封装）：

{
  "mcpServers": {
    "symbols-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--refresh", "symbols-mcp"]
    }
  }
}

--refresh 会在每次启动时从 PyPI 拉取最新版本（启动耗时增加约 1–2 秒 — 固定版本或离线运行时可去掉）。

3. 验证

在编辑器的聊天中，向助手提问：

Use symbols-mcp to call get_project_rules, then summarize the modern stack rules.

如果返回了一套很长的规则，就说明配置好了。试着用一个故意写错的代码片段调用 audit_component，确认它会触发 Rule 62（禁止使用内联 SVG 作为图标的规则）。

---

自动引导 Symbols 项目——不再需要提醒“使用 symbols-mcp”

在编辑器中配置好 symbols-mcp 后，添加项目级规则文件，让每个编辑器在每次聊天时自动加载框架规则：

# from your Symbols project root
npx -y @symbo.ls/mcp init-rules

这会写入 CLAUDE.md、.cursor/rules/symbols.md、.windsurfrules、.clinerules 和 AGENTS.md——每个文件都针对对应的编辑器进行了定制，且都会指向 symbols-mcp 工具（get_project_context、get_project_rules、generate_component、audit_component 等）。此操作可幂等执行；传入 --force 可覆盖文件，传入 --only=cursor,claude 可指定范围。

Agent 技能——一键为机器上的所有 Agent 安装

Wrangler 风格的安装路径：检测已安装的 AI 编码 Agent（Claude Code、Cursor、Codex、GitHub Copilot、Gemini CLI、Windsurf、Cline、Goose、Warp、Antigravity、Zed、Aider），并仅为检测到的 Agent 安装 Symbols 规则和技能：

npx -y @symbo.ls/mcp skills          # detect agents → install rules + skills for them
# equivalent: npx -y @symbo.ls/mcp init-rules --detect
# from the Symbols CLI: smbls skills

对于 Claude Code，这还会在 .claude/skills/symbols/SKILL.md 安装一个标准的 Agent 技能——当 Agent 处理 Symbols/DOMQL 时，它会自动加载（其描述会在 symbols.json 项目、DOMQL 组件、设计令牌以及 smbls CLI 中触发），并包含必须执行的工具调用顺序和硬性规则摘要。--global 会将其安装一次到 ~/.claude/skills/，供每个项目使用；--no-skills 可选择不安装。

结合 MCP 服务的 instructions 字段（所有支持 MCP 的编辑器——Claude Code、Cursor、GitHub Copilot、Windsurf、Cline、Continue、Roo、Zed、Goose、Gemini CLI、Codex、Antigravity、Cody——连接后都会自动加载），这意味着你再也不必提醒 Agent“使用 symbols-mcp”——工作流会在首次交互时自动完成引导。

Claude Code：强制执行钩子（默认安装）

项目级规则文件（CLAUDE.md、AGENTS.md 等）只能尽力发挥作用——长上下文会稀释它们的作用，Agent 也可能偏离规则。对于 Claude Code，init-rules 还会安装一层由运行框架直接强制执行的钩子：

钩子	触发条件	功能
symbols-mcp-require.sh	PreToolUse Edit|Write|MultiEdit	阻止对 symbols.json 所在目录树内的 *.js/*.ts/*.tsx 文件执行 Edit/Write，直到本会话调用过 mcp__symbols-mcp__get_project_rules（或 get_project_context/generate_component/audit_component）。
symbols-mcp-reminder.sh	UserPromptSubmit	当当前工作目录位于 Symbols 项目中时，每轮注入必须执行的顺序和 frankability FA-rule 速查表。与 CLAUDE.md 不同，逐轮注入的内容不会因长上下文而被稀释。
symbols-mcp-audit.sh	PostToolUse Edit|Write|MultiEdit	在 Symbols 项目中每次编辑 JS 后，运行 frank-audit 和内联 FA 规则模式检查（FA101/102/103/105/106/206/207/513/514），并将违规情况反馈给 Claude。

安装的文件：

.claude/settings.json                       # wires the three hooks
.claude/hooks/symbols-mcp-require.sh        # PreToolUse  — block edit until rules loaded
.claude/hooks/symbols-mcp-reminder.sh       # UserPromptSubmit — inject directive
.claude/hooks/symbols-mcp-audit.sh          # PostToolUse — frank-audit + FA-rule check

跳过钩子：npx -y @symbo.ls/mcp init-rules --no-hooks。 运行时禁用单个钩子：SYMBOLS_MCP_REQUIRE_RULES=0、SYMBOLS_MCP_REMINDER=0、SYMBOLS_MCP_POST_AUDIT=0。

钩子需要在 PATH 中有 bash 和 jq（macOS 和大多数 Linux 发行版上通常已预装）。frank-audit 通过 npx -y --no-install @symbo.ls/frank-audit 调用——如果尚未安装，内联模式检查仍会运行。

请参阅 SETUP.md → 引导，了解分层模型和验证步骤。

---

那么 /symbols-audit 呢？

/symbols-audit 斜杠命令仅适用于 Claude Code，但底层功能适用于所有支持 MCP 的编辑器，包括 Cursor、GitHub Copilot、Windsurf、Cline、Continue、Roo、Zed、Goose、Gemini CLI、Codex、Antigravity (Google)、Cody、Claude.ai 网页版以及任何自定义 MCP 客户端。

三种使用方式：

1. 自然语言（零配置）——只需说 “使用 symbols-mcp 对此项目运行完整的 Symbols 审计。” Agent 会调用 get_project_context → audit_project（操作指南）→ bin/symbols-audit.cjs CLI → 使用 audit_component 逐项迭代修复。
2. 自定义命令——注册 Cursor 规则、Continue customCommand、Windsurf 工作流等，实现一键调用。模板见 SETUP.md。
3. 纯 Shell——在任何终端中运行 npx -y -p @symbo.ls/mcp symbols-audit ./symbols，无需编辑器。默认启用严格模式，发现问题时退出码为 1。

---

完整设置指南

参见 SETUP.md，了解：

• 各编辑器的配置： Claude Code · Claude Desktop · Claude.ai (网页版) · Cursor · GitHub Copilot (VS Code / CLI) · Windsurf · Zed · Cline · Continue · Roo · Cody · Gemini CLI · OpenAI Codex · Goose · Antigravity · 通用客户端
• 各工具的快速入门与工作区连接（s1m0ne Bridge + MCP + 规则）：docs.symbols.app/simone
• 本地开发： 克隆仓库、从源代码运行、.mcp.json 模板
• 在非 Claude Code 编辑器中使用 /symbols-audit 和其他工具： 自然语言、各编辑器的自定义命令、Shell 备用方案、直接使用随附的 venv
• 传输模式： stdio（默认）和 SSE（适用于 claude.ai 网页版 / 远程客户端）
• 审计 CLI： 独立的 bin/symbols-audit.cjs，用于 CI / 提交前检查
• 更新和故障排除（PATH 问题、版本过旧、缺少工具）