# 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）

確認:

```powershell
node --version
codex --version
claude --version
op --version
```

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

```powershell
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 ユーザー環境変数に保存します。

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

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

## セットアップ

```powershell
npm install
npm run build
```

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

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

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

## 起動確認

設定確認:

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

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

```powershell
.\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 です。

## 開発時の検証

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

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

## 公式資料

- [1Password: Load secrets into the environment](https://www.1password.dev/cli/secrets-environment-variables)
- [1Password CLI: op run](https://www.1password.dev/cli/reference/commands/run)
- [3D AI Studio API: Getting Started](https://www.3daistudio.com/Platform/API/Documentation/getting-started)
- [3D AI Studio API: Overview](https://www.3daistudio.com/Platform/API/Documentation/overview)
- [Claude Code: MCP](https://docs.anthropic.com/en/docs/claude-code/mcp)