Cerberus KeyRouter

使用说明（Markdown格式）

• 项目简介

  • Cerberus KeyRouter 是一个基于 MCP 的服务端实现，通过受控的本地组件（Vaultwarden、Chrome DevTools Protocol、Playwright）为 LLM 客户端提供“读取凭据、执行自动化浏览器操作、获取/渲染提示模版”等能力。密码信息始终在本地处理，LLM 只看到占位符或处理结果，提升安全性和可控性。

• 主要功能点

  • MCP 服务实现：接收、处理和响应 MCP 风格的请求，注册并执行工具，管理会话与传输。
  • 工具与资源：提供 secure_login、list_vault_items 等工具，允许客户端读取凭据项、执行登录序列等。
  • 浏览器自动化：通过 Playwright + CDP（Chrome DevTools Protocol）在本地浏览器中执行表单填写、点击、等待等动作，并通过 CDP 代理实现容器化/代理环境兼容性。
  • 凭据安全与审计：凭据从 Vaultwarden 获取，替换占位符后再进行注入；完整审计日志记录，敏感信息经过脱敏处理。
  • 安全与隔离：本地化通信、无缝地址校验、会话分离与访问控制（可选的 Bearer Token 验证）。
  • 支持多会话：每个 MCP 会话分配独立的服务器/传输上下文，确保并发安全。
  • 环境与部署：提供 Docker/Vaultwarden 集成方案，包含环境变量、健康检查、以及对外暴露的 MCP 端点。

• 安装步骤

  1. 准备依赖
     • Docker 与 Docker Compose
     • Chrome/Chromium 以及远程调试端口开启（用于浏览器自动化）
  2. 获取代码与依赖
     • 克隆仓库，按照 README 中的说明配置环境变量（例如 Vaultwarden 的管理令牌、API Key、主密码等）
  3. 启动服务
     • 使用 README 提到的命令启动 Vaultwarden 与 Login Router（示例：docker compose up --build -d），等待健康检查通过
  4. 配置客户端
     • 将 MCP 客户端配置为连接 Cerberus KeyRouter 的 MCP 接口（示例在下方的服务器配置部分给出正确的 JSON 配置格式，便于前后端对接）
  5. 验证与测试
     • 访问健康接口，列出凭据项，执行安全登录操作等。

• 服务器配置（MCP 客户端需要的启动信息） 说明：以下为 MCP 客户端需要的启动配置示例（JSON 格式，包含服务器名称、启动命令及参数等信息）。请将其放入客户端的配置中，以便与服务器建立连接。实际部署中，客户端仅需读取此信息进行连接，不需要对服务器端进行改动。 { "serverName": "cerberus-login-router", "command": "docker compose", "args": ["up", "--build", "-d"], "notes": "参考仓库提供的快速启动方式（同时启动 Vaultwarden 与登录路由器）。MCP 客户端通过此信息知道如何启动并连接到 MCP 服务端。" }

• 基本使用方法

  • 步骤 1：在客户端配置中添加服务器信息（如上所示），启动并连接到 cerberus-login-router。
  • 步骤 2：通过 MCP 调用 list_vault_items，获取可用的凭据项名称与用户名（不包含密码）。
  • 步骤 3：通过 secure_login 调用，传入 vaultItem、以及要执行的一系列步骤（如 fill、type、click、wait、select 等），占位符（如 {{email}}、{{password}}）会在服务端本地替换为真实凭据后执行。
  • 步骤 4：服务器返回执行结果与步骤完成情况，必要时查看审计日志以进行追踪与合规检查。
  • 步骤 5：如需多步登录流程（SPA 等场景），可将流程拆分为多个 secure_login 调用，以完成完整的多步流程。

• 注意事项

  • 安全性：密码等敏感信息不会进入大语言模型上下文，凭据在本地生命周期内被使用后清除。
  • 审计与合规：所有操作都会被写入审计日志，便于追踪与分析。
  • 容器与本地网络：CDP 代理确保容器环境下的浏览器调试可用，且默认本地化访问限制。