インスペクター

Stimeo UI の npm パッケージには、stimeo-ui という小さなコマンドライン（CLI）が同梱されています。書いたマークアップが stimeo--* を正しく使えているかを検査し、使えるコントローラの一覧を書き出せます。同じ情報を AI コーディング支援へ供給する MCP サーバとしても動きます。

この CLI は Node 製のツールのため、Ruby の gem には同梱されていません。とはいえ gem + importmap で導入した場合でも使えなくなるわけではありません。npx stimeo-ui はプロジェクトに npm を追加せずにその場で取得・実行できます。必要なのは Node の実行環境だけで、GitHub Actions の GitHub ホステッドランナーには最初から入っています。

まだ発展途上の機能です。 いまは「検査」「一覧の出力」「MCP サーバ」「VS Code 拡張」という絞った機能を提供する、早期プレビューの段階です。これから機能を増やしていきます。

マークアップを検査する

npx stimeo-ui check app/views

指定したフォルダの中の .html / .htm / .html.erb を再帰的に調べ、未知のコントローラや、target / value / action の打ち間違いや使い方の誤りを見つけます。さらにアクセシビリティの契約も検査します — コンポーネントが必要とするのに書かれていない ARIA（例: ダイアログの role / aria-modal / 名前）、キーボードで到達できない操作点（tabindex が必要な div ベースのスライダーつまみ等）、同じファイル内で切れている ARIA の id 参照（aria-labelledby の指し先が存在しない等 — こちらは部分テンプレートをまたぐ場合があるため警告）。誤りが見つかると、コマンドの終了コード（実行結果を表す番号）が 0 以外になります（警告だけなら 0 のまま）。CI（自動チェック）に組み込んでおけば、誤りがあったときにビルドを止められます。

コントローラの一覧（カタログ）を出力する

npx stimeo-ui catalog

使えるすべてのコントローラと、それぞれの target / value / action / event を一覧で書き出します。この一覧は実装から自動で生成されるため、手書きで管理する必要がなく、実装と常に一致します。出力はこんな形です:

Stimeo UI catalog — 111 controller(s)

stimeo--dialog
  targets:  trigger, dialog
  actions:  close, closeOnBackdrop, open

stimeo--tabs
  targets:  tab, panel, list
  actions:  onKeydown, select

…

JSON で出力する（ツール / MCP 向け）

--json を付けると、どちらのコマンドも機械が読める JSON で結果を返します:

npx stimeo-ui check --json app/views
npx stimeo-ui catalog --json

check --json: ファイルごとの検査結果とサマリ（チェックレポート）を返します。
catalog --json: コントローラの一覧をそのままの形（マニフェスト）で返します。

検査で誤りが見つかると、終了コードが 1 になります。そのため、エディタや pre-commit フック、MCP ツールは JSON の中身を、CI は終了コードを使って、それぞれ結果を判定できます。

AI コーディング支援から使う（MCP サーバ）

同じ検査エンジンを、Model Context Protocol（MCP） のサーバとしても起動できます。一度登録しておくと、AI コーディング支援（Claude Code や Cursor など）が「どんなコンポーネントがあるか」「正しい使い方（契約）は何か」「お手本のマークアップ」を公式データから直接引けるようになり、生成したマークアップをあなたに提示する前に自分で検査までできます。AI の「それっぽいが間違ったコード」を減らすための、公式の情報供給口です。

claude mcp add stimeo -- npx -y stimeo-ui mcp

プロジェクトの .mcp.json（Claude Code）や .cursor/mcp.json（Cursor）に書く場合はこうです:

{
  "mcpServers": {
    "stimeo": {
      "command": "npx",
      "args": ["-y", "stimeo-ui", "mcp"]
    }
  }
}

提供するのは読み取り専用の 4 つのツールです:

ツール	AI が得られるもの
`stimeo_check`	生成したマークアップ文字列の検査（`stimeo-ui check` と同じエンジン）
`stimeo_catalog`	全コントローラと `target` / `value` / `action` / `event` の一覧
`stimeo_controller`	1 つのコントローラの完全な契約（アクセシビリティ要求まで）
`stimeo_example`	検証済みのお手本マークアップ — このカタログのデモそのもので、検査を通ることが保証されています

マニフェスト全体と各お手本は MCP のリソース（stimeo://manifest・stimeo://examples/<id>）としても公開しているので、ツール呼び出しを待たずに会話の前提資料として最初から添付しておくこともできます。さらに、この一連の手順（発見 → 契約 → お手本 → 検査）を焼き込んだ定型プロンプトを 2 つ提供します — stimeo_build_ui（この UI を作って）と stimeo_fix_markup（このマークアップを検査して直して）。プロンプト対応のクライアントでは、スラッシュコマンドとして呼び出せます。

すべて手元（ローカル）で完結します。サーバはパッケージに同梱されたデータだけを読み、それ以外にあなたのファイルへアクセスせず、書き込みを行うツールもありません。動作中のサーバがネットワークへ何かを送ることもありません — 上の例で通信が起きるのは、npx が初回にパッケージ本体を取得するときだけです。

エディタで書きながら検査する（VS Code 拡張）

同じ検査を、エディタの中でリアルタイムに動かせます。VS Code Marketplace から Stimeo UI Inspector をインストールしてください（エディタの拡張機能ビューで「Stimeo UI Inspector」を検索しても見つかります）。Cursor / VSCodium / Windsurf など VS Code 系のエディタをお使いの場合は、Open VSX にも同じものを公開しています。設定は不要です。検査エンジンは拡張に同梱されているので、HTML / ERB のファイルを開いたときからそのまま動きます。

書きながら診断 — npx stimeo-ui check と同じ指摘を、編集中にその場でインライン表示します。名前の打ち間違いには「もしかして…?」の候補が付きます。
クイックフィックス（💡） — コントローラ名やターゲット名の打ち間違いなど、直し方が一つに決まる誤りは、ワンクリックで修正できます。
入力補完 — コントローラ名、ターゲット名、アクションのメソッド名を公式カタログから補完します。候補はインストールされているバージョンと常に一致します。
ホバー表示 — stimeo--* の名前にカーソルを載せると、その使い方の契約（targets / values / actions と、検査が見るアクセシビリティ要求）をその場で確認できます。

拡張は、ファイルごとに正しいカタログ（マニフェスト）を3段階で選びます。まず明示設定（stimeo.manifestPath）が最優先、次にそのファイルから一番近くにインストールされている stimeo-ui パッケージ（モノレポでも、それぞれのアプリが自分のバージョンで検査されます）、最後の受け皿として拡張に同梱のスナップショットを使います。npm パッケージを入れていないプロジェクトでも、そのまま動きます。

GitHub Actions にインライン注釈を出す

--github を付けると、検査結果を GitHub Actions のワークフローコマンド（::error / ::warning）として出力します。Actions のジョブでそのまま実行するだけで、Pull Request の差分上に指摘がインライン表示されます。追加のアクションやアップロード手順は不要です:

npx stimeo-ui check --github app/views

検査を部分的に抑止する

静的検査には見えないもの（別の部分テンプレートで解決される id 参照など）を意図的に書いている箇所は、その要素に data-stimeo-ignore を付けると、その要素とその中身への指摘を抑止できます。値に診断コードを空白区切りで書くと、そのコードだけを抑止します（推奨。値なしは全部の抑止になるため多用しないでください）:

<div data-stimeo-ignore="unresolved-idref">
  <%# aria-labelledby の指し先はレイアウト側の見出し %>
  …
</div>

コードを打ち間違えた場合は、それ自体が警告として報告されます（抑止できません）。

カタログの出どころ

コマンドが出力するカタログと、各コンポーネントページに載っている API 契約 の表は、どちらも同じ元データ（dist/inspector/manifest.json）から作られています。この元データは実装から自動で生成されるので、ドキュメントと実物がずれることはありません。詳しくはカタログで各コンポーネントの API 契約 を見てください。

stimeo CLI でマークアップを検査

静的検査

カタログ出力

JSON 出力

実装と常に一致