3D AI Studio Secure MCP

Windows の Codex / Claude Code から 3D AI Studio REST API を操作するための MCP サーバーです。API キーは 1Password Environments から op run --environment により子プロセスへ実行時だけ注入されます。

セキュリティ境界

• Git、MCP設定、コマンドライン引数に API キーを保存しません。
• MCP サーバーは THREED_AI_STUDIO_API_KEY の存在だけを確認し、値を出力しません。
• op run の標準マスキングを維持します（--no-masking は使用しません）。
• 読み取りツールと課金ツールを分離し、課金ツールは confirmCreditSpend: true を必須にします。
• 上流の非構造化エラー本文は返しません。

同一 Windows ユーザーの別プロセスが環境変数を読める可能性は残ります。信頼できないプロセスと同時に実行せず、必要なら最小権限の 1Password Service Account を使ってください。

必要条件

• Windows 10/11、PowerShell 5.1+
• Node.js 20+
• Codex CLI または Claude Code
• 1Password CLI 2.33.0-beta.02 以降（1Password Environments は公式ドキュメント上 beta）

確認:

node --version
codex --version
claude --version
op --version

1Password CLI がない場合は、公式案内に従ってインストールします。通常版が要件を満たす場合:

winget install 1password-cli

op --version が要件未満の場合は、1Password の公式 beta 配布から 2.33.0-beta.02 以降を導入してください。

1Password Environment

1Password アプリの Developer > Environments に Environment を1つ作り、次の変数だけを追加します。

変数	値
THREED_AI_STUDIO_API_KEY	3D AI Studio ダッシュボードで一度だけ表示される API キー

Environment の Manage environment > Copy environment ID で ID をコピーします。Environment ID は秘密値ではありませんが、リポジトリには固定せず Windows ユーザー環境変数に保存します。

[Environment]::SetEnvironmentVariable(
  "THREED_AI_STUDIO_OP_ENVIRONMENT_ID",
  "<Environment ID>",
  "User"
)

新しいターミナルを開いてください。API キー自体を PowerShell に設定したり、.env に保存したりしないでください。

セットアップ

npm install
npm run build

Codex と Claude Code に非秘密の stdio 起動設定を登録:

.\scripts\register-clients.ps1 -Client Both

個別に登録する場合は Codex または Claude を指定します。登録内容は PowerShell ランチャーのパスだけで、API キーも Environment ID も含みません。

起動確認

設定確認:

codex mcp get 3d-ai-studio
claude mcp get 3d-ai-studio

1Password 経由のプロセス起動を確認:

.\scripts\start-mcp.ps1

正常時は stdio MCP サーバーとして待機します。終了は Ctrl+C です。Codex / Claude Code を再起動し、MCP一覧に 3d-ai-studio が表示されることを確認してください。

最初は課金しない get_credit_balance を呼び出してください。生成は料金とプロンプトを確認後に限り generate_rapid_text_to_3d を使います。3D AI Studio の生成 API は非同期のため、返された task UUID を get_generation_status で確認します。

MCPツール

• get_credit_balance: 残高取得（非課金）
• get_generation_status: 生成状態取得（新規生成なし）
• generate_rapid_text_to_3d: Rapid Text-to-3D生成（課金、明示確認必須）

API Base URL は https://api.3daistudio.com、認証は Bearer token です。

開発時の検証

npm run check
npm test
git grep -n -I -E "(api[_-]?key|token|secret).{0,30}[=:].{1,}" -- .

最後の検索結果は変数名や説明を人間が確認するためのものです。実キーをテストに使わないでください。

公式資料

• 1Password: Load secrets into the environment
• 1Password CLI: op run
• 3D AI Studio API: Getting Started
• 3D AI Studio API: Overview
• Claude Code: MCP