Polyxd

@polyxd/mcp

Polyxd 用の MCP サーバーです。ホストのモデルが生成を担います。サーバーは仕様を指示としてモデルに渡し、モデルが作成する UI ドキュメントをチェックし、任意のデザインシステムパックで Polyxd レンダラーが描画したものを MCP App としてユーザーに表示します。

npx -y @polyxd/mcp        # stdio

アカウント登録もサインインも不要なホスト型サーバーには、URL で接続することもできます。

https://mcp.polyxd.com/mcp

URL で接続する

• Claude（claude.ai、およびアカウント経由の Claude Desktop）：Customize > Connectors > Add custom connector を選び、URL を貼り付けて No sign-in を選びます。
• Claude Code：claude mcp add --transport http polyxd https://mcp.polyxd.com/mcp
• ChatGPT：開発者モードを有効にし（Settings > Security and login）、URL と認証なしで chatgpt.com/plugins に追加します。
• Cursor：~/.cursor/mcp.json に { "mcpServers": { "polyxd": { "url": "https://mcp.polyxd.com/mcp" } } } を設定します。
• VS Code：.vscode/mcp.json に { "servers": { "polyxd": { "type": "http", "url": "https://mcp.polyxd.com/mcp" } } } を設定します。

stdio 経由でホストに追加する

Claude Desktop（claude_desktop_config.json）およびほとんどの MCP クライアント：

{
  "mcpServers": {
    "polyxd": { "command": "npx", "args": ["-y", "@polyxd/mcp"] }
  }
}

Claude Code：

claude mcp add polyxd -- npx -y @polyxd/mcp

このリポジトリをクローンした場合は、npm install && npm run build -w @polyxd/mcp を実行し、コマンドとして node <repo>/packages/mcp/dist/bin.js を指定します。

ツール

ツール	機能	structuredContent
polyxd_guide	指示としての仕様です。これらのツールの使い方に続いて、デモで使用する生成プロンプト（ドキュメントの構造、生成する画面のルール、バインディング、アクション、すべてのコンポーネントとその props、パターン）が含まれます。	{ specVersion, guide }。guide はコンテンツと同じテキストです
polyxd_validate	ドキュメントを検証します。各問題には JSON Pointer、該当するコンポーネント、および変更箇所を示すヒントが含まれます。	{ valid, errors, warnings, issues[{ severity, pointer, component?, message, hint? }] }
polyxd_verify	ドキュメントに対する検証チェックです（@polyxd/verifier/static の staticAudit を使用するため、サーバーのインストール時に Playwright はインストールされません）。Design Direction（オブジェクト、または calm-finance / playful-personal）や機能レジストリを指定して検証することもできます。簡潔なレポートを返します。	{ errors, warnings, findings[{ severity, check, message, hint? }], direction?, rules }
polyxd_show	ドキュメントを検証してから、表示用に返します。pack でデザインシステムパックを選択し（デフォルト：material3）、mode でライトまたはダークを選択します（デフォルト：ホストのテーマ）。エラーがある場合は何も表示しません。	{ shown: true, document, pack, packName, mode?, specVersion }、または isError を伴う { shown: false, issues }
polyxd_packs	公開済みのデザインシステムとオリジナルのテンプレートを含むパックです。	{ default, packs[{ name, displayName, template, package, description }] }
polyxd_components	各コンポーネントの概要を1行ずつ返します。name を指定すると、該当するコンポーネントの完全な定義を返します。	{ components[{ name, category, summary, shell }] }、または完全な定義を含む { component }
polyxd_docs	このバージョンに同梱されている polyxd.com のドキュメントを検索します。query に最もよく一致するセクション、ページ全体、またはページ一覧を返します。	{ sections[{ page, title, heading, url, text }] }、{ page }、または { pages[] }

すべてのツールは読み取り専用です。data はドキュメントとは別に polyxd_validate、polyxd_verify、polyxd_show に渡すことができ、その場合はドキュメント自身の data を置き換えます。

すべてのツールは outputSchema（JSON Schema 2020-12、src/output-schemas.ts に定義され、各プロパティはモデル向けに説明されています）を宣言し、成功した結果はすべてそのスキーマに準拠する structuredContent を含みます。SDK は送信前に各結果をチェックします。エラー結果（isError: true）はスキーマへの準拠を求められません。polyxd_show の非表示結果は引き続きスキーマに準拠しますが、その他のツールはテキストのみを返します。

リソース

• ui://polyxd/surface.html (text/html;profile=mcp-app)：MCP Appです。
• polyxd://examples/<name>.json：仕様のサンプルドキュメントです。
• polyxd://directions/<name>.json：仕様のサンプル Design Directions です。

MCP App

polyxd_show は、MCP Apps 拡張（SEP-1865、2026-01-26）に従って _meta.ui.resourceUri: "ui://polyxd/surface.html" と、ChatGPT のエイリアス openai/outputTemplate を宣言します。MCP Apps に対応するホストはこのリソースを読み込み、サンドボックス化された iframe 内に描画します。このページは自己完結型です。@polyxd/web レンダラー、レンダラーのスタイルシート、および各パックのテーマをインライン化しており、外部オリジンを使わないため、ホストのデフォルトのコンテンツセキュリティポリシーで十分です。

リソースの _meta には、各ホスト向けの情報が記載されています（appResourceMeta()）。

• ui.csp：{ connectDomains: [], resourceDomains: [] }。ページは何も読み込みません。
• ui.prefersBorder: true。
• ChatGPT 固有のキー：openai/widgetCSP（同じ空のリスト）、openai/widgetPrefersBorder、openai/widgetDescription、および openai/widgetDomain: "https://mcp.polyxd.com"。これは ChatGPT がアプリのサンドボックスに割り当てるオリジンです。
• ui.domain はありません。Claude はここにコネクター URL のハッシュを必要とし、ChatGPT はオリジンを必要とします。また Claude は、ui.domain が独自の形式でないアプリの描画を拒否します。このページには固定のオリジンが不要なため設定せず、代わりに ChatGPT は openai/widgetDomain を読み取ります。

このページは postMessage を介して MCP Apps プロトコルを使用します。まず ui/initialize を送り、続いて ui/notifications/initialized を送ります。ui/notifications/tool-result 通知の structuredContent からドキュメントを描画し、選択されたパックを使います。テーマは、mode が指定されていない場合、ホストの theme に応じてライトまたはダークになります。ページは ui/notifications/size-changed で高さを通知します。

ユーザーがアクションを押すと、ページは ui/message を送信します。そこには、そのアクションを示すユーザーメッセージ、ボタンのラベル、アクションのコンテキスト（ユーザーが入力した内容を含む、アクションにバインドされた値）が含まれます。

[Polyxd] In the "New task" screen I pressed "Add task" (action task.save).
Context: {"title":"Buy milk","due":"2026-10-01"}

モデルはこれをユーザーの次のメッセージとして受け取り、それに応じて動作します。画面を閉じる操作（ui.dismiss）も同じ方法で届きます。MCP Apps に対応していないホストには、代わりに polyxd_show のテキスト要約が表示されます。

プロンプト

ジェネレーターのプロンプトは @polyxd/runtime に由来し、仕様から生成されます。src/packs.generated.ts にはパックが一覧表示され、src/spec-files.generated.ts は仕様のコンポーネント定義とサンプルを JSON モジュールとしてインポートするため、サーバーはファイルを読み込みません。npm run sync -w @polyxd/mcp を実行すると両方が書き換えられ、どちらかが古い場合はテストが失敗します。

HTTP 経由

@polyxd/mcp/http は、MCP の Streamable HTTP トランスポートを介して同じサーバーを、ウェブ標準の (Request) => Promise<Response> ハンドラーとして提供します。Node の機能を一切使わないため、Cloudflare Worker、Deno、または Bun で実行できます。

import { createHttpHandler, rateLimiter } from "@polyxd/mcp/http";
import viewHtml from "@polyxd/mcp/view.html"; // bundled as text

const mcp = createHttpHandler({ viewHtml: () => viewHtml, rateLimit: rateLimiter({ limit: 600, windowMs: 60_000 }) });
export default { fetch: (request: Request) => (new URL(request.url).pathname === "/mcp" ? mcp(request) : new Response(null, { status: 404 })) };

トランスポートは SDK の createMcpHandler で、ステートレスです。リクエストごとに新しいサーバーを作成し、セッションはありません。2025 年頃のクライアントに対しては、独立したストリームもセッションもないサーバーについて仕様が求めるとおり、GET と DELETE は 405 を返します。各リクエストにバージョンを含める 2026-07-28 プロトコルのクライアントにも対応します。周辺の機能は次のとおりです。

• 本文サイズの上限：maxBodyBytes のデフォルトは 1 MiB で、超過時は 413 を返します。まず Content-Length を確認し、さらに本文の読み込み時にも確認します。
• タイムアウト：応答全体に適用される timeoutMs のデフォルトは 15 秒です。遅れて届いた応答には JSON-RPC エラーを返します。通常は 504、SSE ストリームではリクエストの ID に対するエラーを返します。
• レート制限：rateLimit(request) が false を返すと、Retry-After を付けて 429 を返します。rateLimiter() は CF-Connecting-IP をキーにしたメモリ内の固定ウィンドウ方式です。プロセスまたは Worker isolate ごとにカウントするため、ベストエフォートです。
• CORS：サーバーは認証情報もユーザーデータも保持しないため、すべてのオリジンを許可します。プリフライトでは要求されたヘッダーを許可し、レスポンスでは Mcp-Session-Id と Mcp-Protocol-Version を公開します。
• ログ：リクエストごとに、メソッド、パス、ステータス、処理時間を 1 行に記録します。それ以外は記録しません。本文、ヘッダー、クエリ文字列、アドレス、エラーメッセージは記録しません。

ホステッドサーバー

https://mcp.polyxd.com/mcp は apps/mcp で、Cloudflare Worker です。/mcp は上記のハンドラー、/health は JSON を返し、/ はドキュメントにリダイレクトします。ビューはテキストとして Worker にバンドルされています（合計約 2.4 MB、gzip 圧縮時 385 KB）。レート制限には Cloudflare のレート制限バインディングを使用しており、IP アドレスごとに 1 分あたり 600 リクエストです。このバインディングは Cloudflare のロケーションごとにカウントするため、正確なクォータを適用するのではなく、リクエストの殺到を防ぎます。Claude と ChatGPT はそれぞれ独自のサーバーから呼び出すため、制限は余裕のある設定です。wrangler.jsonc では Cloudflare の呼び出しログ、トレース、Issues が無効になっているため、Worker 独自のログだけが保持されます。POSTHOG_KEY シークレットを設定すると、ホステッド Worker は初期化とツール呼び出しも匿名でカウントします（apps/mcp/src/analytics.ts）。記録するのは名前と件数だけで、ドキュメント、そのデータ、アドレスは記録しません。このパッケージと npx @polyxd/mcp は、どこにもデータを送信しません。

npm run dev -w @polyxd/mcp-remote                        # wrangler dev on http://127.0.0.1:8787/mcp
node apps/mcp/scripts/smoke.ts http://127.0.0.1:8787/mcp  # every tool, in both protocol eras, over real HTTP
npm run deploy -w @polyxd/mcp-remote                     # builds @polyxd/mcp, then wrangler deploy

デプロイすると、polyxd.com ゾーンに mcp.polyxd.com カスタムドメインが作成されます。workers.dev とプレビュー URL は無効になっています。

MCP Registry

server.json は、ホステッドサーバーを MCP Registry に com.polyxd/mcp として登録するための情報を記述します。com.polyxd 配下の名前を使うには、polyxd.com を管理していることを証明する必要があります。

openssl genpkey -algorithm Ed25519 -out key.pem
echo "polyxd.com. IN TXT \"v=MCPv1; k=ed25519; p=$(openssl pkey -in key.pem -pubout -outform DER | tail -c 32 | base64)\""
mcp-publisher login dns --domain polyxd.com --private-key "$(openssl pkey -in key.pem -noout -text | grep -A3 'priv:' | tail -n +2 | tr -d ' :\n')"
mcp-publisher publish      # from packages/mcp

これには OpenSSL 3 が必要です（macOS の LibreSSL は Ed25519 に対応していません）。key.pem は非公開にし、リポジトリに含めないでください。TXT レコードは apex の polyxd.com に設定します。HTTP による証明も可能です。同じ v=MCPv1; k=ed25519; p=... の行を https://polyxd.com/.well-known/mcp-registry-auth で配信し、mcp-publisher login http を使います。mcp.polyxd.com ではなく polyxd.com である必要があります。mcp.polyxd.com で証明した場合、対象になるのは com.polyxd.mcp 配下の名前だけです。

リリースワークフローは、npm にバージョンが公開された後、各バージョンタグで server.json をレジストリに公開します。公開時には MCP_REGISTRY_KEY Actions シークレットに保存された秘密鍵（上記の --private-key コマンドが出力する 16 進文字列）を使ってサインインします。シークレットがない場合、またはレジストリにそのバージョンがすでに登録されている場合、このステップは通知を出してスキップされます。

server.json にはホステッドサーバー（remotes）と npm パッケージ（packages）の両方が記載されているため、ホストはどちらも提供できます。レジストリは package.json のパッケージの mcpName を確認します。server.json の 2 つの version フィールドは、package.json と一致させてください。一致を確認するテストがあります。

ビルドとテスト

npm run build -w @polyxd/mcp     # tsc, then scripts/build-view.ts writes dist/view.html
npm test -w @polyxd/mcp
npm test -w @polyxd/mcp-remote   # the Worker's routes

テストでは、クライアントをメモリ内でサーバーに接続し、すべての仕様例と不正なドキュメントに対してすべてのツールを呼び出します。ビルド済みのバイナリを起動し、stdio 経由で JSON-RPC をやり取りします。Streamable HTTP でサーバーを SDK クライアントに提供し、2 つのプロトコル世代の両方でテストします。また、クライアントライブラリなら送信しない生のリクエスト（不正な JSON、サイズ超過の本文、過剰なリクエスト、プリフライト、応答の遅延）も送信します。HTTP エントリを Worker 向けにバンドルし、Node から何も必要としないことを確認します。さらに、ヘッドレス Chromium で MCP App を読み込み、テストがホストの役割を担って、ハンドシェイクから ui/message としてアクションが届くまでを確認します。Playwright に Chromium がない場合、ブラウザテストはスキップされます（npx playwright install chromium）。