secret-safe-env

secret-safe-env

一个 Model Context Protocol 服务，可让 AI Agent 将机密（API 密钥、令牌、密码、连接字符串）写入项目的 .env 文件，而 Agent 始终无法看到其值。

Agent 调用工具时只需提供变量名。随后会在本地打开原生的 Windows 掩码对话框；由你输入值；本地 PowerShell 辅助程序会直接将其写入 .env。Agent 只会收到状态令牌（OK / CANCEL / ERR:<CODE>），绝不会收到机密。

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

演示

_{▶︎ 高清视频（含音频）}

---

为什么需要

当你让 Agent“将我的 OpenAI 密钥添加到 .env”时，常见做法都会泄露机密：将其粘贴到聊天中，会让它进入模型上下文和聊天记录；让 Agent 写入该值，意味着 Agent 接触到了它；用 cat .env“验证”则会再次暴露它。secret-safe-env 会从所有这些渠道中移除机密——该值只会沿着**用户 → 掩码对话框 → PowerShell → .env**传递，绝不会进入 Agent／模型上下文。

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 吗？”

可以——而且这并不是要取代这种做法。它省去了重复的离开聊天 → 打开文件 → 粘贴步骤，让 Agent 在聊天中直接处理，你只需输入一次值。它还保护了与 .gitignore 不同的攻击面：即使让 .env 不进入 git，如果你交出该值时它已经泄露到聊天／聊天记录／日志中，也无济于事。本工具的范围刻意限定为安全地将值写入 .env——生产环境的机密管理（保险库、运行时注入）不在范围内。

平台支持

此工具专为 Windows 设计，仅支持 Windows——其信任根基是由 Windows PowerShell 驱动的原生 WinForms 掩码对话框。

要求	支持情况	备注
Windows 10 / 11	✅ 必需	唯一支持的操作系统。
Linux / macOS	❌ 不支持	工具会返回 UNSUPPORTED_PLATFORM 并拒绝执行；Agent 会获知此设备不受支持。（npm 包仍可在任何操作系统上安装，只是无法在这些系统上运行。）
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 缓存问题），请安装全局 bin 并指向它：

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 的遮蔽输入对话框；用户输入值；辅助程序将 key=value 写入 .env。返回人类/Agent 可读的文本及错误标志——绝不返回该值。key 必须为 UPPER_SNAKE_CASE（^[A-Z_][A-Z0-9_]*$）。值必须是单行（对于多行 PEM/JSON，请让用户手动编辑 .env）。destructiveHint: true（会原位更新键值）。

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

仅返回 key 是否存在于 .env 中——绝不返回该值。请用它确认写入，不要读取/cat .env。readOnlyHint: true。

env_path 是项目 .env 的绝对路径。始终显式传入——由运行器启动的 MCP 服务，其工作目录是运行器沙箱，而不是你的工作区。若省略，则默认为 <CLAUDE_PROJECT_DIR or cwd>/.env。

面向 AI Agent

只要任务需要将密钥/API 密钥/令牌/密码/凭据写入项目 .env，就使用 set_env_secret（例如“添加我的 OpenAI 密钥”“设置 DATABASE_URL”“配置我的 .env”）。规则：

• ✅ 只传入变量名；由用户在本地对话框中提供值。
• ✅ 使用 env_key_exists 确认写入（仅返回 true/false，绝不返回该值）。
• ❌ 绝不要让用户将密钥粘贴到聊天中。
• ❌ 绝不要自行写入值或占位符。
• ❌ 绝不要通过 cat/读取 .env 来验证——这会再次暴露密钥。

这些规则也会通过服务的 instructions 和每个工具的 description 提供给 Agent，因此没有任何先前上下文的全新 Agent 也能正确使用。

安全范围

范围内——从输入值到写入 .env 的整个过程，不会被任何经过审计的 Windows/Agent 通道记录：PSReadLine 历史记录、4688/Sysmon 进程命令行、4103 模块日志记录、4104 脚本块日志记录、PowerShell 转录、AMSI、MCP/Agent 上下文、OTEL 跟踪以及 mcp-debug 日志。该值不会跨越 PowerShell 参数边界，且仅通过 [System.IO.File] 写入，绝不使用 cmdlet。静态 AST lint（npm run lint:ps）和 Pester 转录测试会强制执行此要求。

范围外（值写入 .env 后由你负责）——云同步 / OneDrive、VSS / 备份快照、防病毒扫描、文件 ACL，以及 Agent 之后读取 .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 标签，GitHub Actions 即会发布到 npm（Trusted Publishing / OIDC）和 MCP Registry——无需令牌。参见 docs/DECISIONS.md。

文档

• docs/SPEC.md — 用途、保障措施、威胁模型、范围和非目标。
• docs/ARCHITECTURE.md — 模块和数据流。
• docs/DECISIONS.md — 设计决策及其理由。

贡献

欢迎贡献——请参见 CONTRIBUTING.md。唯一规则：保持防泄漏保障，并确保经过测试。

许可证

MIT

免责声明

secret-safe-env 按“原样”提供，不作任何形式的保证（请参阅 LICENSE）。它会尽力在文档所述的安全范围内减少机密信息暴露；但不保证绝对保密。你有责任确认它符合你的威胁模型，并对值写入 .env 之后发生的一切负责——云同步、备份、杀毒软件、文件权限，以及之后读取 .env 的任何工具（包括 Agent）。对于生产环境中的机密信息，建议使用专用的机密管理器。

这是一个独立的开源项目，与 Anthropic、“Claude”或 Model Context Protocol 项目均无关联、背书或赞助关系；这些名称归各自所有者所有，仅用于说明兼容性。