updsts: Instructions file for Codex

updsts project

既存の AWS プロファイルと MFA の TOTP トークンから一時的な STS 認証情報を取得し、AWS の credentials ファイルを更新する CUI ツール兼ローカル MCP サーバー。 MCP 経由で操作される前提のため、アクセスキーやシークレットキーなどの秘密情報をマスクせずに LLM 側へ返さないことを設計上の原則としている。

技術スタック

• Python 3.12 以上、パッケージ管理は uv、ビルドは hatchling
• 主な依存: boto3（STS の get_session_token）、fastmcp（MCP サーバー）、pydantic
• テスト: pytest（マーカー: slow / integration / unit / aws。AWS 呼び出しはモック）

ディレクトリ構成

src/updsts/
  __main__.py     CLI エントリポイント（main）。引数解析と例外のメッセージ化
  cmdparam.py     argparse のサブコマンド定義（get / list / mcp）
  cmd_handler.py  サブコマンドのハンドラ
  awsutil.py      業務ロジック: credentials ファイルの読み込み、STS トークン取得、マスク処理
  upcred.py       CredentialUpdater: credentials ファイルの該当ブロックを書き換える
  logutil.py      ロガー（コンソール出力は stderr。MCP の stdio を汚さないため）
  mcp_server.py   FastMCP のツール定義（薄いラッパー）
  mcp_impl.py     MCP ツールの実装、例外を ValueError に揃える共通処理
src/updsts_main.py  Claude プラグイン用の MCP 起動スクリプト（PEP 723 のインライン依存を持つ）
test/             モジュールごとの pytest
.claude-plugin/   Claude Code プラグインのマニフェスト
.mcp.json         プラグイン用 MCP サーバー設定（uv run src/updsts_main.py mcp --mcp-server）

処理の流れは、CLI なら __main__.py → cmd_handler.py → awsutil.py → upcred.py、MCP なら mcp_server.py → mcp_impl.py → awsutil.py → upcred.py となる。

CLI

updsts get -n <profile> -t <totp_token>              # STS 認証情報を取得して credentials ファイルを更新
updsts get -n <profile> -t <totp> -sn <sts_profile>  # 書き込み先のプロファイル名を指定（既定は <profile>_sts）
updsts get -n <profile> -t <totp> -d 7200            # 有効期間（秒）を指定（既定は 3600）
updsts list                                          # プロファイル一覧（秘密情報はマスク表示）
updsts mcp --mcp-server                              # MCP サーバーとして起動（オプションなしならツール一覧を表示）

共通オプションは -v, --verbose（0: 通常、1: 詳細、2: デバッグ）と -c, --credential_file。

MCP ツール

ツール	内容
updsts_update_sts_credential	TOTP トークンで STS 認証情報を取得し、credentials ファイルを更新
updsts_get_credential_info	指定プロファイルの情報（秘密情報はマスク済み）
updsts_get_credential_info_list	全プロファイルの情報（秘密情報はマスク済み）

各ツールの cred_file と sts_profile_name は、空文字列なら既定値を使う。 TOTP トークンは mktotp などで生成する前提で、プロファイルの totp_secret_name がその対応付けに使われる。