内容
# envpact-mcp
[](https://www.npmjs.com/package/envpact-mcp)
[](https://opensource.org/licenses/MIT)
[](https://github.com/chirag127/envpact-mcp/actions/workflows/ci.yml)
**envpact 的模型上下文协议服务器** — 为 AI 编程代理（如 Cursor、Windsurf、Claude Code、Cline、Goose、ChatGPT Desktop 及其他支持 MCP 的客户端）提供集中式机密管理。
> 停止将 API 密钥粘贴到提示中。让您的代理根据您的私有保险库按需生成 `.env` 文件。
envpact 生态系统的一部分。
## 功能
当您询问 AI 代理 _“建立一个使用 OpenAI 和 Stripe 的 Next.js 项目”_ 时，现代代理可以搭建代码，但会在 `.env` 步骤卡住。安装 envpact-mcp 后：
- 代理查看您的项目的 `.env.example` 要求。
- 它调用 `generate_env`，文件从您的私有保险库中写入。
- 它发现的新密钥通过 `add_secret`/`add_shared_secret` 添加回保险库。
- 可选地通过 `sync_github` 同步到 GitHub Actions，以便 CI 端到端工作。
您永远不会将机密粘贴到代理提示中。
## 安装
MCP 服务器以 `envpact-mcp` 的身份发布到 npm。配置您的 AI 客户端：
### Claude Desktop / Claude Code
`~/.config/claude/claude_desktop_config.json`：
```json
{
"mcpServers": {
"envpact": {
"command": "npx",
"args": ["-y", "envpact-mcp"]
}
}
}
```
### Cursor
项目中的 `.cursor/mcp.json` 或全局的 `~/.cursor/mcp.json`：
```json
{
"mcpServers": {
"envpact": {
"command": "npx",
"args": ["-y", "envpact-mcp"]
}
}
}
```
### Windsurf
`~/.codeium/windsurf/mcp_config.json`：
```json
{
"mcpServers": {
"envpact": {
"command": "npx",
"args": ["-y", "envpact-mcp"]
}
}
}
```
### Cline（VS Code）
在 Cline 的 MCP 设置面板中，添加一个_stdio_服务器，命令为 `npx`，参数为 `["-y", "envpact-mcp"]`。
## 先决条件
您需要一个 envpact 保险库。如果您还没有：
```bash
npx envpact-cli --init auto
# 创建 chirag127/envpact-secrets（私有）并克隆到
# ~/.envpact/secrets/ — 相同保险库每个组件读取。
```
## 可用工具
| 工具 | 描述 |
| :--- | :--- |
| `generate_env` | 解析机密，为当前项目写入 `.env`。 |
| `list_projects` | 列出保险库中的所有项目。 |
| `list_shared` | 列出共享机密名称（值被掩盖）。 |
| `add_secret` | 添加/更新项目机密。 |
| `add_shared_secret` | 添加/更新共享机密。 |
| `rotate_secret` | 轮换共享机密；报告受影响的项目。 |
| `sync_github` | 将已解析的机密推送到 GitHub Actions。 |
| `pull_secret` | 从保险库拉取一个密钥 → `.env`（每密钥，冲突安全）。 |
| `push_secret` | 从 `.env` 推一个密钥 → 保险库（每密钥，冲突安全）。 |
| `sync_status` | 报告 `.env.example` 上的每密钥同步状态。 |
| `generate_global_env` | 将每个共享机密镜像到 `~/.envpact/.env`（v3.1）。 |
架构详情：参见 [SHARED_SPEC §7](https://github.com/chirag127/envpact/blob/main/_build/specs/SHARED_SPEC.md)。
## v3.1 UX 新增功能
- **双重渲染时间戳（UTC + IST）。** `pull_secret` / `push_secret` 和 `sync_status` 中的每个冲突拒绝现在都带有规范的 UTC ISO 字符串和人类 IST 渲染（`YYYY-MM-DD HH:MM:SS IST`）。冲突有效载荷还公开 `recommended_side: "vault" | "local"`，设置为更新的任一侧。用户保留最终决定；`recommended_side` 只是一个提示。
- **全局保险库 `.env`。** `generate_global_env` 将每个 `shared.*` 条目镜像到 `~/.envpact/.env` 中的单个文件，该文件从 `~/.envpact/.env.example.global` 生成（首次运行时自动创建，字节忠实模板格式）。加密值发出 `# KEY: encrypted` 注释；缺失密钥发出 `# KEY: not in vault`。输出模式为 0600（在 Windows 上尽力而为）。
## 每密钥同步（v3）
保险库是 **扁平的，每个项目只有一个环境**，具有 `{value, _modified_at}` 条目。代理可以一次同步一个密钥，而无需触及 `.env` 的其余部分：
> **您：** “从保险库中拉取最新的 OPENAI_API_KEY。”
>
> **代理：** 调用 `pull_secret({key: 'OPENAI_API_KEY'})` → 将新值写入 `.env`，更新 `.env.example.lock`。如果您在上次同步后编辑了 `.env`，调用将返回具有 `status: 'local_newer'` 的 `isError` 有效载荷；代理在询问您后仅使用 `force: true` 重试。
> **您：** “这个项目的同步状态是什么？”
>
> **代理：** 调用 `sync_status()` → 将每个密钥报告为 `synced` / `local_newer` / `vault_newer` / `both_diverged` / `local_only` / `vault_only`。从不返回值。
## 示例代理对话
> **您：** “为此项目设置 envpact。`.env.example 需要 OPENAI_API_KEY 和 DATABASE_URL`。”
>
> **代理：** 调用 `generate_env` → `.env` 已写入，缺少 `DATABASE_URL`。询问：”`DATABASE_URL` 应该是共享机密还是项目特定机密？”`
>
> **您：** “共享，值为 `postgres://prod-host/db`。”
>
> **代理：** 调用 `add_shared_secret({key: 'DATABASE_URL', value: '...'})`，然后 `add_secret({project: 'this-app', key: 'DATABASE_URL', value: 'shared.DATABASE_URL'})`，然后再次 `generate_env`。完成 — `.env` 完成。
> **您：** “OPENAI_API_KEY 已泄露。 在所有地方轮换它。”
>
> **代理：** 调用 `rotate_secret({key: 'OPENAI_API_KEY', new_value: 'sk-new...'})` → 报告 12 个受影响的项目。 为每个项目调用 `sync_github`。
## 远程 / SSE 变体
一个 Cloudflare Worker 变体，支持通过 Streamable HTTP 的 MCP，部署在 `https://mcp.envpact.oriz.in/mcp`，并在 Smithery 上列出，网址为 `https://smithery.ai/server/@chirag127/envpact-mcp`。 Worker 暴露了相同的 11 种工具，但有两种自然的 Worker 偏差：`pull_secret` 将解析值作为响应正文返回（无 `.env` 可写入），而 `generate_global_env` 将渲染的全局 `.env` 正文作为文本返回，而不是写入磁盘。有关完整的偏差列表，请参见 `worker/README.md`。
## 安全模型
- 机密值在工具 *响应* 中永远不会离开您的机器 — 只有工具参数（例如，当您要求代理设置值时）携带明文。
- `list_shared` 仅返回名称；机密值从不回显。
- MCP 服务器直接读取/写入 `~/.envpact/secrets/`。保险库是您的现有私有 GitHub 仓库。
- 所有保险库提交都经过签名确认 (`-s`)，并由 `envpact-mcp` 授权。
## 许可证
MIT © Chirag Singhal — 参见 [LICENSE](./LICENSE)。
## 文档
- **[仓库文档 (`docs/README.md`)](./docs/README.md)** — envpact-mcp 的完整 API + 使用参考
- **[项目伞形网站](https://chirag127.github.io/envpact/)** — 概述所有 envpact 组件、安全模型、快速入门
- **[实时仪表盘](https://envpact.oriz.in)** — 视觉保险库管理
