Mlola UI

mlola-ui

Mlola UI のソースコピー CLI です。コンポーネント、ブロック、ページ、テンプレートをプロジェクトに書き込み、インポートを書き換えてプロジェクトに適合させ、コピーしたコードがインポートする Mlola パッケージをパッケージマネージャーでインストールします。フレームワークに依存しません。コピーしたマークアップは HTML を出力できるあらゆる言語で動作し、React ソースが使用するのは React のみです。

ライブラリのコントラクトは独自のスタイルシートから生成されるため、これを読むモデルが、存在しないクラスや属性を作り出すことはありません。

インストール

npx mlola-ui init
npx mlola-ui add button sheet hero-split landing
npx mlola-ui doctor

init は mlola.config.json、エンジンのスタイルシート、コーディングエージェントが読む指示（下記参照）を作成し、@mlola-ui/engine をインストールします。見つかったプロジェクトに合わせて設定されます。ファイルは tsconfig.json の @/ エイリアスが指す場所に配置され、エイリアスがない場合は src/ があればそこに配置されます。新しい Vite アプリのようにエイリアスがない場合は、"imports": "relative" を設定し、コピーしたファイル同士を相対パスでインポートするため、事前の設定は不要です。

add は依存関係グラフを解決し（ページはそのブロックを、ブロックはそのコンポーネントを取り込みます）、指定したものだけをコピーして、コピーしたコードがインポートするパッケージのうち package.json にまだ宣言されていないものをインストールします。コマンドを表示するだけにするには --no-install を渡します。doctor は、プロジェクトとレジストリを照合し、インストール済みの項目がインポートするパッケージ、エンジンのインポート、テーマ属性、追加後に変更されたファイルをチェックします。

プロジェクトでは Tailwind を引き続き使用できます。エンジンは、どちらのインポート順でも Mlola のレイヤーを Tailwind の preflight より上に配置します。

コマンド

コマンド	動作
init [--no-agents] [--no-install]	mlola.config.json、スタイルシートのエントリーポイント、エージェント向けの指示を作成し、エンジンをインストールします
agents	既存のプロジェクトでエージェント向けの指示を作成または更新します
mcp	コーディングエージェント向けに、Mlola MCP サーバーを stdio 経由で実行します
add <items…> [--no-install]	項目とその依存関係をプロジェクトにコピーし、それらがインポートするパッケージをインストールします
list [--json]	インストール可能なすべての項目を表示します
doctor	プロジェクトとレジストリの問題を報告します
check [path…] [--json] [--strict] [--all]	各ファイルのマークアップと CSS をコントラクトに照らしてチェックし、手入力された色と間隔の値を数えます
migrate [path…] [--write] [--json]	shadcn/ui プロジェクトの props、トースト、アイコンを Mlola に移行し、人手による対応が必要な項目を一覧表示します
render check <file | -> [--json]	エージェントが作成した A2UI メッセージを Mlola Render カタログに照らしてチェックします。エラーがある場合は終了コード 1 を返します
render catalog [--schema]	エージェントが読むガイドとして Mlola Render カタログを表示するか、A2UI カタログとして表示します
render prompt [--tool] [--page-theme]	自分で呼び出すモデル用のシステムプロンプトを表示します。すべての回答をサーフェスにするか、（--tool を指定した場合）役立つときにモデルが呼び出すツールにします。--page-theme を指定すると、テーマはページに任せます
login <token>	Mlola Pro トークン（/account で取得）をこのユーザー用に保存します
logout	保存したトークンを削除します

プロジェクトのチェック

check は、プロジェクト内のすべての HTML、JSX、TSX、Vue、Svelte、Astro、CSS ファイル（または指定したパス）に対して、MCP サーバーの check_markup と同じチェックを実行し、各問題を行番号と修正方法とともに報告します。

npx mlola-ui check            # the whole project
npx mlola-ui check src --json # one folder, every issue as data

最後に、トークンから読み取らずに手入力された色と間隔の値の種類数と、最も多く使われている値を示します。どのプロジェクトでも使えるため、Mlola の導入前に現状を測定できます。Mlola プロジェクトでは、CLI がインストールしたものは除外されます（--all を指定するとコピーしたマークアップも対象に含まれます。組み込みテーマを含む Mlola 独自のスタイルシートはライブラリのゲートで保護されており、チェック対象になりません）。Tailwind、UnoCSS、Windi がインストールされている場合、ユーティリティクラスはそのままにして、クラス内に手入力された値だけを数えます（bg-[#fafafa]、p-[13px]）。

エラーが見つかった場合は終了コード 1 を返します（--strict を指定した場合は警告でも返します）。GitHub Actions では、各問題がプルリクエスト上のアノテーションにもなります。

# .github/workflows/ui.yml
name: UI
on: pull_request
jobs:
  mlola:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npx -y mlola-ui@latest check src

shadcn/ui からの移行

migrate は、推測せずに機械的に変更できる箇所を変更し、残りについては行番号と対応方法を一覧表示します。Mlola は shadcn/ui と同じファイル（components/ui/button.tsx）にコンポーネントをインストールするため、インポートはそのまま使えます。デフォルトでは読み取りのみ行い、変更を適用するには --write を指定します。

npx mlola-ui migrate            # what would change, and what needs a person
npx mlola-ui migrate --write    # make the changes
npx mlola-ui add button badge toast --overwrite   # the command it prints

リテラルで記述された props を書き換えます（variant="destructive" は variant="danger" に、Badge の variant は tone になります）。sonner と古い use-toast を Mlola の toast に移行し（toast.error は toast.danger になります）、switch を toggle に、また Mlola が提供する lucide-react のアイコンを、ファイル内のインポート形式に合わせて @mlola-ui/icons に置き換えます。実行時に計算される値、cva() ヘルパー、API が異なるコンポーネント（Dialog、Select、Dropdown Menu など）は変更せず、それぞれ置き換え先となる属性またはコンポーネントを示します。

コーディングエージェント

init（既存のプロジェクトでは agents）を実行すると、プロジェクトのコーディングエージェントに、UI が Mlola であることを伝えます。

• mlola.agents.md：すべてのクラス、data-* の値、トークン、および新しい UI のルールを含むデザインガイドです。
• AGENTS.md：ガイドへの参照をマーカーで囲んだ短いセクション（既存の内容にマージされ、上書きはされません）と、Claude Code 用にそれをインポートする CLAUDE.md です。
• .mcp.json（およびプロジェクトで使用している場合は .cursor/ または .vscode/）：Mlola MCP サーバーです。

npx mlola-ui mcp がそのサーバーです。この CLI に同梱されたレジストリを使ってオフラインで応答します。提供するツールは get_design_rules、search_components、get_component、get_tokens、check_markup（独自クラス、誤った data-* の値、ユーティリティクラス、手書きの色、--ml-space-* スケールから外れたスペーシング、style 属性・<style> ブロック・ユーティリティクラス内の薄いテキストを、それぞれ行番号とともに検出）、get_render_catalog、check_render、render_ui（下記の Mlola Render）、add_components、init_project です。init を使わずに Claude Code を設定する場合：

claude mcp add mlola --scope project -- npx -y mlola-ui mcp

エージェントによって起動され、stdio 経由で通信するため、手動で実行すると 1 行出力して待機します。コマンドを実行できないエージェント向けに、書き込みを行う 2 つのツールを除いた同じツールを https://ui.mlola.com/mcp でも利用できます（ビルド手順のないページ向けに、CDN リンクとスクリプトも提供する get_install_command を含みます）。このサーバーは MCP Registry に io.github.mlolahq/mlola-ui として登録されています。Cursor、VS Code、Codex、チャットアプリについては、https://ui.mlola.com/docs/agents をご覧ください。

Mlola Render

エージェントがコードを書く代わりにインターフェースを表示する場合（チャット内のフォームや、エージェントのアプリ内のステータスカードなど）、Mlola Render カタログのA2UI v0.9 メッセージを組み立てます。使用できるのは無料のコンポーネントと名前付きの値のみで、色やクラスは指定しません。検証では、カタログに沿っていることと、サーフェスが使いやすいこと（すべてのフィールドに名前があること、ルートが1つであること、ループがないこと、見出しの順序が正しいこと、値が範囲内であること）を確認し、A2UI の VALIDATION_FAILED 形式で応答するため、エージェントは自分のメッセージを修正できます。

npx mlola-ui render catalog          # what an agent may compose
npx mlola-ui render check ui.json    # an array, one message, or JSON Lines

import { validateRender } from "mlola-ui/render";
import rules from "mlola-ui/render/rules" with { type: "json" };

const { valid, errors } = validateRender(messages, rules);

MCP ツールは get_render_catalog、check_render、render_ui です。MCP Apps を表示するチャットでは、render_ui が会話内にサーフェスを描画します（そのビューはリソース ui://mlola/render です）。ユーザーが押した内容は、A2UI のアクションとともに、次のメッセージとしてエージェントに返されます。A2UI カタログは mlola-ui/render/catalog と https://ui.mlola.com/a2ui/catalog/v1 です。

自分で呼び出すモデルを使う場合、mlola-ui/render/ai はその呼び出しを取り巻く機能です。システムプロンプト、モデルの応答を読み取るリーダー（ストリーミング中でも、JSON のラップ形式にかかわらず対応します）、および拒否された応答をエラーとともに差し戻すループが含まれます。Mlola はモデルを呼び出さず、キーも保持しません。

import { composeRender } from "mlola-ui/render/ai";

const { valid, messages, turns } = await composeRender({
  rules,
  request: "A form to book a table for tonight",
  generate: ({ system, messages }) => callYourModel(system, messages), // answers with the model's text
});

renderSystemPrompt、renderTool、createRenderReader、readRenderReply、checkRenderReply、renderRepairPrompt は、ストリーム、ツール呼び出し、または独自のループで使用する各機能です。npx mlola-ui render prompt を実行すると、別の言語で書かれたサーバー向けのプロンプトが出力されます。

サーフェスを自分で描画するには、React では npx mlola-ui add render-surface を、フレームワークを使わないページでは @mlola-ui/behavior/render を使用してください。詳しくは https://ui.mlola.com/docs/render を参照してください。

Mlola Pro

Pro のコンポーネント、ブロック、ページ、テンプレートはこのパッケージには含まれません。ライセンスをお持ちの場合は、https://ui.mlola.com/account でトークンを作成してから、次を実行してください。

npx mlola-ui login mlp_…
npx mlola-ui add conversation bot

add は Pro アイテムとその Pro 依存関係をサービスから取得し、すべてのファイルの整合性ハッシュを確認して、ほかのアイテムと同じように書き込みます。無料の依存関係は引き続きこのパッケージから取得されます。Pro スタイルシートは styles/mlola-pro/ に配置され、styles/mlola-pro.css にまとめられます。エンジンのスタイルシートの後に、一度だけインポートしてください。プロジェクトのルートにある mlola-pro.agents.md には、コーディングエージェント向けのすべての Pro クラスと属性が記載されています。AGENTS.md からこのファイルを参照してください。CI では、ログインする代わりに MLOLA_PRO_TOKEN を設定します。トークンは ~/.config/mlola-ui/credentials.json に保存され、読み取れるのはご本人のみです。

設定

エイリアスとターゲットは mlola.config.json に記述します。

{
  "aliases": {
    "components": "@/components/ui",
    "blocks": "@/components/blocks",
    "pages": "@/app/pages",
    "templates": "@/app/templates"
  }
}

CLI はリポジトリをチェックアウトせずに npm tarball から動作し、パッケージ化されたインストールは CI でテストされています。

MIT ライセンスです。Mlola UI の一部です。