mktotp 0.9.13__tar.gz

mktotp-0.9.13/.claude/CLAUDE.md

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

mktotp-0.9.13/.claude/settings.local.json

@@ -0,0 +1,5 @@
+{
+  "enabledMcpjsonServers": [
+    "zv-mktotp"
+  ]
+}

mktotp-0.9.13/.claude-plugin/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "mktotp-mcp",
+  "description": "Interactive TOTP (Time-based One-Time Password) manager. Helps create, list, and manage TOTP secrets and generate one-time passwords.",
+  "version": "0.9.13",
+  "author": {
+    "name": "kanok-one",
+    "email": "zervoid77@gmail.com"
+  },
+  "license": "MIT"
+}

mktotp-0.9.13/.gitignore

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

mktotp-0.9.13/.mcp.json

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

mktotp-0.9.13/.python-version

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

mktotp-0.9.13/.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: 'mktotp'",
+            "type": "debugpy",
+            "request": "launch",
+            "module": "mktotp",
+            "args": [
+                "list",
+            ],
+            "console": "integratedTerminal",
+            // "stopOnEntry": true,
+            "env": {
+
+            }
+        },
+        {
+            "name": "Python: 'mktotp help'",
+            "type": "debugpy",
+            "request": "launch",
+            "module": "mktotp",
+            "args": [
+                "-h",
+            ],
+            "console": "integratedTerminal",
+            // "stopOnEntry": true,
+            "env": {
+
+            }
+        }
+    ],
+    "compounds": []
+}

mktotp-0.9.13/.vscode/mcp.json

@@ -0,0 +1,16 @@
+{
+    "servers": {
+        "mktotp-ws": {
+            "type": "stdio",
+            "command": "uv",
+            "args": [
+                "run",
+                "${workspaceFolder}/src/mktotp_main.py",
+                "mcp",
+                "--mcp-server"
+            ],
+            "env": {},
+        }
+    },
+    "inputs": []
+}

mktotp-0.9.13/.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"
+        }
+    ],
+}

mktotp-0.9.13/.vscode/task.json

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

mktotp-0.9.13/AGENTS.md

@@ -0,0 +1,81 @@
+# mktotp project
+
+TOTP（二要素認証のワンタイムパスワード）のシークレットを管理する CUI ツール兼ローカル MCP サーバー。
+QR コード画像からシークレットを登録し、登録済みシークレットからトークンを生成する。
+MCP 経由で操作される前提のため、シークレット文字列そのものを LLM 側へ返さないことを設計上の原則としている。
+
+## 技術スタック
+
+- Python 3.12 以上、パッケージ管理は uv、ビルドは hatchling
+- 主な依存: `pyotp`（TOTP 生成）、`fastmcp`（MCP サーバー）、`opencv-python` / `pillow` / `cairosvg`（QR コード読み取り、SVG 対応）、`filelock`（排他制御）、`pydantic`
+- テスト: pytest + pytest-asyncio（`asyncio_mode = auto`）
+
+## ディレクトリ構成
+
+```text
+src/mktotp/
+  __main__.py     CLI エントリポイント（main）とサブコマンドのハンドラ
+  cmdparam.py     argparse のサブコマンド定義（add / get / list / remove / rename / mcp）
+  func_impl.py    CLI と MCP で共有する業務ロジック（SecretMgr を with で開いて操作）
+  secrets.py      SecretMgr: シークレット JSON の読み書き、ロック、TOTP 生成
+  qrcode_util.py  QR コード画像のデコード（otpauth:// URI を取り出す）
+  permutil.py     シークレットファイルの権限設定（Unix は 600、Windows は icacls）
+  logutil.py      ロガー（出力は stderr。MCP の stdio を汚さないため）
+  mcp_server.py   FastMCP のツール定義（薄いラッパー）
+  mcp_impl.py     MCP ツールの実装、入力検証、例外を ValueError に揃える共通処理
+src/mktotp_main.py  Claude プラグイン用の MCP 起動スクリプト（PEP 723 のインライン依存を持つ）
+test/             モジュールごとの pytest
+.claude-plugin/   Claude Code プラグインのマニフェスト
+.mcp.json         プラグイン用 MCP サーバー設定（uv run src/mktotp_main.py mcp --mcp-server）
+```
+
+処理の流れは、CLI なら `__main__.py` → `func_impl.py` → `secrets.py`、MCP なら `mcp_server.py` → `mcp_impl.py` → `func_impl.py` → `secrets.py` となる。
+
+## CLI
+
+```bash
+mktotp add -nn <name> -f <qr_image>     # QR コード画像から登録
+mktotp add -nn <name> -ss <secret>      # シークレット文字列を直接登録（CLI のみ）
+mktotp get -n <name>                    # トークン生成
+mktotp list                             # 一覧
+mktotp remove -n <name>                 # 削除
+mktotp rename -n <old> -nn <new>        # 名前変更
+mktotp mcp --mcp-server                 # MCP サーバーとして起動（オプションなしならツール一覧を表示）
+```
+
+共通オプションは `-v, --verbose`（0: 通常、1: 詳細、2: デバッグ）と `-s, --secrets-file`。
+
+## MCP ツール
+
+| ツール | 内容 |
+| --- | --- |
+| `mktotp_register_secret` | QR コード画像から登録 |
+| `mktotp_generate_token` | トークン生成 |
+| `mktotp_get_secret_info_list` | 一覧（name / account / issuer のみ。シークレット値は含めない） |
+| `mktotp_remove_secrets` | 複数名を指定して削除 |
+| `mktotp_rename_secret` | 名前変更 |
+
+各ツールは `secrets_file` を必須引数に取り、空文字列なら既定のファイルを使う。
+シークレット文字列の直接登録は MCP には公開していない。
+
+## データ保存
+
+- 既定の保存先は `~/.mktotp/data/secrets.json`（ディレクトリは 0700、ファイルは 600）
+- 形式は `{"secrets": [{"name", "account", "issuer", "secret", ...}], "version": "1.0", "last_update": ...}`
+- 同じ場所の `secrets.lock` を使い、`filelock` で排他制御する
+- 読み込み時に権限が緩ければ自動で修正する
+
+## 開発
+
+```bash
+uv sync                 # 依存のインストール
+uv run pytest           # テスト実行
+uv run mktotp --help    # ローカル実行
+```
+
+## 変更時の注意
+
+- MCP ツールの戻り値やログにシークレット値を含めない。`list_secrets(include_secret=False)` の挙動を崩さない
+- ログや print は stderr に出す。stdout は MCP の stdio 通信に使われる
+- 依存を変えるときは `pyproject.toml` と `src/mktotp_main.py` のインライン依存の両方を更新する
+- バージョンは `pyproject.toml` と `.claude-plugin/plugin.json` の両方にある

mktotp-0.9.13/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.

mktotp-0.9.13/PKG-INFO

@@ -0,0 +1,254 @@
+Metadata-Version: 2.5
+Name: mktotp
+Version: 0.9.13
+Summary: A Simple TOTP Secret Manager with MCP Server Support
+Author-email: kanok-one <zervoid77@gmail.com>
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: cairosvg>=2.8.2
+Requires-Dist: fastmcp>=2.11.3
+Requires-Dist: filelock>=3.18.0
+Requires-Dist: opencv-python>=4.12.0.88
+Requires-Dist: pillow>=10.0.0
+Requires-Dist: pydantic>=2.11.7
+Requires-Dist: pyotp>=2.9.0
+Description-Content-Type: text/markdown
+
+# mktotp
+
+A simple CUI-based TOTP secret management tool and local MCP server for multi-factor authentication (MFA)
+
+English | [日本語](README_ja.md)
+
+<!-- TOC tocDepth:2..3 chapterDepth:2..6 -->
+
+- [mktotp](#mktotp)
+  - [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. `add` Command](#5-2-add-command)
+      - [5-2-1. Adding from a QR code image file](#5-2-1-adding-from-a-qr-code-image-file)
+      - [5-2-2. Registering a TOTP secret directly (CUI tool only)](#5-2-2-registering-a-totp-secret-directly-cui-tool-only)
+    - [5-3. `get` Command](#5-3-get-command)
+    - [5-4. `list` Command](#5-4-list-command)
+    - [5-5. `remove` Command](#5-5-remove-command)
+    - [5-6. `rename` Command](#5-6-rename-command)
+    - [5-7. `mcp` Command](#5-7-mcp-command)
+  - [6. File Storage Location](#6-file-storage-location)
+  - [7. Security Notes](#7-security-notes)
+  - [8. License](#8-license)
+
+<!-- /TOC -->
+
+## 1. Overview
+
+mktotp is a command-line tool for managing TOTP (Time-based One-Time Password) secrets and generating authentication tokens for multi-factor authentication services.  
+It also works as a local MCP server, so you can operate it from MCP-compatible Agent tools.
+
+## 2. Features
+
+- Register TOTP secrets from QR code image files in PNG, JPEG, BMP, TIFF, or SVG format
+- Generate TOTP tokens for registered secrets
+- List all registered secrets
+- Remove and rename secrets
+- Can be operated from MCP-compatible Agent tools when running as a local MCP server  
+  While running as an MCP server, mktotp is designed so that secret strings are not sent to the LLM.
+
+## 3. Runtime Environment
+
+This project uses uv as the package manager.  
+
+For how to install uv, see the following page.
+
+- [Installing uv](https://docs.astral.sh/uv/getting-started/installation/)
+
+## 4. Installation/Usage
+
+### 4-1. Install as a uv tool
+
+Install mktotp into a uv environment and use it.  
+Use this method when you use mktotp as a CLI tool.  
+
+#### 4-1-1. Installation
+
+```bash
+# Install directly from git repository
+uv tool install git+{mktotp_repository_URL}
+```
+
+After installation, you can run the `mktotp` command directly.  
+
+```bash
+mktotp --help
+```
+
+#### 4-1-2. Registering as an MCP server
+
+By registering mktotp as an MCP server, you can also operate `mktotp` from Agent tools.  
+For how to register an MCP server, refer to the manual of the Agent tool you use.  
+
+```jsonc
+{
+  // Example configuration for registering as an MCP server
+  //
+  // (Note)
+  // Registration keys differ depending on the Agent tool.
+  // Refer to the manual of the Agent tool you use for detailed procedures.
+  "mcpServers": {
+    // Configuration for starting mktotp as an MCP server using uv
+    "mktotp-uv": {
+      "type": "stdio",
+      "command": "mktotp",
+      "args": [
+        "mcp",
+        "--mcp-server"
+      ],
+      "env": {}
+    }
+  }
+}
+```
+
+### 4-2. Registering as an MCP server via the Claude plugin
+
+mktotp 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 mktotp-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)
+- `-s, --secrets-file FILE`: Path to the JSON file where secrets are stored
+
+### 5-2. `add` Command
+
+Add a new secret.  
+Specify either `-f` (QR code image) or `-ss` (secret string).  
+If neither is given, the command fails with an error.  
+If both are given, `-f` takes precedence and `-ss` is ignored.  
+
+- `-nn, --new-name`: Name for the secret (required)
+
+If a secret with the same name is already registered, it is overwritten.  
+
+#### 5-2-1. Adding from a QR code image file
+
+Add a new secret from a QR code image.  
+
+```bash
+mktotp add -nn <new_name> -f <QR_code_image_file>
+```
+
+- `-f, --qrcode-file`: Path to the image file containing the QR code  
+  PNG, JPEG, BMP, TIFF, and SVG are supported (for TIFF, only the `.tiff` extension is accepted)
+
+The account and issuer are taken from the QR code.  
+If the image contains multiple QR codes, all of them are registered.  
+The second and later secrets get a `_2`, `_3` ... suffix (e.g. `<new_name>_2`).  
+
+#### 5-2-2. Registering a TOTP secret directly (CUI tool only)
+
+Add a new secret by specifying the secret string directly.  
+
+```bash
+mktotp add -nn <new_name> -ss <secret_string> [-i <issuer>] [-a <account>]
+```
+
+- `-ss, --secret-string`: Secret string in Base32 format
+- `-i, --issuer`: Issuer. Defaults to the secret name
+- `-a, --account`: Account. Defaults to the secret name
+
+Whitespace in the secret string (such as groups of 4 characters) and trailing `=` padding are removed before saving.  
+An invalid Base32 string results in an error.  
+The error message shows only the positions of the invalid characters, counted from the start of the input (whitespace included). It never shows the secret itself.  
+
+> The string given with `-ss` may remain in your shell history and the process list.
+
+### 5-3. `get` Command
+
+Generate a TOTP token for the specified secret name.
+
+```bash
+mktotp get -n <secret_name>
+```
+
+- `-n, --name`: Name of the secret to operate on (required)
+
+### 5-4. `list` Command
+
+Display all registered secrets.
+
+```bash
+mktotp list
+```
+
+### 5-5. `remove` Command
+
+Remove the specified secret.
+
+```bash
+mktotp remove -n <secret_name>
+```
+
+- `-n, --name`: Name of the secret to remove (required)
+
+### 5-6. `rename` Command
+
+Rename a registered secret.
+
+```bash
+mktotp rename -n <current_name> -nn <new_name>
+```
+
+- `-n, --name`: Current secret name (required)
+- `-nn, --new-name`: New secret name (required)
+
+### 5-7. `mcp` Command
+
+Start mktotp as a local MCP server.  
+You can operate mktotp from Agent tools.
+
+```bash
+mktotp mcp --mcp-server
+```
+
+If the `--mcp-server` option is not specified, it outputs the MCP tool list.
+
+```bash
+mktotp mcp
+```
+
+## 6. File Storage Location
+
+By default, secrets are stored in the following location.
+
+```text
+~/.mktotp/data/secrets.json
+```
+
+You can specify a different location with the `-s` option.
+
+## 7. Security Notes
+
+- Secret files contain sensitive information, so protect them with permissions that prevent anyone but the owner from reading or writing them. When saving, mktotp automatically sets permissions that allow only the owner to read and write (600 on Unix-like systems).  
+- When creating backups, we recommend using encrypted storage.  
+- Remove unnecessary secrets with the `remove` command.
+
+## 8. License
+
+This project is licensed under the MIT License.  
+See the [LICENSE](LICENSE) file for details.