---
name: conoha-storage-operations
description: ConoHa Object Storage（Swift）の基本操作ガイド。コンテナ作成・一覧・削除、オブジェクト一覧・削除、署名済みURL（TempURL）によるアップロード／ダウンロード、Web 公開設定などを操作する際に参照する。「オブジェクトストレージ」「Object Storage」「Swift」「コンテナ」「バケット」「アップロード」「ダウンロード」「署名URL」「TempURL」「conoha_storage_list」「conoha_storage_presign_upload」などのキーワードで発動する。
---

# ConoHa Object Storage 操作ガイド

## 前提条件

- MCP クライアントが ConoHa Object Storage MCP（`/vps/swift-mcp`）に接続済みで、OAuth 認可が完了していること
- テナントID（`{tenantId}`）は MCP サーバーが OAuth アクセストークンから自動取得する。パス中の `{tenantId}` は**そのままのリテラル文字列**で指定してよく、ユーザーが実際のテナントIDを入力する必要はない
- スコープ: 読み取り系ツールは `vps:read`、作成・更新・削除系は `vps:write`

## ツール概要

| ツール名                          | 種別 | 概要                                                           |
| --------------------------------- | ---- | -------------------------------------------------------------- |
| `conoha_storage_list`             | 読取 | コンテナ一覧 / コンテナ内オブジェクト一覧                      |
| `conoha_storage_stat`             | 読取 | アカウント情報 / コンテナ詳細 / オブジェクトメタデータ（HEAD） |
| `conoha_storage_create_container` | 作成 | コンテナ作成（PUT）                                            |
| `conoha_storage_set_metadata`     | 更新 | アカウント容量クォータ設定 / コンテナの Web 公開 ACL 設定      |
| `conoha_storage_presign_upload`   | 作成 | アップロード用の署名済み URL（TempURL）発行                    |
| `conoha_storage_presign_download` | 読取 | ダウンロード用の署名済み URL（TempURL）発行                    |
| `conoha_storage_delete`           | 削除 | コンテナ削除 / オブジェクト削除（`confirm: true` 必須）        |

パス・引数の詳細は [tool-path-reference.md](references/tool-path-reference.md)、ヘッダー・戻り値スキーマは [request-body-schemas.md](references/request-body-schemas.md) を参照。

## 絶対遵守制約

1. **オブジェクト本体は署名URL経由必須** — オブジェクトのアップロード／ダウンロードは必ず `conoha_storage_presign_upload` / `conoha_storage_presign_download` で発行した TempURL を使う。MCP サーバーはファイル本体を経由しない。5MiB のサイズ制限はなく、大容量ファイルも扱える
2. **削除は明示確認必須** — `conoha_storage_delete` は必ず `confirm: true` を指定する。削除は元に戻せない
3. **公開ACLは明示確認必須** — コンテナを全体公開（`X-Container-Read: ".r:*"`）する場合、必ず `publicReadConfirm: true` を併せて指定する。公開は URL を知る誰でもアクセス可能になるため、事前にユーザーへ確認する
4. **X-Container-Read は固定値のみ** — `""`（公開解除）または `".r:*"`（全体公開）のみ指定可
5. **クォータは100GB単位** — `X-Account-Meta-Quota-Giga-Bytes` は GB 単位・100GB 刻みで指定する（例: `"100"`, `"200"`, `"300"`）
6. **署名URLの有効期限は短めに** — `ttlSeconds` は 60〜3600 の範囲。推奨 600（10分）。期限超過後は 401 になる。ダウンロードURLは特に短く設定する
7. **署名URLはメソッド限定** — アップロードURLは PUT 専用、ダウンロードURLは GET 専用。逆メソッドは ConoHa 側で弾かれる

## 実行ポリシー（curl の扱い）

**`curl` などのコマンドを実行できる環境（シェル）がある場合は、アシスタントが自分で実行してアップロード／ダウンロードまで完結させる。コマンド文字列をユーザーに提示して確認・手動実行させない。**

- 転送は内部処理として扱い、ユーザーには**結果だけ**を伝える（例:「アップロードしました」「保存しました」）
- presign で返る署名付き URL（`temp_url_sig=...` を含む長い URL）や生の `curl` は原則ユーザーに見せない（内部で使う）
- 事前確認を取るのは破壊的・不可逆な操作（公開設定・削除）のみ。presign 発行・転送はいちいち確認しない
- **例外（コマンドを提示するケース）**: 次のいずれかの場合は、自分で実行せず、そのままコピーして実行できる完全な `curl` コマンドをユーザーに提示する
  - シェル実行環境が無い
  - AI クライアントがコマンド実行を許可されていない（サンドボックスやネットワーク遮断・権限設定で `curl` が実行できない／拒否される）
  - 実行を試みて拒否・失敗した場合も、以降はコマンド提示に切り替える

## パス体系

すべて `/v1/AUTH_{tenantId}` を基点とする。

```text
/v1/AUTH_{tenantId}                        … アカウント（一覧: コンテナ / stat: アカウント情報 / 容量クォータ設定）
/v1/AUTH_{tenantId}/{container}            … コンテナ（一覧: オブジェクト / stat: コンテナ詳細 / 作成 / 公開ACL / 削除）
/v1/AUTH_{tenantId}/{container}/{object}   … オブジェクト（stat: メタデータ / 署名URL / 削除）
```

- **Web 公開 URL 形式**: `https://object-storage.c3j1.conoha.io/v1/AUTH_{tenantId}/{container}/{object}`
  - ホストは環境／リージョン依存（上記は代表例）。presign や公開の正確なホストは、`conoha_storage_presign_*` が返す URL に従うのが確実

## ワークフロー判定ツリー

### コンテナ作成フロー

```text
1. conoha_storage_list path="/v1/AUTH_{tenantId}" → 既存コンテナを確認（重複回避）
2. conoha_storage_create_container input.path="/v1/AUTH_{tenantId}/<コンテナ名>" → 作成
3. （任意）conoha_storage_stat path="/v1/AUTH_{tenantId}/<コンテナ名>" → 作成確認
```

### オブジェクトアップロードフロー（署名URL）

```text
1. （未作成なら）コンテナ作成フローを実施
2. conoha_storage_presign_upload path="/v1/AUTH_{tenantId}/<コンテナ名>/<オブジェクト名>" ttlSeconds=600 [contentType=...]
   → { url, expiresAt } を取得
3. 返却URLへ PUT でアップロード（シェルがあり実行が許可されていればアシスタントが直接実行し結果のみ報告。シェルが無い／実行が許可されない・拒否される場合は curl を提示）:
   curl -T <ローカルファイル> -X PUT '<url>'          （contentType 指定時は -H "Content-Type: <contentType>" を付与）
4. （任意）conoha_storage_stat でアップロード結果を確認
```

### オブジェクトダウンロードフロー（署名URL）

```text
1. conoha_storage_list path="/v1/AUTH_{tenantId}/<コンテナ名>" → 対象オブジェクト名を確認
2. conoha_storage_presign_download path="/v1/AUTH_{tenantId}/<コンテナ名>/<オブジェクト名>" ttlSeconds=600
   → { url, expiresAt } を取得
3. 返却URLへ GET でダウンロード（シェルがあり実行が許可されていればアシスタントが直接実行し結果のみ報告。シェルが無い／実行が許可されない・拒否される場合は curl を提示）:
   curl -o <保存先> '<url>'
```

### Web 公開 / 公開解除フロー

```text
■ 公開
  1. ユーザーに公開の意思を確認
  2. conoha_storage_set_metadata input={ path:"/v1/AUTH_{tenantId}/<コンテナ名>",
       headerparam:{ "X-Container-Read": ".r:*", "publicReadConfirm": true } }
  3. 公開URL: https://object-storage.c3j1.conoha.io/v1/AUTH_{tenantId}/<コンテナ名>/<オブジェクト名>

■ 公開解除
  conoha_storage_set_metadata input={ path:"/v1/AUTH_{tenantId}/<コンテナ名>",
    headerparam:{ "X-Container-Read": "" } }
```

### 容量クォータ設定フロー

```text
1. conoha_storage_stat path="/v1/AUTH_{tenantId}" → 現在の使用量・クォータを確認
2. conoha_storage_set_metadata input={ path:"/v1/AUTH_{tenantId}",
     headerparam:{ "X-Account-Meta-Quota-Giga-Bytes": "<100GB単位>" } }
```

### 情報取得フロー

| 取得対象                           | ツール                | path                                       |
| ---------------------------------- | --------------------- | ------------------------------------------ |
| コンテナ一覧                       | `conoha_storage_list` | `/v1/AUTH_{tenantId}`                      |
| オブジェクト一覧                   | `conoha_storage_list` | `/v1/AUTH_{tenantId}/{container}`          |
| アカウント情報（使用量・クォータ） | `conoha_storage_stat` | `/v1/AUTH_{tenantId}`                      |
| コンテナ詳細                       | `conoha_storage_stat` | `/v1/AUTH_{tenantId}/{container}`          |
| オブジェクトメタデータ             | `conoha_storage_stat` | `/v1/AUTH_{tenantId}/{container}/{object}` |

### 削除フロー

```text
■ オブジェクト削除
  conoha_storage_delete path="/v1/AUTH_{tenantId}/{container}/{object}"
    param="/v1/AUTH_{tenantId}/<コンテナ名>/<オブジェクト名>" confirm=true

■ コンテナ削除（原則、中のオブジェクトを全削除してから）
  1. conoha_storage_list path="/v1/AUTH_{tenantId}/<コンテナ名>" → 残オブジェクトを確認
  2. 残があれば各オブジェクトを削除
  3. conoha_storage_delete path="/v1/AUTH_{tenantId}/{container}"
       param="/v1/AUTH_{tenantId}/<コンテナ名>" confirm=true
```

## ユーザー発話パターンとツール対応

| 発話パターン                       | 使用ツール                                  |
| ---------------------------------- | ------------------------------------------- |
| 「コンテナ（バケット）を作って」   | `conoha_storage_create_container`           |
| 「ファイルをアップロードして」     | `conoha_storage_presign_upload`             |
| 「ファイルをダウンロードして」     | `conoha_storage_presign_download`           |
| 「コンテナ / オブジェクトの一覧」  | `conoha_storage_list`                       |
| 「使用量 / 容量 / クォータを確認」 | `conoha_storage_stat`（アカウント）         |
| 「コンテナを公開して / 公開解除」  | `conoha_storage_set_metadata`               |
| 「容量上限を上げて」               | `conoha_storage_set_metadata`（アカウント） |
| 「削除して」                       | `conoha_storage_delete`（`confirm: true`）  |

## エラー対応ガイド

| エラー           | 原因                                            | 対処                                                             |
| ---------------- | ----------------------------------------------- | ---------------------------------------------------------------- |
| 401 Unauthorized | OAuth 認可切れ / scope 不足 / 署名URLの期限切れ | 再認可し `vps:read` / `vps:write` を確認。署名URLは再発行        |
| 403 Forbidden    | 公開 ACL 未設定のオブジェクトへ匿名アクセス     | `conoha_storage_set_metadata` で公開設定、または署名URLを使う    |
| 404 Not Found    | コンテナ / オブジェクトが存在しない             | `conoha_storage_list` で名称を再確認                             |
| 409 Conflict     | 空でないコンテナの削除等                        | 中のオブジェクトを全削除してからコンテナを削除                   |
| 413 / 容量超過   | クォータ超過                                    | `conoha_storage_stat` で使用量確認、クォータ引き上げ or 不要削除 |

## リファレンス

- [ツール別パス・引数一覧](references/tool-path-reference.md)
- [ヘッダー・戻り値スキーマ集](references/request-body-schemas.md)
- [主要操作のワークフローレシピ](references/workflow-recipes.md)