Store Builder

sbuilder-mcp

AI エージェントが Store Builder サイトを最初から最後まで操作できる MCP stdio サーバーです。ページをデザインし、実際のデータを入力し、結果を確認して、 公開まで行います。人がクリックする必要はありません。

Tiếng Việt

インストール

1つのコマンドで、このサーバーをマシン上のすべてのエージェントクライアントに設定できます。

npx -y sbuilder-mcp install --token wbk_… --api https://your-host --site site_…

Claude Code、Claude Desktop、Cursor、Windsurf、VS Code、Codexに対応しており、見つかったクライアントにインストールします。--client cursor,codex で対象を指定するか、--dry-run で事前に確認できます。認識できないオプションは拒否され、無視されることはありません。何もしないフラグがひそかに存在するより、存在しないほうがよいからです。

--site は省略可能ですが、指定する価値があります。キーは1つのサイトにのみ属するため、SB_SITE として設定され、以降のすべてのツールでデフォルトとして使われます。指定しない場合、モデルはセッション中にサイトIDを保持する必要がありますが、そのIDを取得するにはページを一覧表示して、いずれかのページを読み込まなければなりません。

--site-name "Your Store" を指定すると、SB_SITE_NAME としてあわせて設定されます。これはラベルであり、アドレスではありません。これを使って何かが解決されることはありません。ただし、エージェントが、あなたが選んだものではない32文字のIDではなく、ストア名を伝えられるようになります。ストアに名前がある場合、Apps → AI agent 画面にこの値が追加されます。

これは設定をマージします。対象ファイル内の既存のサーバーはそのまま残り、置き換えられる設定は <file>.sbuilder-backup にコピーされます。解析できない設定ファイルは上書きせずに拒否します。破棄する価値のあるファイルより、末尾にカンマがあるファイルのほうがはるかに多く、修正が必要なのはそのファイルだからです。

ストアの Apps → AI agent 画面では、キーがあらかじめ含まれたこのコマンドを確認できます。

{
  "mcpServers": {
    "sbuilder": {
      "command": "npx",
      "args": ["-y", "sbuilder-mcp"],
      "env": { "SB_API": "https://api.your-host", "SB_TOKEN": "wbk_…", "SB_SITE": "site_…" }
    }
  }
}

キーの取得

ストアを開き、Apps → AI agent に移動して、Create key を押します。この画面では、キーがあらかじめ含まれたクライアント用の設定ブロックを確認できます。このセクションを読む手間を省けます。

必要なのはキー1つだけです。パートナー向けエンドポイント（/api/v1）と、ページドキュメントやライブ編集ソケットを含む非公開のサイトAPIの両方にアクセスできます。また、リクエストごとに3つの条件で制限されます。キー自体のスコープ、作成者であるメンバーの現在のロール、そしてキーが属する単一のストアです。

SB_EMAIL と SB_PASSWORD は引き続き省略可能で、使えるのはアカウントレベルの呼び出しのみです。サイトの一覧表示、メンバーやロールの管理などが該当します。これらは「この人のアカウント」を対象とするため、キーでは意図的に実行できません。

SB_API のデフォルト値は http://localhost:8080 です。シークレットは環境変数からのみ読み込まれます。

sb_media_upload の写真検索に、このサーバーのキーは不要です。プラットフォーム独自の GET /api/sites/{siteId}/images/search を呼び出し、サーバーがすでに保持している認証情報を使って、プロバイダーのキーをローテーションしながら検索します。運用者は、サーバー上で PEXELS_API_KEYS を設定して有効にします（カンマ区切り。無料のキーは https://www.pexels.com/api/ から取得できます）。キーが設定されていない場合、検索は「利用不可」と応答し、呼び出し元に独自の方法で写真を探してURLを渡すよう伝えます。その後、プラットフォームがサーバー側でURLから画像を取得します。このクライアントには、意図的に代替プロバイダーを設けていません。代替プロバイダーを設けると、プラットフォームが預かるためのキーを、すべてのインストール環境に持たせることになるからです。

ツール

すべての結果はコンパクトな JSON 形式で、各ディレクティブはプロセスごとに一度だけ通知され、すべてのツールに MCP アノテーションが付いています。それらを尊重するクライアントは、読み取りのたびに人へ確認を求めることがなくなります。

全リファレンス：docs/tools.md。ビルダーが標準でサポートする機能と、その範囲外となる部分については、docs/capabilities.mdをご覧ください。

同期の仕組み

プラットフォームは、生成されたコミット済みのアーティファクトを2つ公開します。ビルドステップでチェックアウトからこれらを読み取り、カタログを生成します。

WB_REPO=/path/to/web_builder npm run codegen

そのため、このリポジトリはプラットフォームのコードをベンダーとして取り込まず、仕様が維持されている2つのデータファイルに依存しています。src/catalog/api.generated.tsはコミット済みなので、npm installにチェックアウトは必要ありません。

開発

npm run build     # tsc -> dist/
npm test          # vitest
npm run smoke     # offline self-test; must print ALL GOOD

コントリビューターガイド：CLAUDE.md。設計の根拠： docs/superpowers/specs/。

リリース

src/**に変更を含むmainへのプッシュは単独でリリースされます（.github/workflows/auto-release.yml）。ゲートでビルド、テスト、スモークテストが実行され、バージョンの更新内容はコミットの件名から判断されます。featはマイナー、BREAKING CHANGEまたは!はメジャー、それ以外はパッチです。Claudeが両言語で変更履歴を作成し、server.jsonを同期したうえで、chore(release): vX.Y.Zとしてリリースをコミットしてタグ付けし、その後、npm、GitHub Release、GitHub OIDC経由のMCP Registryに公開します。workflow_dispatchでは、選択した更新内容で同じフローを実行します。件名にchore(release):またはrelease: vを含むコミットはスキップされるため、リリースが次のリリースを引き起こすことはありません。

このワークフローには、prod環境のリポジトリシークレットが2つ必要です。NPM_ACCESS_TOKENとCLAUDE_CODE_OAUTH_TOKENです。レジストリのステップにシークレットは不要です。

npm run release（scripts/release.mjs）はオフライン用の手順です。CIのないマシンや、シークレットのローテーション中にリリースを作成する場合に使います。同じゲートを実行し、同じ## [x.y.z] - date形式の変更履歴見出しを書き込むため、2つの方法で食い違うことはありません。

安全な設計

クライアントが知らなければひそかに失敗するプラットフォームのルールが5つあるため、注意事項ではなく、テスト済みのコードとしてここに実装しています。

• バンドの順序 — ROOTの子要素は[header][middle][footer]の順に並ぶ必要があります。そうでない場合、プラットフォームはすべての保存を拒否します。
• サイトオーバーレイ（カートドロワー、ポップアップ）は読み取り時にROOTへ合成され、書き込み時に除外されます。ROOTレベルのすべてのルールの対象外であり、ページツールから編集することはできません。
• グローバルセクションは共有マスターです。1つを編集すると、それを含むすべてのページが変わり、公開も連鎖します。これらに触れる結果には、その旨が示されます。
• 標準でレスポンシブ — sb_setはブレークポイントごとに書き込みます。デザインは画面に応じて変化するべきだからです。ベースはカスケードのフォールバック層であり、制約ではありません。
• アプリブロック — マーケットプレイスアプリのサブツリーは読み取り時にページへ合成され、保存時には1つの参照ノードに戻されるため、内部を編集しても何も通知されず変更が失われます。すべての書き込みで内部への変更が拒否され、アウトラインではブロックのルートにapp: trueのフラグが付きます。

状況

3つのフェーズすべてをリリース済みです。認証とAPI全体へのアクセス、ページドキュメント・パッチプロトコル・ビルダーと5つの落とし穴、ライブ編集ソケット・yieldルール・ビジョンループです。その後、すべての結果のトークン消費量を削減し、リリースを自動で作成する仕組みを追加しました。

Node ≥22（グローバルのWebSocket）が必要です。また、sb_lookのみシステムにインストールされたGoogle Chromeが必要です。playwright-coreにはブラウザーが含まれていないため、インストール時にダウンロードは発生しません。

MIT。