内容
# @wundervault/mcp-server
[](https://www.npmjs.com/package/@wundervault/mcp-server)
[](https://registry.modelcontextprotocol.io/v0/servers?search=wundervault)
[](LICENSE)
用于 [Wundervault](https://wundervault.com) 的零知识秘密管理的MCP服务器。通过 [Model Context Protocol](https://modelcontextprotocol.io) 向AI代理公开保险库秘密 - 秘密在服务器端解密，从不以明文形式返回给代理。
## 安装
```bash
npm install -g @wundervault/mcp-server
```
## 快速入门
```json
{
"mcpServers": {
"wundervault": {
"command": "wundervault-mcp",
"env": {
"WUNDERVault_AGENT_VAULT_URL": "https://wundervault.com",
"WUNDERVault_AGENT_VAULT_API_KEY": "wv_agent_<AGENT_ID>|<KEY_SUFFIX>",
"WUNDERVault_AGENT_KEY": "<BASE64_ENCRYPTION_KEY>"
}
}
}
}
```
或使用凭证文件：
```bash
wundervault-mcp --credentials ~/.wundervault/creds.json
```
## 安全模型
- **零知识：** 加密密钥仅存在于MCP服务器进程中。Wundervault服务器永远不会看到它。
- **读取后销毁：** 明文秘密从不返回给调用代理。解密后，代理仅接收 `"Secret retrieved and burned."`。
- **执行擦除：** 如果使用 `exec` 参数，则在返回之前会擦除stdout/stderr中的明文。
- **指令完整性：** 在释放任何秘密之前，会验证服务器端指令签名（PBKDF2-HMAC-SHA256，60万次迭代）。
- **时间安全：** HMAC比较使用 `crypto.timingSafeEqual`。
## 工具
### `vault_entries_list`
列出此代理可用的所有保险库条目。返回条目ID和秘密名称 - 无值。
```
输入：{}
输出： "Vault entries (N):\n [entry_id] secret_name (tier: read)"
```
### `vault_entry_get`
检索和解密保险库秘密。可选地，使用它执行命令。
```
输入：
entry_id: string # 来自 vault_entries_list
purpose: string # 审计日志原因
exec?: string # 可选 shell 命令
输出： "Secret retrieved and burned." （绝不返回明文）
```
**安全执行模式** （sudo 示例）：
```bash
sudo -S systemctl restart nginx <<< "$WUNDERVault_SECRET"
```
不要使用 `echo $WUNDERVault_SECRET | sudo -S` - 这会在进程日志中公开秘密。
### `vault_entry_forget`
丢弃本地引用。服务器上为无操作。
```
输入： { entry_id: string }
输出： "Reference [id] discarded from local context."
```
## 凭证加载优先级
1. CLI 标志（ `--api-key`， `--enc-key`， `--url` ）
2. 环境变量（ `WUNDERVault_AGENT_VAULT_API_KEY`， `WUNDERVault_AGENT_KEY`， `WUNDERVault_AGENT_VAULT_URL` ）
3. `WUNDERVault_CREDENTIALS_FILE` 环境变量（显式路径）
4. `~/.wundervault/creds.json`
5. `~/.config/wundervault/credentials` （XDG）
### 凭证文件格式
```json
{
"agent_vault_url": "https://wundervault.com",
"agent_vault_api_key": "wv_agent_<ID>|<SUFFIX>",
"agent_encryption_key": "<BASE64_URL_SAFE_32_BYTES>"
}
```
## CLI 选项
```
wundervault-mcp [选项]
--api-key <key> 代理 API 密钥
--enc-key <key> 加密密钥（base64 URL-safe）
--url <url> API 基本 URL（默认：https://wundervault.com）
--credentials <f> 凭证 JSON 文件路径
--help 显示帮助
```
## 沙盒/演示模式
设置 `WUNDERVAULT_MOCK=1` 以在没有 `wundervault-agent` 守护进程或任何凭证的情况下运行服务器。在此模式下，每个工具调用都会返回一个带有 `[DEMO MODE]` 标签的代表性响应，而不是与保险库联系 - **绝不会涉及真实秘密**。此功能允许MCP目录扫描器和CI（例如 [Glama](https://glama.ai) ）启动服务器，执行每个工具，并验证构建，而无需实时保险库。**默认情况下关闭**，在生产环境中从不启用。
```jsonc
"env": { "WUNDERVAULT_MOCK": "1" } // 仅限演示/CI - 返回伪造的、带标签的输出
```
## 从源代码构建
```bash
git clone https://github.com/wundervault/wundervault-mcp.git
cd wundervault-mcp
npm install
npm run build # 编译 TypeScript 到 dist/
npm test # 运行测试套件
```
## 许可证
在 **GNU Affero General Public License v3.0 或更高版本** （ `AGPL-3.0-or-later` ）下许可。参见 [LICENSE](LICENSE)。
Wundervault 是 **开放核心**：此MCP服务器和客户端是开源的； [wundervault.com](https://wundervault.com) 上的托管服务是一种商业产品。如需商业或托管查询，请通过 [wundervault.com/contact](https://wundervault.com/contact) 联系我们。
