Customer MCP App

基于已验证的 Hermes 开发环境 API 构建的客户 MCP App。模型可按名称查询客户；支持 MCP Apps 的 Host 还会获得 React 交互界面，用于分页、查看详情、搜索外部企业，以及经过明确确认后安全新增客户。

能力

• query-customers：模型和 App 均可调用，关联客户列表 UI。
• “查看详情”：使用查询结果随附的 App 专用详情数据在本地弹框，不调用 Tool。
• search-external-companies：仅 App 调用，搜索新增候选。
• prepare-customer-create：仅准备预览和短期确认令牌，不写数据。
• confirm-create-customer：用户勾选并点击确认后，最多提交一次创建请求。
• Streamable HTTP：/mcp；stdio：--stdio。

界面不直接连接 Hermes，也不会接触 Cookie、Session Token 或完整的原始创建资料。

环境要求

• Node.js 20 或更高版本。
• 能访问目标 Hermes 环境；开发环境通常还需要 aTrust/零信任连接。
• 有效的登录 Cookie。可选地同时提供业务 User ID 和 Session Token。

安装与配置

npm install
npm run setup:local

setup:local 会要求粘贴一次浏览器开发者工具中 dev 请求的完整 Cookie Header 值，输入过程不回显。脚本会自动生成：

• .env：已填好的 dev Base URL 和本地运行参数；
• .local/hermes-cookie.txt：明文 Cookie，仅当前用户可读。

两者都被 Git 忽略，服务启动时会自动加载 .env，不需要手动 source。如果当前 shell 已有 HERMES_COOKIE，脚本会直接使用它而不再询问。

也可以先把 Cookie Header 值复制到 macOS 剪贴板，再执行 npm run setup:local:clipboard；脚本不会打印剪贴板内容。

需要连接其他环境时，也可以复制 .env.example 后自行调整。

关键配置：

变量	必需	说明
HERMES_BASE_URL	是	Hermes API 根路径，例如本地代理的 http://127.0.0.1:8081/hermes；远端地址只允许 HTTPS
HERMES_COOKIE	二选一	完整 Cookie 请求头值
HERMES_COOKIE_FILE	二选一	只含 Cookie 值的本地文件路径；自动生成时使用绝对路径
HERMES_USER_ID	否	与 HERMES_SESSION_TOKEN 成对配置
HERMES_SESSION_TOKEN	否	与 HERMES_USER_ID 成对配置
HERMES_TIMEOUT_MS	否	上游超时，默认 15000 ms
MCP_HOST / PORT	否	HTTP 监听地址；代码默认 127.0.0.1:3001，setup:local 为 Docker Quick Tunnel 生成 0.0.0.0:3002
MCP_ALLOWED_ORIGINS	否	逗号分隔的浏览器 Origin 白名单
MCP_PUBLIC_URL	否	当前 Quick Tunnel 的 HTTPS URL；仅用于 Codex Host 阻断 iframe tools/call 时启用短期令牌兼容通道，可填写带 /mcp 的完整 endpoint

.env、.local/、Cookie 和 Session Token 已被 Git 忽略；即使是 dev 凭证，也不要把真实值写进代码、文档、日志或测试。

启动

HTTP：

npm run build
npm run serve

使用 setup:local 生成的配置时，MCP endpoint 为 http://127.0.0.1:3002/mcp，健康检查为 http://127.0.0.1:3002/health；服务实际监听 0.0.0.0:3002，以便 Docker 容器通过 host.docker.internal:3002 访问。0.0.0.0 是监听地址，不是客户端 URL。

0.0.0.0 模式不配置固定 Host allowlist，以兼容每次变化的 *.trycloudflare.com Host Header；MCP_ALLOWED_ORIGINS 的浏览器 CORS 白名单仍然生效。当前 MCP endpoint 没有远程身份认证，随机 Tunnel URL 也不是访问控制，因此该模式仅供开发者监督下的短时本地联调。

Docker Quick Tunnel

保持 MCP App 和 aTrust 在宿主机运行，启动 Docker Desktop 后执行：

docker run --rm \
  --name customer-mcp-tunnel \
  --dns 1.1.1.1 \
  --dns 1.0.0.1 \
  cloudflare/cloudflared:latest \
  tunnel --no-autoupdate --protocol http2 \
  --url http://host.docker.internal:3002

只使用本次命令新打印的 https://<random>.trycloudflare.com/mcp。如果当前 Codex Host 无法代理 View 内按钮调用，把同一个地址写入 .env 的 MCP_PUBLIC_URL 并重启服务；服务会启用短期能力令牌保护的 UI 兼容端点。终端必须保持运行；测试完成后按 Ctrl+C 同时停止 Tunnel 并删除临时容器。需要稳定域名、长期运行或多人共享时，必须移除该临时通道或另行增加受信网关身份认证和授权。

stdio：

npm run build
npm run serve:stdio

本地开发（监听 UI 和 Server 源码变化）：

npm run dev

验证

npm run typecheck
npm test
npm run build

自动化测试全部使用 mock，不连接真实 Hermes 环境，也不会执行真实创建。运行和排障细节见 运行手册，需求与验收标准见 客户列表 Spec。

创建安全边界

新增客户始终经过“获取原始资料 → 查重 → 展示预览 → 用户明确确认 → 再次查重 → 单次创建 → 回查”。确认令牌默认 5 分钟过期，只在进程内保存哈希。创建请求发生超时或断网时不会自动重试；系统只做只读回查，无法确认结果时要求先人工核查客户列表。