updsts 0.8.9__tar.gz

updsts-0.8.9/.claude/CLAUDE.md

@@ -0,0 +1 @@
+@../AGENTS.md

updsts-0.8.9/.claude/settings.local.json

@@ -0,0 +1,5 @@
+{
+  "disabledMcpjsonServers": [
+    "zv-updsts"
+  ]
+}

updsts-0.8.9/.claude-plugin/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "updsts-mcp",
+  "description": "Get and update AWS STS credential using existing AWS profile.",
+  "version": "0.8.9",
+  "author": {
+    "name": "kanok-one",
+    "email": "zervoid77@gmail.com"
+  },
+  "license": "MIT"
+}

updsts-0.8.9/.gitignore

@@ -0,0 +1,18 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+.pytest_cache/
+temp/
+tmp/
+
+# Virtual environments
+.venv
+.coverage
+
+# uv.lock
+uv.lock
+

updsts-0.8.9/.mcp.json

@@ -0,0 +1,13 @@
+{
+  "mcpServers": {
+    "zv-updsts": {
+      "command": "uv",
+      "args": [
+        "run",
+        "${CLAUDE_PLUGIN_ROOT:-.}/src/updsts_main.py",
+        "mcp",
+        "--mcp-server"
+      ]
+    }
+  }
+}

updsts-0.8.9/.python-version

@@ -0,0 +1 @@
+3.12

updsts-0.8.9/.vscode/launch.json

@@ -0,0 +1,56 @@
+{
+    "version": "0.2.0",
+    "configurations": [
+        // プラグインデバッグ用
+        {
+            "name": "Python Plugin Debug (Attach)",
+            "type": "debugpy",
+            "request": "attach",
+            "connect": {
+                "host": "localhost", // replace this with remote machine name
+                "port": 5678
+            },
+            "justMyCode": false
+        },
+        {
+            "name": "Python debug current file",
+            "type": "debugpy",
+            "request": "launch",
+            "program": "${file}",
+            "console" : "integratedTerminal",
+            // "stopOnEntry": true,
+            "env": {
+
+            }
+        },
+        {
+            "name": "Python: 'updsts'",
+            "type": "debugpy",
+            "request": "launch",
+            "module": "updsts",
+            "args": [
+
+            ],
+            "console": "integratedTerminal",
+            // "stopOnEntry": true,
+            "env": {
+
+            }
+        },
+        {
+            "name": "Python: 'updsts help'",
+            "type": "debugpy",
+            "request": "launch",
+            "module": "updsts",
+            "args": [
+                "-h",
+            ],
+            "console": "integratedTerminal",
+            // "stopOnEntry": true,
+            "env": {
+
+            }
+        }
+    ],
+    "compounds": []
+}

updsts-0.8.9/.vscode/mcp.json

@@ -0,0 +1,19 @@
+{
+    "servers": {
+        "updsts-ws": {
+            "type": "stdio",
+            "command": "uv",
+            "args": [
+                "run",
+                "--directory",
+                "${workspaceFolder}",
+                "-m",
+                "updsts",
+                "mcp",
+                "--mcp-server"
+            ],
+            "env": {}
+        }
+    },
+    "inputs": []
+}

updsts-0.8.9/.vscode/settings.json

@@ -0,0 +1,17 @@
+{
+    // 単体テストツールとしてpytestを有効化
+    "python.testing.pytestEnabled": true,
+    // ファイル保存時にテスト対象コードを自動的に探索
+    "python.testing.autoTestDiscoverOnSaveEnabled": true,
+    "python.testing.pytestArgs": [
+        "test"
+    ],
+    "python.testing.unittestEnabled": false,
+    "python-envs.pythonProjects": [
+        {
+            "path": ".",
+            "envManager": "ms-python.python:venv",
+            "packageManager": "ms-python.python:pip"
+        }
+    ],
+}

updsts-0.8.9/.vscode/task.json

@@ -0,0 +1,6 @@
+{
+    "version": "2.0.0",
+    "tasks": [
+
+    ]
+}

updsts-0.8.9/AGENTS.md

@@ -0,0 +1,89 @@
+# 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 呼び出しはモック）
+
+## ディレクトリ構成
+
+```text
+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
+
+```bash
+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` がその対応付けに使われる。
+
+## credentials ファイル
+
+- 既定の場所は `~/.aws/credentials`
+- 元になるプロファイルには `aws_access_key_id` / `aws_secret_access_key` / `mfa_device_arn` が必要。`totp_secret_name` は任意
+- 取得した STS 認証情報は、次のタグで囲まれたブロックを丸ごと書き換える。`key` は元のプロファイル名。ブロックがなければ末尾に追加する
+
+  ```ini
+  # ${{{ key=<profile> [auto update by updsts]
+  [<profile>_sts]
+  aws_access_key_id=...
+  aws_secret_access_key=...
+  aws_session_token=...
+  expiration_datetime=...
+  # $}}} [auto update by updsts]
+  ```
+
+- 書き換えは `.tmp` に書いてから置き換える。元ファイルの権限を引き継ぐ
+- `expiration_datetime` はローカルタイムゾーンの ISO 8601 形式
+- プロキシは環境変数 `http_proxy` / `https_proxy` から読む
+- ログファイルは `~/.awscm/log/awscm.log`
+
+## 開発
+
+```bash
+uv sync                 # 依存のインストール
+uv run pytest           # テスト実行
+uv run updsts --help    # ローカル実行
+```
+
+## 変更時の注意
+
+- MCP ツールの戻り値やログに秘密情報を生の値で含めない。`get_profile_info` / `get_profile_list` を MCP から呼ぶときは `secret_mask=True` を渡す
+- ログは stderr に出す。stdout は MCP の stdio 通信に使われる
+- 依存を変えるときは `pyproject.toml` と `src/updsts_main.py` のインライン依存の両方を更新する
+- バージョンは `pyproject.toml` と `.claude-plugin/plugin.json` の両方にある

updsts-0.8.9/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 kanok-one
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

updsts-0.8.9/PKG-INFO

@@ -0,0 +1,268 @@
+Metadata-Version: 2.5
+Name: updsts
+Version: 0.8.9
+Summary: Get and update AWS STS credential using existing AWS profile.
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: boto3>=1.40.39
+Requires-Dist: fastmcp>=2.12.4
+Requires-Dist: pydantic>=2.11.10
+Description-Content-Type: text/markdown
+
+# updsts
+
+A simple CUI tool and local MCP server for reflecting AWS STS credentials into the credentials file
+
+English | [日本語](README_ja.md)
+
+<!-- TOC tocDepth:2..3 chapterDepth:2..6 -->
+
+- [updsts](#updsts)
+  - [1. Overview](#1-overview)
+  - [2. Features](#2-features)
+  - [3. Runtime Environment](#3-runtime-environment)
+  - [4. Installation/Usage](#4-installationusage)
+    - [4-1. Install as a uv tool](#4-1-install-as-a-uv-tool)
+      - [4-1-1. Installation](#4-1-1-installation)
+      - [4-1-2. Registering as an MCP server](#4-1-2-registering-as-an-mcp-server)
+    - [4-2. Registering as an MCP server via the Claude plugin](#4-2-registering-as-an-mcp-server-via-the-claude-plugin)
+  - [5. CUI Tool Command Options](#5-cui-tool-command-options)
+    - [5-1. Common Options](#5-1-common-options)
+    - [5-2. `get` Command](#5-2-get-command)
+    - [5-3. `list` Command](#5-3-list-command)
+    - [5-4. `mcp` Command](#5-4-mcp-command)
+  - [6. Credentials File](#6-credentials-file)
+    - [6-1. Credentials File Format](#6-1-credentials-file-format)
+    - [6-2. Credentials File Location](#6-2-credentials-file-location)
+  - [7. Available MCP Tools](#7-available-mcp-tools)
+    - [`updsts_update_sts_credential`](#updsts_update_sts_credential)
+    - [`updsts_get_credential_info`](#updsts_get_credential_info)
+    - [`updsts_get_credential_info_list`](#updsts_get_credential_info_list)
+  - [8. Security Notes](#8-security-notes)
+  - [9. License](#9-license)
+
+<!-- /TOC -->
+
+## 1. Overview
+
+updsts is a command-line tool that retrieves AWS STS (Security Token Service) credentials using the credentials already registered in an existing credentials file (~/.aws/credentials). The retrieved credentials are automatically reflected in the same file.  
+It also works as a local MCP server that automatically updates the temporary credentials in the credentials file, so it can be operated from common Agent tools.
+
+## 2. Features
+
+- Obtain temporary AWS STS credentials using MFA authentication
+- Automatically update the STS profile in the credentials file with the new credentials
+- Support for TOTP-based MFA devices
+- List all AWS profiles in the credentials file
+- Leave profiles other than the one being updated untouched
+- Can be operated from common Agent tools when running as a local MCP server  
+  (Of course, care is taken to ensure that confidential information such as secret keys and session tokens is not sent to the LLM.)
+- Support for proxy environments
+
+## 3. Runtime Environment
+
+This project uses uv as the package manager.  
+Using uv allows you to reproduce the runtime environment automatically.  
+
+For how to install uv, see:
+
+- [Installing uv](https://docs.astral.sh/uv/getting-started/installation/)
+
+## 4. Installation/Usage
+
+### 4-1. Install as a uv tool
+
+Install updsts into a uv environment and use it.  
+Use this method when you use updsts as a CUI tool.  
+
+#### 4-1-1. Installation
+
+```bash
+# Install directly from git repository
+uv tool install git+{repository_url}
+```
+
+After installation, you can run the `updsts` command directly.  
+
+```bash
+updsts --help
+```
+
+#### 4-1-2. Registering as an MCP server
+
+By registering updsts as an MCP server, you can operate it from common Agent tools.
+
+```jsonc
+{
+  // Example configuration for registering as an MCP server
+  //
+  // (Note)
+  // Registration keys may differ depending on the Agent tool used,
+  // so please refer to the manual of the Agent tool you use for detailed procedures.
+  "mcpServers": {
+    // Configuration for starting updsts as an MCP server using uv
+    "updsts-uv": {
+      "type": "stdio",
+      "command": "updsts",
+      "args": [
+          "mcp",
+          "--mcp-server"
+      ],
+      "env": {}
+    }
+  }
+}
+```
+
+### 4-2. Registering as an MCP server via the Claude plugin
+
+updsts can be installed as a Claude plugin.  
+
+```bash
+# Add the marketplace
+/plugin marketplace add zv-louis/zv-plugin-marketplace
+# Install from the marketplace
+/plugin install updsts-mcp@zv-plugins
+```
+
+## 5. CUI Tool Command Options
+
+### 5-1. Common Options
+
+- `-v, --verbose LEVEL`: Set the output verbosity (0: normal, 1: verbose, 2: debug)
+- `-c, --credential_file FILE`: Path to the credentials file (default: ~/.aws/credentials)
+
+### 5-2. `get` Command
+
+Get and update the STS credentials for the specified AWS profile.
+
+```bash
+updsts get -n <profile_name> -t <totp_token>
+```
+
+- `-n, --profile_name`: AWS profile name to get the STS token for (required)
+- `-t, --totp_token`: TOTP token generated by the MFA device (required)
+- `-sn, --sts_profile_name`: STS profile name to create in the credentials file (optional, default: AWS profile name + "_sts")
+- `-d, --duration`: Token duration in seconds (optional, default: 3600)
+- `-c, --credential_file`: Path to the credentials file (optional, default: ~/.aws/credentials)
+
+### 5-3. `list` Command
+
+Display all AWS profiles in the credentials file.  
+Secrets (`aws_access_key_id`, `aws_secret_access_key`, `aws_session_token`) are displayed masked.
+
+```bash
+updsts list
+```
+
+### 5-4. `mcp` Command
+
+Start updsts as a local MCP server.  
+You can operate updsts from Agent tools.
+
+```bash
+updsts mcp --mcp-server
+```
+
+If the `--mcp-server` option is not specified, the MCP tool list is output.
+
+```bash
+updsts mcp
+```
+
+## 6. Credentials File
+
+### 6-1. Credentials File Format
+
+updsts works with the standard AWS CLI credentials file format.  
+It preserves existing profiles while updating only the specified section.  
+
+Example credentials file:  
+
+```ini
+[default]
+# Access Key ID (required)
+aws_access_key_id = AKIAIOSFODNN7EXAMPLE
+# Secret Access Key (required)
+aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLE
+# IAM user's MFA device ARN (required. The user must add this)
+mfa_device_arn = arn:aws:iam::123456789012:mfa/user 
+# TOTP secret name managed by the mktotp MCP server (optional. The user can add this)
+# If this is set and the `mktotp` MCP server is available, the Agent will automatically generate and use the TOTP token.
+totp_secret_name = my_totp_secret 
+
+# The section enclosed by the following tags is automatically created/updated by updsts.
+# ${{{ key=<name of the profile that requested STS> [auto update by updsts]
+[default_sts]
+aws_access_key_id = ASIAIOSFODNN7EXAMPLE
+aws_secret_access_key = wJalrXUtnFEMI/K7MDENG/bPxRfiCYtempKEY
+aws_session_token = IQoJb3JpZ2luX2VjE...
+expiration_datetime = 2025-10-05T15:30:00+09:00
+# $}}} [auto update by updsts]
+```
+
+updsts automatically manages the section between the special tags and leaves other profiles intact.  
+The tags are added automatically on the first run, so there is no need to add them manually.
+
+### 6-2. Credentials File Location
+
+By default, the credentials file is stored in the following location.  
+※ This is the same file used by the AWS CLI.  
+
+```text
+~/.aws/credentials
+```
+
+You can specify a different location with the `-c` option.  
+
+## 7. Available MCP Tools
+
+When started as an MCP server, the following tools are available from Agent tools.
+
+### `updsts_update_sts_credential`
+
+Get the STS credentials for the specified AWS profile and create/update the STS profile in the credentials file.
+
+- Parameters:
+  - `profile_name` (str): AWS profile name to update (required)
+  - `totp_token` (str): TOTP token from the MFA device (required)
+  - `sts_profile_name` (str | None): STS profile name to create in the credentials file (optional)
+    - If None or an empty string, `<profile_name>_sts` is used (default: None)
+  - `cred_file` (str | None): Path to the credentials file (optional)
+    - If None or an empty string, the default location (~/.aws/credentials) is used (default: None)
+  - `duration` (int): STS token duration in seconds (optional, default: 3600)
+- Returns (dict[str, str] | None): A dictionary containing the update result, or None on failure
+  - `updated_profile_name`: Name of the STS profile that was updated
+  - `aws_access_key_id`: Access key ID of the retrieved STS credentials (masked)
+  - `aws_token_expiration`: Expiration of the STS credentials (ISO 8601 format in the local time zone)
+  - The secret access key and the session token are not returned
+
+### `updsts_get_credential_info`
+
+Get the information of the specified AWS profile in the credentials file.  
+For security reasons, `aws_access_key_id`, `aws_secret_access_key` and `aws_session_token` are returned masked.  
+
+- Parameters:
+  - `profile_name` (str): AWS profile name to retrieve (required)
+  - `cred_file` (str | None): Path to the credentials file (optional)
+    - If None or an empty string, the default location (~/.aws/credentials) is used (default: None)
+- Returns (dict[str, str] | None): A dictionary containing the credential details, or None if not found
+
+### `updsts_get_credential_info_list`
+
+Get the information of all AWS profiles in the credentials file.  
+For security reasons, `aws_access_key_id`, `aws_secret_access_key` and `aws_session_token` are returned masked.  
+
+- Parameters:
+  - `cred_file` (str | None): Path to the credentials file (optional)
+    - If None or an empty string, the default location (~/.aws/credentials) is used (default: None)
+- Returns (list[dict[str, str]]): A list of dictionaries containing the credential details, or an empty list if no profiles are found
+
+## 8. Security Notes
+
+- The credentials file contains sensitive information, so protect it with appropriate permissions (recommended: 600)
+
+## 9. License
+
+This project is licensed under the MIT License.  
+See the [LICENSE](LICENSE) file for details.