IceShore

ADL のノードに、規範的な注意点（humanNote）を保存する（ログインが必要・editor または admin 権限）。同じ ref_path への保存は上書き（UPSERT）で、1 ノードに有効なノートは最大 1 件。 text: 200 字以内。「〜のため〜にする」「〜なので〜禁止」の規範の形。固有名詞は書ける。1 ノードの複数の観点は 1 文にまとめて書く。 ref_path はサーバが ADL と照合する: 見つからないときは reason="ref_path_not_found" と、当たった最長の前置（matched_prefix）、そこにあるキー（candidates）を返す。ADL が読めないときは reason="adl_unavailable"。"$ref" の先はたどらない。ADL に "contexts" という欄は無い（実体は "useCases"）。 ノートの下書きをローカルにためてから保存する進め方は iceshore://guide/common に書いてある。 入力: content_id, ref_path, text, lang（すべて必須）。 出力: { ok, mode: "inserted"|"updated", defined_at, updated_at }。

IceShore への接続と認証の状態を返す。 入力: なし。 出力: 認証成功なら userId と所属組織一覧（organizations: workspace_id / name / role）、失敗（トークンの無効・失効など）なら error を含む文字列。 organizations[].workspace_id は、create_content / commit_uploaded_codes の登録先（workspace_id）や list_projects の絞り込みに使える値。 組織への登録ができるのは、role が admin または editor の組織。

複数のプロビジョニングファイルの presigned PUT URL を、1 回の呼び出しで N 件（最大 100）発行する（ログインが必要）。 各 upload_url は HTTP PUT でファイル本体を受け付ける（有効期限 10 分・並列可）。シェルを実行できるクライアントでの例: curl --silent --show-error --fail -X PUT --upload-file <ローカルパス> '<upload_url>'。 アップロードしたファイルは commit_uploaded_codes で構成図に取り込まれる。ADL 本体（adr）も 1 ファイル分足して送れ、commit_uploaded_codes の code_entries で is_root:true を付けると inline の adl_root が要らない。 urls[] の順序は入力 files[] と同じ。同じバッチに同じ code_id が 2 件あるとエラー。staging はユーザ × project_id ごとに分かれる。 入力: files（1〜100 件・必須）、project_id（追記時）。 出力: project_id, urls: [{code_id, upload_url, content_key}, ...], expires_in（=600）。

request_upload_url / batch_request_upload_url の URL へ PUT したファイルを、IceShore プロジェクトの codes に取り込む（ログインが必要）。新規プロジェクトはこの呼び出しで作られ、既存プロジェクトにはマージ（MERGE）で追記・更新し、指定しなかった既存ファイルは温存する。 マージのルール: code_id が一致すれば上書き、新しい code_id は末尾に追加、code_entries に無い既存ファイルはそのまま残る（save_content の全置換とは違う）。adl_root（または is_root:true のエントリ）を渡すと ADL 本体を置き換え、省くと既存のまま。 ADL 本体の渡し方は 2 通り: code_entries の 1 件に is_root:true（staged 経由・大きな ADL 向け）、または引数 adl_root に JSON 文字列（inline・小さな ADL 向け）。両方あれば inline を使う。旧称 cloud_design_root も受け付ける。 品質評価（KGI）と構成図は保存時にサーバ側で作られるので、画面で保存し直す必要はない。info.version と info.status もサーバが決める（version は保存のたびに +1 される整数、status は品質評価から designed / prepared / draft を自動で決める）。応答には構成図の URL が含まれる。 code_entries の各 code_id は、PUT 済みでなければ 400。is_root:true は 1 件まで。ファイルの削除は扱わない（delete_code または save_content）。 notes（任意・配列）: 変更の 1 行要約。save_content と同じ形で、構成図の「履歴」タブに残る。応答の「記録した変更サマリー: N 件」が記録された件数。 入力: project_id（必須）、code_entries（必須・空配列可）、adl_root（新規時に必要・staged の is_root があれば不要）、overview（新規時に必要）、workspace_id（新規時の登録先）、notes。 出力: id と構成図の URL。

新しい IceShore プロジェクトを作る（ADL と添付ファイルを登録する。ログインが必要）。既存プロジェクトの更新は save_content が扱う。 codes の形: 配列のうち 1 件が ADL 本体（id="adlRoot", isRoot=true, lang="adl", fmt="json", data=ADL を JSON.stringify した文字列）。残りはプロビジョニングファイルを 1 件 1 エントリ（isRoot=false）。ADL 本体が無いと画面では空になる。ADL の構造は iceshore://guide/adl に書いてある。 例: { "codes": [ { "id": "adlRoot", "isRoot": true, "lang": "adl", "fmt": "json", "data": "{"reindeer":"2.0.0","self":"adl.json",...}" }, { "id": "main.tf", "isRoot": false, "lang": "tfm", "fmt": "hcl", "data": "resource "aws_lambda_function" ..." } ], "overview": { "titles": {"en": "...", "ja": "..."}, "descriptions": {"en": "...", "ja": "..."}, "version": "1.0.0", "type": "private", "security": "publicHandling" } } overview は必須。IaC リポジトリからの新規インポートでは importSource（originUrl / webUrl / webKind / repoPath / lastImportedCommit / lastImportedAt / importMethod。手元のフォルダのパスは送らない）を、変更履歴として changeLog（at / by / source / summary / delta / securityNotices）を持てる（iceshore://guide/iac-import・iceshore://guide/changelog）。 workspace_id: "personal"（個人）または組織の ID（auth_check の organizations[].workspace_id）。省くと個人。組織への登録にはその組織の admin / editor 権限が要り、無ければ 403。登録先は作成時だけ指定でき、後から MCP では変えられない（画面から変える）。 大きさ: 1 回あたり約 5 MB まで（同期リクエストの上限 6 MB）。合計が大きいとき・ファイルが多いときは batch_request_upload_url + commit_uploaded_codes の経路がある。 保存前に、アクセスキー・パスワード・トークンなどに見える値は ***MASKED*** に置き換えて保存する。 出力: 新しい id（"d" で始まる内部 ID）と構成図の URL。失敗時は ok:false と error。

プロジェクトの codes から 1 件のファイルを削除する（ログインが必要）。ADL 本体（adlRoot）は削除できない（必要なら save_content の全置換）。 1 ファイル分の読み書きだけで済み、全 codes を送り直す save_content より速い。構成図は保存時にサーバ側で作り直される。 入力: project_id, code_id（どちらも必須）。 出力: { ok: true, id, removed: true|false }。removed:false は、その code_id が元から無かったことを示す。

ADL ノードの humanNote を論理削除する（is_deleted=1・ログインが必要・editor または admin 権限）。行は消さないので、同じ ref_path に add_note すると復活する。 入力: content_id, ref_path（どちらも必須）。 出力: { ok, mode: "deleted"|"not_found" }。

git の origin URL（またはローカルの絶対パス）から、IceShore のプロジェクト（ADL）を探す（ログインが必要）。 用途: IaC のインポート前に、同じリポジトリがインポート済みかを調べる（済みなら更新 = save_content、未なら新規 = create_content の対象になる）。手順は iceshore://guide/iac-import に書いてある。 入力: origin_url。 出力: 見つかれば found=true と id・title・updatedAt、無ければ found=false。

【認証不要（公式サンプルの公開コンテンツのみ）】匿名では公式サンプルだけを返し、それ以外はログインが必要（401）。IceShore プロジェクト 1 件の ADL と添付ファイルを返す。 用途: 既存プロジェクトの参照、保存・更新の結果の確認（get_content(mode='detail') の戻りが保存後の実際の状態の正典）。 id は list_projects または list_samples が返す、"d" で始まる内部 ID。 mode の違い: - "meta": メタ情報だけ。S3 を読まないので速い（10 秒以上短い） - "root": ADL 本体（adlRoot）だけ - "detail": 全ファイル。大きく、30 秒ほどかかる場合がある 出力: { code, id, mode, data, type, role, ownerID, ... }。

【認証不要】匿名（未ログイン）でも使える。IceShore のガイド文書（ADL の書き方・登録手順・分析の進め方など）を名前で返す。 MCP リソースに対応していないクライアント向けの取得手段で、対応クライアントは resources/read でも同じ内容を読める。 主な名前: "analysis"（業務影響・依存・外部波及の分析）/ "registration"（システム登録）/ "fix"（ADL の修正）/ "adl"（ADL の作り方）/ "saving-publishing"（保存と公開）。 入力: name（短縮名または URI パス）。知らない name のときは、使える名前の一覧を返す。 出力: ガイド本文（markdown / JSON。本文は英語）。

プロジェクトの humanNote（人が ADL のノードに残した規範的な注意点）を返す（ログインが必要）。1 ノード（ref_path）につき有効なノートは最大 1 件。 用途: 既存プロジェクトを編集するときの確認、人が編集した形跡（_meta.d が "h:" で始まる）のあるノードの参照、特定ノードについての質問への回答。 refs（任意・配列）: 取得するノードの ref_path。省くと全件（最大 500 件）。 ref_path が今の ADL に無いノートは、ノードの削除や改名で取り残されたもの。 出力: { code, id, data: { notes: [{ note_id, ref_path, text, lang, defined_by, defined_at, updated_at }] } }。

既存プロジェクトの codes 配列のメタデータ一覧を返す（ファイル中身 data は含まない）。差分アップロードの判定に使う。 各エントリの sha256 は、data フィールド（文字列）を SHA-256 にかけた値。テキストファイルなら、ローカルの shasum -a 256 <file> の結果と一致する。 sha256 が一致するファイルは変更なしで、不一致または一覧に無いファイルだけを request_upload_url / batch_request_upload_url → commit_uploaded_codes で送れば足りる。 入力: project_id。 出力: codes: [{code_id, isRoot, lang, fmt, size, sha256}]。

ユーザが閲覧権限を持つプロジェクト（ADL 構成図）の一覧を返す（ログインが必要）。 用途: 作業対象のプロジェクトの特定。業務影響・規模・依存関係を分析するときに、get_content で ADL を取る前の起点になる。 ページング: 既定は page=0 / itemperpage=24。続きは page=1, 2, …。itemperpage の最大は 100。 サンプルとの関係: range を省くと range="related" と同じで、公式サンプルは含まない（サンプルは list_samples が返す）。 workspace_id を渡すと、その 1 組織が所有する案件だけに絞り込む（値は auth_check の organizations[].workspace_id）。 入力: range, page, itemperpage, workspace_id（すべて省略可）。 出力: プロジェクトの id とタイトルの一覧（プレーンテキスト）。末尾に total / totalPages。

【認証不要】匿名（未ログイン）でも使える。サンプルのワークスペース（公式のサンプル・OSSのサンプルなど）の公開構成図の一覧を返す（ログイン時も同じ）。 用途: 新しい設計の参考事例、サンプルを土台にした作成。 list_projects との違い: list_projects は自分が閲覧権限を持つプロジェクト（サンプルを含まない）、本ツールはサンプルだけ。 ワークスペース: 既定はすべてのサンプルのワークスペース。workspace で1つに絞れる（一覧の先頭にサンプルのワークスペースの名前と id を出す）。 ページング: 既定は page=0 / itemperpage=24。 入力: page, itemperpage, workspace（すべて省略可）。 出力: 公開プロジェクトの id とタイトルの一覧。末尾に total / totalPages。

プロビジョニングファイル 1 件分の、S3 への presigned PUT URL を発行する（ログインが必要）。ファイルが複数なら batch_request_upload_url が 1 回で N 件を発行する。 返る upload_url は HTTP PUT でファイル本体を受け付ける（有効期限 10 分）。シェルを実行できるクライアントでの例: curl --silent --show-error --fail -X PUT --upload-file <ローカルパス> '<upload_url>'。ファイル中身はディスクから S3 へ直接送られ、会話の出力トークンにならない。シェルを使えないクライアントでは、create_content / save_content が中身を引数で受け取る。 アップロードしたファイルは commit_uploaded_codes で構成図に取り込まれる。ADL 本体（adr）も同じ経路で送れ、commit_uploaded_codes の code_entries で is_root:true を付けると inline の adl_root が要らない。 project_id を省くと新しい project_id を採番する。同じ project_id で同じ code_id を発行し直すと、commit 時に後のものが使われる。staging はユーザ × project_id ごとに分かれ、他ユーザの project_id には発行できない（403）。 入力: code_id, lang, fmt（必須）、project_id（追記・更新時）。 出力: upload_url, content_key, project_id, expires_in。

既存の IceShore プロジェクトの ADL と添付ファイルを更新する（ログインが必要・所有者または admin / editor 権限）。新規作成は create_content が扱う。 全置換（full-replace）: codes に渡したものがすべてになり、未指定の既存ファイルは削除される（allow_code_deletion を付けたときだけ削除を受け付ける）。既存ファイルを残すには、変更しないものも含めて全 codes を送る。現在の codes は get_content(mode='detail') で取れる。一部のファイルだけ足す・直すなら、マージする commit_uploaded_codes がある。 codes の形は create_content と同じ（1 件が ADL 本体 adlRoot）。overview は必須。 notes（任意・配列）: 変更の 1 行要約。[{ at: <UNIX 秒・整数>, content: "<100 字以内>" }] の形で、構成図の「履歴」タブに残る。応答の「記録した変更サマリー: N 件」が記録された件数。 info.version と info.status はサーバが決める: version はサーバが採番し、保存のたびに +1 される整数（送った値は使われない）、status は品質評価から designed / prepared / draft を自動で決める（"reviewed" は自動では下げない）。応答の「改訂 N / status: X」が保存後の値。 品質評価（KGI）と構成図は保存時にサーバ側で作られる。 IaC から更新するときに人が足した内容（resources[*].lessons、useCases[*].notes、IaC に無い actors など）の扱いは iceshore://guide/iac-import に書いてある。 保存前に、アクセスキー・JWT・秘密鍵・接続文字列などに見える値は ***MASKED*** に置き換えて保存し、置き換えた箇所を応答に一覧で返す。 入力: id（必須）、codes（必須）、overview（必須）、notes、allow_code_deletion。