pixoo-mcp-server

---

概要

ローカルネットワーク上の Divoom Pixoo LED マトリックスディスプレイに対応しています。主な対象は Pixoo-64 ですが、16 と 32 もサポートしています。スタイル付きテキスト、レイヤー化されたシーン、ダッシュボード、アニメーション、HTML ページをレンダリングして送信したり、デバイスの状態を読み取って変更したりできます。

ツール

ツール	説明
pixoo_display_text	テーマ、グラデーション、シャドウ、自動フィットを使ってスタイル付きテキストをレンダリングし、静止画またはアニメーションとして送信します
pixoo_compose_scene	テキスト、アイコン、ウィジェット、図形、ビットマップ、画像、スプライトを重ねたシーンを作成します。静止画とアニメーションに対応しています
pixoo_push_image	ローカル画像または https 画像を LED グリッドに合わせてリサイズして送信します。アニメーション GIF または WebP はアニメーションとして送信します
pixoo_render_html	HTML ページ（CSS、SVG、Canvas、WebGL）を、パネルサイズに合わせてヘッドレスブラウザーでレンダリングし、静止画または仮想時計に基づくフレーム単位のアニメーションとして送信します
pixoo_overlay_text	デバイスでレンダリングされるスクロールテキストのオーバーレイを設定または解除します
pixoo_control_device	明るさ、画面の状態、チャンネル、時計盤を読み取ったり変更したりします
pixoo_discover_devices	Divoom のクラウド検出を通じて Pixoo デバイスとその LAN IP アドレスを見つけます
pixoo_design_brief	デザインのテーマに関するガイダンスを作成します。デバイスの最新状態と、入力済みの次の呼び出しを含みます

リソース

リソース	説明
pixoo://device/status	デバイスのライブスナップショット：到達可能性、チャンネル、明るさ、画面の状態、表示サイズ
pixoo://reference/themes	テーマとパレットの一覧
pixoo://reference/icons	カテゴリ別の組み込みアイコン名
pixoo://reference/design-guide	64px ディスプレイ向けの詳細な制作ガイド

ツールのみを利用するクライアントも、同じ機能を利用できます。pixoo_control_device はデバイスのライブ状態を読み取り、pixoo_design_brief は制作ガイダンス、テーマ名、アイコン名を返します。

機能リファレンス

pixoo_display_text _tool

• text は文字列または行の配列です。theme（midnight、ember、claude、ice、neon、forest、mono）は背景とデフォルトのパレットを設定します。style には、palette のグラデーション（ember、ice、neon、fire、lavender、claude、mono）またはカスタムの { from, to } に加え、shadow、outline、scale 1～8 を指定します。position は意味的な位置またはピクセル単位の位置で、align は複数行のテキストを揃えます
• font：standard（5×7）と compact（3×5）は、印字可能な ASCII 文字に加えて ° ← ↑ → ↓ ▲ ▼ ♥ · … を描画します。それ以外の文字（€、’、1つの文字列内の改行など）は ? として表示され、レスポンスの notice にはコードポイントと行インデックスが記載されます。numerals は時計や数値表示向けの 11×18 の数字フォントで、0～9、スペース、および : . - + / % ° ? を描画します。それ以外の文字を含むテキストは検証に失敗し、該当する文字が示されます
• layout[] は各種のフィット判定を action として報告します（テキストがコンパクトフォントでのみ収まる場合は shrunk-to-compact、返されるフレームがスクロールする場合は scrolling、それ以外は none）。また、使用する font と、各行のボックスがパネルに fits するかどうかも報告します。1行がパネルの幅を超え、スクロールしない場合は、x 0 から始まり、右端で切り取られます。単一行のテキストは、font が設定されていない場合、標準フォントからコンパクトフォントに切り替わりますが、numerals には切り替わりません。テキストがそれでも幅を超える場合、effect: "auto" または "scroll" のときにのみスクロールします
• effect：scroll は最大 40 フレームで1回スクロールし、auto はオーバーフローした場合にのみスクロールします。float と pulse は 20 フレームにわたってループします。frames はフレーム数を報告し、アニメーションは1つのデバイスアニメーションとして送信されます

pixoo_compose_scene _ツール

• text（pixoo_display_text と同じ3種類のフォント）、icon、rect、circle、line、progress、sparkline、bitmap、pixels、image（絶対パスまたは https URL。pixoo_push_image と同じ finish を使用）、sprite（絶対パス）を、背面から前面の順に最大50個の elements として描画します。background は単色、v / h / r のグラデーション、または theme です
• 各要素では opacity（各ピクセルに固有のアルファ値 × opacity が適用されるため、ソフトエッジも均等にフェードします）と blend（normal、add（発光や光線向け）、screen、multiply）を指定します。line と輪郭のみの circle では strokeWidth と antialias を、rect の枠線では内側に広がる strokeWidth を指定できます。ストロークを描画しない図形にいずれかのフィールドを指定すると、該当フィールド名を示して検証に失敗します
• layout[] が返されます。各要素の配置ボックス（幅のあるストロークまたはアンチエイリアス処理されたストロークの場合は、描画されるすべてのピクセル）と、パネル内に収まるかどうかが含まれます。要素は指定された順に配置され、再フィットされないため、action は常に none です。絶対パスの output を指定すると、PIXOO_OUTPUT_DIR への自動保存の代わりに、最初のフレームが PNG としてその場所に保存されます。型付きエラー：asset_not_found、invalid_image（読み込まれたもののデコードできない画像またはスプライト）、invalid_color、unknown_icon、invalid_output_path
• 要素ごとのエフェクトプリセット（float、scroll-left、scroll-right、pulse、blink、twinkle、drift、fade-in、fade-out）または dx、dy、opacity（数値または数値文字列）、visible（true / false）、color（color を持つあらゆる要素でRGBを通じて補間）の生の animate キーフレームを使ってアニメーションできます。各トラックには少なくとも1つのキーフレームが必要です。frames は1～800、speed は1フレームあたり10～2000 ms（デフォルトは150）です。40フレームを超えると、シーンはデバイスがこのホストからダウンロードする1つのGIFとして再生され、speed は10 ms単位に丸められます。要素には effect または animate のどちらか一方を指定し、両方は指定できません。エフェクトの amplitude は、float、scroll-*、drift の移動量と、pulse および twinkle の不透明度低下の深さ（0～1）を設定します

---

pixoo_push_image _ツール

• source はローカルの絶対パスまたは https URL です。ダウンロードサイズの上限は10 MBです。fit は contain（デフォルト）、cover、fill、kernel は nearest（デフォルト。ピクセルアート向け）、lanczos3（写真向け）、mitchell です
• ファイル名にかかわらず、アニメーション GIF または WebP としてデコードされるソースは、最大 maxFrames フレーム（1～800、デフォルトは40）のアニメーションとして送信されます。長いソースは均等にサンプリングされ、40フレームを超えると、デバイスがこのホストからダウンロードする1つのGIFとして再生されます。再生時間は、ソース全体の再生時間を送信フレーム数で割ったもの（ソースに遅延時間の記録がない場合は150 ms）か、speed（1フレームあたり10～2000 ms）です。frames、sourceFrames、speed は送信された内容を示します
• finish を指定すると、送信前に画像がパレットに減色されます。colors（画像から生成。2～256色）または palette（16進数または名前付きカラー。1～256色）のどちらか一方を指定し、さらに dither（none、bayer4、floyd-steinberg）を指定します。透明ピクセルは消灯したままになり、アニメーションの colors パレットはすべてのフレームで共有されます
• 読み取れないパスまたは URL は asset_not_found、読み込まれたもののデコードできないソース（テキストファイル、HTMLページ、不完全なダウンロード）は invalid_image、解決できない finish のパレット項目は invalid_color として失敗します。プレビューにはデバイスが受信するフレームそのもの、またはアニメーションのフレーム一覧がグリッドで表示されます

---

pixoo_render_html _tool

• html は完全なドキュメントまたは本文フラグメントで、最大500,000文字です。CSSピクセル1つをLED 1個に対応させた正方形のビューポートにレイアウトされます。ページがパネルになります。body に余白はなく、スクロールバーは非表示で、背景を描画しないページは黒（消灯）でレンダリングされます。ページ独自のCSSが各LEDを上書きします

• frames は1～800（デフォルトは1）、speed はフレームあたり10～2000 ms（デフォルトは150）です。各フレームで仮想時計が speed だけ進みます。ページで定義されている場合、window.render(t, frame) は各キャプチャの前に実行され、t = frame / frames となるため、周期的な動きはシームレスにループします。requestAnimationFrame、setTimeout / setInterval（ネストされたタイマーと繰り返しタイマーでは最小4 ms）、Date（実際の時刻から開始）、performance.now()（読み込み時に0）は同じ時計に従い、CSSアニメーションもその時刻に一時停止してシークされるため、すべてのフレームが決定論的に描画されます。requestIdleCallback と iframe は実時間のままです。40フレームを超えると、pixoo_compose_scene と同様に、デバイスがこのホストからダウンロードするGIFとしてページが再生されます

• sampling は native（デフォルト）または supersample です。後者は8倍の解像度でレンダリングし、各LEDにエリア平均化して、変形、テキスト、SVG、canvasを滑らかにします。Chromiumは拡大縮小の前に通常のボックスの端をCSSピクセル単位の整数にスナップするため、left: 0.5px のボックスも1つのLED上に配置されます。サブピクセル移動には transform を使用してください。finish には pixoo_push_image と同じパレット縮小が適用され、プレビューの前に処理されます

• ネットワークからの読み込みは行われず、ワーカーはブロックされます。pageErrors はページで捕捉されなかったエラー、console.error の出力、ブロックされたURL（ブロックされたナビゲーションは Blocked navigation: <url>）を返します。最初の20件がそれぞれ500文字に切り詰められます。window.render が例外をスローするか拒否された場合は、フレーム番号を示す page_error で失敗します。ブラウザーが見つからない場合は、インストール手順を含む browser_unavailable で失敗します（前提条件を参照）。render_timeout と render_crashed は、それぞれレンダリングが30秒を超えた場合、ブラウザーまたはページがクラッシュした場合を示します。PIXOO_HTML_ENABLED=false にすると、このツールは無効になります

• すべてのページには、ブラウザーのアンチエイリアスでLED上ににじむのを防ぐ、くっきりしたビットマップテキスト、パレット、アイコン用の pixoo グローバルが、ページ独自のスクリプト実行前に追加されます。

  • pixoo.context() は、ページ上に固定配置されたパネルサイズの透明キャンバスの2Dコンテキストです。
  • pixoo.text(ctx, text, x, y, { font, color, palette, scale, shadow, outline }) は、pixoo_display_text のフォントを描画します。
  • pixoo.icon(ctx, name, x, y, { w, h, color, palette }) は、レジストリのアイコンを描画します。
  • pixoo.palettes は7つのパレットを、pixoo.size はパネルサイズを保持します。

  この方法で描画したテキストとアイコンは、どちらのサンプリングモードでも pixoo_compose_scene とピクセル単位で一致します。不明なパレット、アイコン、色が指定されると、その名前を示す例外が発生します。

  <script>
    const ctx = pixoo.context();
    pixoo.text(ctx, 'HELLO', 'center', 4, { palette: 'ember', scale: 2, shadow: true });
    pixoo.icon(ctx, 'check-circle', 50, 50, { color: 'green' });
  </script>
  

• トピックを html にした pixoo_design_brief では、ループ、時計、サンプリング、pixoo ランタイム、64 pxでの読みやすさを扱います。ループごとにパネルを1周するドットの例：

{
  "html": "<svg viewBox=\"0 0 64 64\" style=\"display:block;width:100vw;height:100vh\"><circle id=\"dot\" r=\"6\" fill=\"#ffb000\"/></svg><script>const dot = document.getElementById('dot'); window.render = (t) => { const a = 2 * Math.PI * t; dot.setAttribute('cx', 32 + 20 * Math.cos(a)); dot.setAttribute('cy', 32 + 20 * Math.sin(a)); };</script>",
  "frames": 20,
  "speed": 100,
  "sampling": "supersample"
}

---

pixoo_overlay_text _tool

• 20個のスロットのいずれか（id 0～19）で mode: "set" または "clear" を指定します。set では text が必須です。また、デバイスの font ID（0～114）、PIXOO_SIZE 内の x / y、color、speed（0～100）、direction、align、width を指定できます
• acknowledged、mode、id を返します。オーバーレイはデバイスでレンダリングされるため、プレビューはありません。消去するまでチャンネルを切り替えても表示され続けます

---

pixoo_control_device _tool

• パラメーターなしの場合は状態を読み取ります。brightness（0～100）、screen（on / off）、channel（faces / cloud / visualizer / custom）、clockFaceId のいずれかを指定すると、読み取り結果を返す前に適用されます
• reachable、channel、brightness、screenOn、clockId（到達不能な場合は省略）と applied を返します。設定に失敗した項目は applied から除外され、呼び出し自体を失敗させるのではなく、通知に項目名が記載されます

---

pixoo_discover_devices _ツール

• Divoom のクラウドエンドポイント（app.divoom-gz.com）に問い合わせるため、インターネットアクセスが必要です。timeoutMs は 1000～30000（デフォルトは 5000）です。
• 各デバイスの name、id、ip を返します。PIXOO_IP が設定されている場合、configuredIpFound は一致したかどうかを示します。エンドポイントに到達できない場合は discovery_failed で失敗します。

---

pixoo_design_brief _ツール

• topic：text、scene、dashboard、animation、pixel-art、html、troubleshooting のいずれかです。到達可能なデバイスがなくても動作します。
• Markdown 形式の craftGuidance、ライブの deviceContext、htmlRenderer（利用可能な場合は available、PIXOO_HTML_ENABLED=false の場合は disabled、ブラウザーを起動せずに検出した場合は no_browser）、トピックとデバイスの状態に合わせて引数が事前入力された { toolName, reason, args } 形式の nextToolSuggestions に加え、availableThemes と iconCategories を返します。

---

pixoo://device/status _リソース

• キャッシュされないライブ読み取り：reachable、channel、brightness、screenOn、clockId、displaySize、configuredIp
• デバイスに到達できない場合や PIXOO_IP が未設定の場合は、エラーではなく reachable: false を返します。

---

pixoo://reference/themes _リソース

• 各テーマ（背景、textPalette、accent、shadow）と各パレット（from／to の停止点）に加え、theme および palette パラメーター用の themeNames と paletteNames を返します。
• 静的レジストリで、24 時間キャッシュされます。

---

pixoo://reference/icons _リソース

• 各アイコンの name、category、viewBox に加え、カテゴリ（weather、arrows、status、media）ごとの byCategory グループを返します。name は pixoo_compose_scene のアイコン要素に指定します。
• 静的レジストリで、24 時間キャッシュされます。

---

pixoo://reference/design-guide _リソース

• text/markdown：読みやすさの最低基準、パレットの使い方、レイアウトゾーン、アニメーション予算、エフェクトプリセット、ピクセルアートのルール、送信の間隔、既知のデバイス動作を記載しています。
• ガイド全体をまとめたドキュメントです。pixoo_design_brief はトピックごとのガイダンスを返します。24 時間キャッシュされます。

機能

@cyanheads/mcp-ts-core を基盤としています。stdio および Streamable HTTP トランスポート、差し替え可能な認証（none / jwt / oauth）、差し替え可能なストレージ（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1）、オプションの OpenTelemetry トレースに対応した構造化ログを備えています。

Pixoo 固有の機能：

• すべての合成処理は、RGBA キャンバスのパイプライン（@cyanheads/pixoo-toolkit）を使用してホスト上で行われます。デバイスには完成した RGB フレームが送信されます。
• プッシュすると、デバイスはカスタムチャンネルに切り替わります。デバイスのフリーズを防ぐため、プッシュは一度に 1 つずつ、PIXOO_PUSH_MIN_INTERVAL_MS（デフォルトは 1000）で指定した間隔を空けて実行されます。
• アニメーションのフレーム数が 40 以下の場合、各リクエストで最大 40 フレームをプッシュします。それを超えるフレームのプッシュはデバイスを不安定にします。40 フレームを超える場合、pixoo_compose_scene、pixoo_push_image、pixoo_render_html（最大 800 フレーム）は、このホスト上の一度限りのリスナーから GIF を 1 つ提供し、デバイスがそれをダウンロードしてループ再生します。そのため、デバイスからこのホストにアクセスできる必要があります。pixoo_display_text は 40 フレーム以内に収まります。

エージェントに適した出力：

• すべてのレンダリングでプレビューを表示します。pixoo_display_text、pixoo_compose_scene、pixoo_push_image、pixoo_render_html は、プッシュの有無にかかわらず、フレームを 8 倍に拡大した PNG 画像ブロックとして返します。そのため、push: false を使えば、デバイスを接続せずにデザインを確認できます。MCP クライアントによって GIF の表示が異なるため、アニメーションはフレームのグリッドとしてプレビューされます（1 倍サイズのタイルが 512 px のシートに収まる場合はすべてのフレーム、それを超える場合は均等にサンプリングしたフレーム）。GIF 自体は PIXOO_OUTPUT_DIR が設定されている場合に保存されます。保存されるのは、8 倍プレビュー GIF、または 40 フレームを超える場合はデバイスがダウンロードするパネルサイズの GIF です。
• レイアウトの透明性：layout[] には、フォントのフォールバック、スクロール、各ボックスがパネルに収まるかどうかなど、レンダラーのすべての判断が報告されるため、エージェントはデザインを調整できます。
• デバイスの状態を正確に反映します。pushed はデバイスの ACK を反映します。40 フレームを超える場合は、再生の ACK とデバイスによる GIF リクエストを反映します（ファイル全体は送信用に OS に渡されます。デバイスは受信を確認しません）。プッシュ後に読み戻される deviceState には、レンダリングが表示されない場合、対処方法を示す通知が付属します（画面がオフ、明るさが 10 以下、カスタムチャンネル以外）。
• プッシュに失敗してもレンダリング結果は保持されます。4 つすべてのレンダリングツールで、型付きエラー（device_unreachable、device_http_error、device_rejected、gif_serve_failed、no_device_configured）には、保存されたプレビューを示す outputFiles が含まれます（PIXOO_OUTPUT_DIR のコピー、または未設定の場合は一時ファイル）。

はじめに

PIXOO_IP に Pixoo の LAN アドレスを設定し、以下を MCP クライアントの設定ファイルに追加します。アドレスがわからない場合は、pixoo_discover_devices で検出できます。

{
  "mcpServers": {
    "pixoo-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/pixoo-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "PIXOO_IP": "192.168.1.50"
      }
    }
  }
}

または npx を使用する場合（Bun は不要です）：

{
  "mcpServers": {
    "pixoo-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/pixoo-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "PIXOO_IP": "192.168.1.50"
      }
    }
  }
}

または Docker を使用する場合：

{
  "mcpServers": {
    "pixoo-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "-e", "PIXOO_IP=192.168.1.50",
        "-e", "PIXOO_SERVE_HOST=192.168.1.20",
        "-e", "PIXOO_SERVE_PORT=8765",
        "-p", "8765:8765",
        "ghcr.io/cyanheads/pixoo-mcp-server:latest"
      ]
    }
  }
}

デバイスは 40 フレームを超えるアニメーションをこのホストからダウンロードします。Docker のデフォルトのブリッジネットワークでは、デバイスにルーティングされるアドレスはコンテナ自身のアドレスであり、デバイスからはアクセスできません。上記のように、PIXOO_SERVE_HOST に Docker ホストの LAN アドレスを設定し、固定の PIXOO_SERVE_PORT を公開してください。40 フレーム以下の場合、どちらも必要ありません。

Streamable HTTP を使用するには、トランスポートを設定してサーバーを起動します。

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 PIXOO_IP=192.168.1.50 bun run start:http
# Server listens at http://localhost:3010/mcp

前提条件

• Bun v1.4.0 以降（または Node.js v24 以降）。
• ローカルネットワーク上の Divoom Pixoo（Pixoo-64、Pixoo-32、または Pixoo-16）。
• HTML レンダラーを使用する場合は任意：chrome-headless-shell。npx @puppeteer/browsers install chrome-headless-shell@stable --path ~/.cache/puppeteer を実行すると、サーバーがデフォルトで参照する場所にインストールされます。--path <dir> を指定して別の場所にインストールした場合は、インストール時に表示される実行ファイルのパスを PIXOO_BROWSER_PATH に設定してください。サーバーは、レンダリングに必要な場合にのみ、DevTools ポートを開かずにヘッドレスで起動します。

インストール

1. リポジトリをクローンします：

git clone https://github.com/cyanheads/pixoo-mcp-server.git

2. ディレクトリに移動します：

cd pixoo-mcp-server

3. 依存関係をインストールします：

bun install

4. 環境を設定します：

cp .env.example .env
# edit .env and set PIXOO_IP

設定

変数	説明	デフォルト
PIXOO_IP	ローカルネットワーク上のデバイスの IP アドレスです。プッシュ、オーバーレイ、デバイス制御には必須です。検出、デザイン概要、push: false のレンダリングは、この値がなくても動作します。	—
PIXOO_SIZE	ディスプレイのサイズ（ピクセル単位）です。16、32、64 のいずれかを指定します。	64
PIXOO_OUTPUT_DIR	レンダリングツールがプレビュー用の PNG ファイルと GIF ファイルを保存するディレクトリです。相対パスはサーバーの起動元ディレクトリを基準に解決されるため、報告される保存先パスは絶対パスになります。未設定の場合、プレビューはレスポンス内でのみ返されます。	—
PIXOO_PUSH_MIN_INTERVAL_MS	デバイスへのプッシュ間の最小間隔（ミリ秒）です。	1000
PIXOO_SERVE_HOST	40 フレームを超えるアニメーションをデバイスがダウンロードする URL で、PIXOO_IP へのルーティングに OS が使用するローカルアドレスの代わりに通知されるホストです。リスナーは、いずれの場合もそのルーティング先アドレスにバインドされます。NAT の背後やコンテナー内で実行する場合に設定してください。	—
PIXOO_SERVE_PORT	ファイアウォールルールやコンテナーポートの公開に使用する、ダウンロード用のワンショットリスナーの固定ポートです。未設定の場合、再生ごとに空きポートが使われます。	—
PIXOO_BROWSER_PATH	HTML レンダリングに使用するブラウザーの実行ファイルです。設定すると、そのブラウザーのみが試されます。実行可能ファイルではないパスを指定すると、フォールバックせずに失敗します。相対パスは起動ディレクトリを基準に解決されます。未設定の場合、Puppeteer のキャッシュ（~/.cache/puppeteer）にある最新の chrome-headless-shell が使用されます。Docker イメージにはブラウザーが含まれていません。	—
PIXOO_HTML_ENABLED	pixoo_render_html を提供します。false にすると tools/list から削除されます。ブール値以外を指定すると、起動に失敗します。	true
MCP_TRANSPORT_TYPE	トランスポートです。stdio または http を指定します。	stdio
MCP_HTTP_PORT	HTTP サーバーのポートです。	3010
MCP_SESSION_MODE	HTTP セッションモードです。stateless、stateful、auto のいずれかを指定します。ここで値を設定すると、サーバーが宣言する stateless より優先されます。	stateless
MCP_AUTH_MODE	認証方式です。none、jwt、oauth のいずれかを指定します。	none
MCP_LOG_LEVEL	ログレベルです（debug、info、warning、error など）。	info
LOGS_DIR	ログファイルのディレクトリです（Node.js のみ）。	<project-root>/logs
LOG_TOOL_FAILURE_PAYLOADS	失敗したツール呼び出しごとに、引数と結果をログに記録します。キー名による編集が行われ、LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES（デフォルトは 16384）で上限が設定されます。自由形式の値に含まれるシークレットは編集されません。	false
OTEL_ENABLED	OpenTelemetry を有効にします。	false

省略可能なオーバーライドの全一覧は .env.example を参照してください。

サーバーの実行

ローカル開発

• ビルドして実行：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• チェックとテストを実行：

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  
  # Real-browser suite for the HTML renderer (opt-in; launches the named browser)
  PIXOO_TEST_BROWSER_PATH=/path/to/chrome-headless-shell bun run test:browser
  

Docker

docker build -t pixoo-mcp-server .
docker run --rm -e PIXOO_IP=192.168.1.50 -p 3010:3010 \
  -e PIXOO_SERVE_HOST=192.168.1.20 -e PIXOO_SERVE_PORT=8765 -p 8765:8765 \
  pixoo-mcp-server

PIXOO_SERVE_HOST（Docker ホストの LAN アドレス）と公開された PIXOO_SERVE_PORT を設定すると、上記の stdio 構成と同様に、コンテナー内からデバイスが 40 フレームを超えるアニメーションをダウンロードできます。

Dockerfile では、デフォルトで HTTP トランスポート、ステートレスセッションモードが使用され、ログは /var/log/pixoo-mcp-server に記録されます。OpenTelemetry のピア依存関係はデフォルトでインストールされます。これらを除外するには、--build-arg OTEL_ENABLED=false を指定してビルドしてください。

プロジェクト構成

ディレクトリ	目的
src/index.ts	createApp() エントリーポイント：ツールとリソースを登録し、Pixoo サービスを初期化します。
src/config/	Zod を使用した、サーバー固有の環境変数の解析と検証を行います。
src/mcp-server/tools/	ツール定義（*.tool.ts）、レンダリング後の共通プッシュ処理、共通の finish 入力スキーマを格納します。
src/mcp-server/resources/	リソース定義（*.resource.ts）を格納します。
src/services/pixoo/	PixooService：@cyanheads/pixoo-toolkit をラップし、プッシュ間隔の調整、結果のマッピング、デバイス状態の読み取りを行います。
src/services/browser/	BrowserRenderer：隔離されたヘッドレスの chrome-headless-shell で HTML をレンダリングします。DevTools Protocol のパイプ経由で制御し、パネルフレームとしてキャプチャします。
src/renderer/	デバイスに依存しない純粋なレンダリングパイプラインです。要素レンダラー、スタイル付きテキストエンジン、テーマ、アイコン、エフェクトコンパイラー、パレットの仕上げ、プレビューのエンコード、リモート画像の取得、HTML ページに注入する仮想時計を含みます。
tests/	src/ に対応するユニットテストと統合テストを格納します。

開発ガイド

開発ガイドラインとアーキテクチャ上のルールについては、CLAUDE.md/AGENTS.md を参照してください。要点は次のとおりです。

• ハンドラーは例外をスローし、フレームワークが捕捉します。ツールのロジックで try/catch は使用しません
• リクエスト単位のログには ctx.log を、テナント単位のストレージには ctx.state を使用します
• レンダラー（src/renderer/）は純粋で、デバイスに依存せず、ハードウェアなしでテストできます
• デバイスへの呼び出しはすべて PixooService 経由で行います。すべての PixooResult を確認し、プッシュが成功したと決めつけないでください

コントリビュート

Issue を歓迎します。提出前にチェックとテストを実行してください。

bun run devcheck
bun run test

ライセンス

Apache-2.0 — 詳細は LICENSE をご覧ください。