secret-safe-env

secret-safe-env

AI エージェントがプロジェクトの .env ファイルにシークレット（API キー、トークン、パスワード、接続文字列）を、値を一度も見ることなく書き込めるようにする Model Context Protocol サーバーです。

エージェントは変数名だけを指定してツールを呼び出します。ネイティブのマスク機能付き Windows ダイアログがローカルで開き、ユーザーが値を入力すると、ローカルの PowerShell ヘルパーがそのまま .env に書き込みます。エージェントが受け取るのはステータストークン（OK／CANCEL／ERR:<CODE>）だけで、シークレットを受け取ることはありません。

繁體中文說明見 README.zh-TW.md.

デモ

_{▶︎ 高画質ビデオ（音声付き）}

---

理由

エージェントに「OpenAI のキーを .env に追加して」と頼むと、通常の方法ではどれもシークレットが漏えいします。チャットに貼り付けると、モデルのコンテキストやトランスクリプトに残ります。エージェントに値を書き込ませると、エージェントが値を扱うことになります。「確認」のために cat .env を実行すれば、再び値が露出します。secret-safe-env は、こうしたすべての経路からシークレットを取り除きます。値はユーザー → マスク機能付きダイアログ → PowerShell → .env の順に渡され、エージェント／モデルのコンテキストには入りません。

agent: set_env_secret({ key: "OPENAI_API_KEY" })
          │  (name only — no value)
          ▼
   ┌──────────────────────────┐     you type the value here
   │  native masked dialog     │ ◄── (never shown to the agent)
   └──────────────────────────┘
          │  $script:SecretValue (never a parameter, never stdout)
          ▼
   PowerShell writes .env via [System.IO.File]
          │
          ▼
agent receives:  "OK"   ← status token only

「.env は自分で編集すればよいのでは？」

はい。その方法に取って代わるものではありません。このツールは、エージェントがチャット内で処理できるように、繰り返し行う チャットを離れる → ファイルを開く → 貼り付ける という手順をなくします。値を入力するのは一度だけです。また、.gitignore とは異なる漏えい経路にも対処します。.env を Git の対象外にしても、値を渡した瞬間にチャット／トランスクリプト／ログへ漏えいしていれば防げません。対象範囲は意図的に 値を安全に .env へ入れること のみに限定しており、本番環境のシークレット管理（ボールト、実行時の注入）は対象外です。

プラットフォームのサポート

このツールは設計上、Windows 専用です。信頼の基盤は、Windows PowerShell で動作するネイティブの WinForms マスク機能付きダイアログです。

要件	対応状況	備考
Windows 10 / 11	✅ 必須	対応 OS はこれのみです。
Linux / macOS	❌ 非対応	ツールは UNSUPPORTED_PLATFORM を返して処理を拒否し、マシンが非対応であることをエージェントに伝えます。（npm パッケージはどの OS にも インストール できますが、そこで実行することはできません。）
Windows PowerShell 5.1	✅ 必須	固定されたパス %SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe から起動します。
PowerShell 7+ (pwsh)	❌ 使用しません	PATH からの解決は意図的に行わないため、PATH 上の pwsh によって実行／ログ記録の経路が変わることはありません。
Node.js	✅ 18 以上	MCP サーバーを実行します（PowerShell を起動しますが、値には触れません）。

インストール

Claude Code

claude mcp add secret-safe-env -- npx -y secret-safe-env

最も安定したセットアップ（npx のキャッシュによる予期しない動作なし）にするには、グローバルの実行ファイルをインストールして、そのパスを指定します。

npm i -g secret-safe-env
claude mcp add secret-safe-env -- secret-safe-env

更新するには、npm i -g secret-safe-env@latest を実行します。バージョンを固定していない npx を使う場合は、キャッシュをクリア（npx clear-npx-cache）するか、バージョンを固定（npx -y secret-safe-env@<version>）して、古いキャッシュ済みコピーが実行されないようにしてください。

その他の MCP クライアント（.mcp.json）

{
  "mcpServers": {
    "secret-safe-env": { "command": "secret-safe-env" }        // requires `npm i -g secret-safe-env`
    // zero-install alternative (pin a version):
    // "secret-safe-env": { "command": "npx", "args": ["-y", "secret-safe-env@<version>"] }
  }
}

サーバーを認識させるため、クライアントを再読み込みしてください。npx で起動した stdio サーバーが一覧に表示されても Windows で接続されない場合は、コマンドを cmd /c npx -y secret-safe-env でラップしてください。

ツール

set_env_secret({ key, env_path? }) → ステータステキスト

key のマスクされたダイアログを開き、ユーザーが値を入力すると、ヘルパーが .env に key=value を書き込みます。エラーフラグと、人間／エージェントが読み取れるテキストを返します。値は決して返しません。key は UPPER_SNAKE_CASE（^[A-Z_][A-Z0-9_]*$）である必要があります。値は1 行に限られます（複数行の PEM／JSON の場合は、ユーザーに .env を手動で編集するよう依頼してください）。destructiveHint: true（キーをその場で挿入または更新します）。

env_key_exists({ key, env_path? }) → { exists: boolean }

.env に key が存在するかどうかだけを返します。値は決して返しません。書き込みの確認には、.env を読み取ったり cat したりする代わりに使用してください。readOnlyHint: true。

env_path はプロジェクトの .env への絶対パスです。必ず明示的に渡してください。runner が起動した MCP サーバーの作業ディレクトリは、ワークスペースではなく runner のサンドボックスです。省略した場合は <CLAUDE_PROJECT_DIR or cwd>/.env がデフォルトになります。

AI エージェント向け

タスクでプロジェクトの .env にシークレット／API キー／トークン／パスワード／認証情報が必要な場合は、必ず set_env_secret を使用してください（例：「自分の OpenAI キーを追加する」「DATABASE_URL を設定する」「.env を構成する」）。ルール：

• ✅ 変数名だけを渡してください。値はユーザーがローカルのダイアログに入力します。
• ✅ env_key_exists を使って書き込みを確認してください（値ではなく true／false を返します）。
• ❌ ユーザーにシークレットをチャットに貼り付けるよう依頼しないでください。
• ❌ 値やプレースホルダーを自分で書き込まないでください。
• ❌ 確認のために .env を cat したり読み取ったりしないでください。シークレットが再び露出します。

これらのルールは、サーバーの instructions と各ツールの description を通じてエージェントにも提供されるため、事前のコンテキストがまったくないエージェントでも正しく使用できます。

セキュリティの範囲

対象範囲内 — 値を入力してから .env に書き込まれるまで、監査対象の Windows／エージェントのどのチャネルにも記録されません。対象には、PSReadLine の履歴、4688／Sysmon のプロセスコマンドライン、4103 Module Logging、4104 Script Block Logging、PowerShell Transcription、AMSI、MCP／エージェントのコンテキスト、OTEL トレース、mcp-debug ログが含まれます。値が PowerShell のパラメーター境界を越えることはなく、書き込みには [System.IO.File] のみを使用し、コマンドレットは使用しません。静的 AST lint（npm run lint:ps）と Pester のトランスクリプトテストでこれを担保します。

対象範囲外（値が .env に入った後はユーザーの責任です）— クラウド同期／OneDrive、VSS／バックアップのスナップショット、ウイルス対策スキャン、ファイル ACL、エージェントによるその後の .env の読み取り。

脅威モデルと保証の全容については、docs/SPEC.md を参照してください。

開発

npm install
npm run build       # tsc -> dist/
npm test            # Node unit tests (vitest)
npm run test:ps     # PowerShell upsert + no-leak tests (Pester 5)
npm run lint:ps     # static value-path AST lint

PowerShell のテストには Pester 5 が必要です：Install-Module Pester -MinimumVersion 5.0 -Scope CurrentUser。

リリースは自動化されています。vX.Y.Z タグを push すると、GitHub Actions が npm（Trusted Publishing／OIDC）と MCP Registry に公開します。トークンは不要です。docs/DECISIONS.md を参照してください。

ドキュメント

• docs/SPEC.md — 目的、保証、脅威モデル、対象範囲と対象外事項。
• docs/ARCHITECTURE.md — モジュールとデータフロー。
• docs/DECISIONS.md — 設計上の決定とその根拠。

コントリビューション

コントリビューションを歓迎します。CONTRIBUTING.md を参照してください。ルールは 1 つだけです。情報漏えい防止の保証を維持し、テストすること。

ライセンス

MIT

免責事項

secret-safe-env は、いかなる種類の保証もなく「現状のまま」提供されます（LICENSE を参照）。文書化されたセキュリティ範囲内で、ベストエフォートでシークレットの露出を低減しますが、完全な秘匿性を保証するものではありません。ご自身の脅威モデルに適合するかどうかの確認と、値が .env に書き込まれた後に起こること（クラウド同期、バックアップ、ウイルス対策ソフト、ファイル権限、そしてエージェントを含む、後から .env を読み取るあらゆるツール）については、ご自身で責任を負うものとします。本番環境のシークレットには、専用のシークレットマネージャーを使用してください。

これは独立したオープンソースプロジェクトです。Anthropic、「Claude」、または Model Context Protocol プロジェクトとは、提携、承認、後援のいずれの関係もありません。これらの名称はそれぞれの所有者に帰属し、互換性を説明する目的でのみ使用しています。