Customer MCP App

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

能力

• query-customers：模型和 App 均可调用，关联客户列表 UI。

• “查看详情”：使用查询结果随附的 App 专用详情数据在本地弹框，不调用 Tool。

• search-external-companies：仅 App 调用，搜索新增候选。

• prepare-customer-create：仅准备预览和短期确认令牌，不写数据。

• confirm-create-customer：用户勾选并点击确认后，最多提交一次创建请求。

• show-project-detail：通过独立 MCP View 嵌入存量业务平台项目详情；默认打开示例项目 18703741。

• Streamable HTTP：/mcp；stdio：--stdio。

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

Related MCP server: @21st-dev/magic

环境要求

• 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 后自行调整。

关键配置：

.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。

项目详情嵌入验证

1. 在 /Users/lunarjan/workspace/gjthrd_aries 启动存量前端并确认以下地址能在浏览器中打开：

   http://localhost:8081/apps/gjthrd_aries/project/18703741?name=2022%E6%9D%8E%E7%99%BD%E5%85%AC%E5%8F%B8%E5%80%BA%28%E4%B8%BB%E6%89%BF%29&from=ProjectList

2. 启动本仓库 MCP Server，并让 Host 调用 show-project-detail；不传参数即使用上述示例。

3. 如果页面被拒绝嵌入，检查实际响应的 X-Frame-Options 和 CSP frame-ancestors。

4. 如果 Host 阻止 HTTP 混合内容，把存量前端放到可访问的 HTTPS 测试地址，并更新 LEGACY_WEB_BASE_URL 后重启 MCP Server。

该验证 View 不读取 iframe DOM，也不通过 MCP Server 代理项目数据。登录、权限和页面内动作仍由存量系统控制；验证期间不要执行真实业务写操作。详细边界见 项目详情嵌入 Spec。

创建安全边界

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