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、およびエージェントに次の操作（ユーザーへの確認、ログイン、または処理の続行）を示す next_step ヒントを返します。新しいコードでは、旧版の detect_environment の代わりに使用します。
get_project_rules	必須のルールセットです。引数なしの場合は、コンパクトな CORE バンドルを返します（再利用に関する指示 + RULES の要点 + すべての STRICT ルール + frankability チェックリスト + セクション索引 + 次のステップ表。80K 文字未満で、すべてのクライアントのツール出力上限内に収まります）。section="SYNTAX"（または COMPONENTS、FRANKABILITY、RULES + part=N など。全 16 セクション）を指定すると、呼び出しごとに 1 セクションを取得します。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 パイプラインを反映）。save_to_project に渡すため、generate_component／generate_page の後に使用します。

監査

ツール	説明
audit_component	インライン VALIDATOR：単一ファイルのコード（コンポーネント、ページ、関数など）を監査します。違反と警告を返します（約1K文字）。生成中に使用してください。file_path（例：'functions/listQuerySet.js'）を渡すと、ファイルが置かれているフォルダーに応じたルールが適用されます。渡さない場合、コードはコンポーネントとして監査されます。また、通常のプロジェクト監査では実行されない、4つの STRICT な構造ルールについても警告します（frank-audit のオプトイン FA810～FA813）：3つ以上の CSS プロパティで条件が繰り返されている（ルール 19）、:hover はあるが :active がないインタラクティブ要素（ルール 65）、兄弟要素と並んでフロー内にある要素の、状態によって決まる if:（ルール 66）、組み込み Button の呼び出し箇所での padding／height の上書き（ルール 68）。include_playbook=True を渡すと、AUDIT.md のプレイブックも出力します。
audit_project	複数フェーズのプロジェクト監査プレイブック（エージェント向けの手順書。フェーズ 0 のセットアップからフェーズ 5 のレポートまで）を返します。静的監査フェーズでは bin/symbols-audit.cjs CLI と組み合わせてください。

ファイルシステム全体を監査するための CLI がパッケージに含まれています：npx -y -p @symbo.ls/mcp symbols-audit <symbols-dir>（デフォルトで strict、検出結果がある場合は終了コード 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 になりました。これは、正規の 59 ルールのレジストリ、処方の生成、検証またはロールバックを行う修正処理を担う AST ベースのエンジンです。

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	プロジェクトを環境（production、staging、dev）にデプロイします。

エンドツーエンドのフロー（任意の 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	Symbols/DOMQL プロジェクトで作業する AI エージェント向けの厳格なルール 62 項目
symbols://skills/syntax	DOMQL 構文言語の完全なリファレンス（フラット API、シグナルによるリアクティビティ）
symbols://skills/modern-stack	最新の smbls スタック — fetch、polyglot、helmet（メタデータカタログ全体）、router、scratch テーマランタイム、brender SSR
symbols://skills/components	DOMQL コンポーネントリファレンス（要素上のフラットな props、フラットな 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	監査の完全な手順書（フェーズ 0～5、エンドツーエンドで実行可能）
symbols://skills/common-mistakes	誤った DOMQL パターンと正しい 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	デザインシステムに照らしてビジュアル／デザインを監査

---

クイックスタート

2 つのコマンドと 1 行の設定で、主要な 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. 確認

エディターのチャットで、アシスタントに次のように尋ねます。

symbols-mcp を使って get_project_rules を呼び出し、最新のスタックルールを要約してください。

ルールセットが返されたら準備完了です。意図的に壊したスニペットに対して audit_component を試し、ルール 62（アイコンにインライン SVG を使うことを禁止するルール）が検出されることを確認してください。

---

Symbols プロジェクトの自動セットアップ — 「use 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 を渡します。

エージェントスキル — マシン上のすべてのエージェントに一括インストール

wrangler 方式の手順で、インストール済みの AI コーディングエージェント（Claude Code、Cursor、Codex、GitHub Copilot、Gemini CLI、Windsurf、Cline、Goose、Warp、Antigravity、Zed、Aider）を検出し、該当するエージェントにのみ 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 にインストールされます。エージェントが 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 では接続時に自動で読み込まれます）、エージェントに「use symbols-mcp」と念押しする必要はなくなります。最初のやり取りでワークフローがセットアップされます。

Claude Code：強制適用フック（デフォルトでインストール）

プロジェクトレベルのルールファイル（CLAUDE.md、AGENTS.md など）はベストエフォートです。コンテキストが長くなるとルールが埋もれ、エージェントが逸脱する可能性があります。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	cwd が Symbols プロジェクト内にある場合、毎ターン、必須の手順と frankability の FA ルール早見表を挿入します。ターンごとに挿入されるため、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 web、その他のカスタム MCP クライアント）で動作します。

3 つの方法があります。

1. 自然言語（設定不要）— _「symbols-mcp を使って、このプロジェクトの Symbols 監査を全体的に実行して」_と伝えるだけです。エージェントは get_project_context → audit_project（プレイブック）→ bin/symbols-audit.cjs CLI の順に呼び出し、audit_component を使って修正を繰り返します。
2. カスタムコマンド — Cursor のルール、Continue の customCommand、Windsurf のワークフローなどを登録すれば、ワンキー操作で同等の機能を利用できます。テンプレートは SETUP.md にあります。
3. シェルのみ — npx -y -p @symbo.ls/mcp symbols-audit ./symbols は、エディターなしであらゆるターミナルから実行できます。デフォルトでは厳格モードで、問題が見つかると終了コード 1 を返します。

---

詳細なセットアップガイド

以下については SETUP.md をご覧ください。

• エディターごとの設定： Claude Code · Claude Desktop · Claude.ai (web) · 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 およびその他のツールの使用： 自然言語、エディターごとのカスタムコマンド、シェルによる代替手段、同梱の venv の直接利用
• トランスポートモード： stdio（デフォルト）と SSE（claude.ai web / リモートクライアント向け）
• 監査 CLI： CI / pre-commit 用のスタンドアロン bin/symbols-audit.cjs
• 更新およびトラブルシューティング（PATH の問題、古いバージョン、ツールの不足）