feat: prefer remote MCP OAuth installation
This commit is contained in:
@@ -3,11 +3,13 @@
|
||||
一个面向 Agent 的统一审批 MCP。用户只登录一次钉钉，即可读取、处理和发起本人在钉钉 OA 与薪福通中的审批：
|
||||
|
||||
```text
|
||||
Agent → 本地轻量 stdio 桥 → HTTPS/OAuth 统一网关
|
||||
├─ 钉钉 OA OpenAPI
|
||||
└─ 薪福通 OpenAPI
|
||||
Agent → 远程 Streamable HTTP MCP / OAuth 统一网关
|
||||
├─ 钉钉 OA OpenAPI
|
||||
└─ 薪福通 OpenAPI
|
||||
```
|
||||
|
||||
只有宿主不支持远程 MCP 或标准 OAuth 时，才使用本地 STDIO Bridge 兼容层。
|
||||
|
||||
## 工具
|
||||
|
||||
- `approval_login`：检查登录或返回唯一授权链接。
|
||||
@@ -75,32 +77,11 @@ Agent 不传 `userId`、员工号或单据所有者。网关从 OAuth Token 确
|
||||
https://approval.justconn.top/downloads/dingmcp/install.md
|
||||
```
|
||||
|
||||
用户把这个链接交给 Agent 后，Agent 先校验并运行当前平台的原生 PowerShell 或 POSIX 安装引导。Windows、Linux、macOS 均支持 x64 与 ARM64，系统无需预装 Node.js：引导会复用兼容的系统 Node，或者从阿里云、npmmirror、Node 官方的精确版本地址依次下载 Node 22.23.2，并用固定的 Node 官方 SHA-256 校验后安装为插件私有运行时。它不修改系统 PATH、不需要管理员权限，也不使用任何 `latest` 镜像别名。
|
||||
默认流程不下载任何客户端：Agent 按宿主官方方式把 `https://approval.justconn.top/mcp` 注册为远程 Streamable HTTP MCP，由宿主通过标准 OAuth 元数据、动态客户端注册和 PKCE 完成登录。用户端不需要 Node.js、npm、DWS、企业凭证或本地常驻进程。用户本人确认授权后，Agent 用 `approval_list_todos(source=all, limit=1)` 只读验证钉钉 OA 与薪福通都可用。
|
||||
|
||||
随后安装器使用固定 Ed25519 公钥验证清单和发布物，把轻量客户端安装到稳定的用户数据目录，并统一返回 `bridgePath`、`skillPath`、`loginCommand`、`nodeRuntime` 和标准 `mcpConfig`；不再区分 Agent 品牌，不全局安装 npm 包，也不会猜测或直接修改 Agent 的私有配置。启动器固定使用安装时选定的 Node，用户以后升级系统 Node 或切换版本管理器不会改变 MCP 命令。安装器会立即在受保护的本地会话中检查登录并返回机器可读 `postInstall`：未登录时直接带回当前授权链接，网关暂时不可用也不会使安装回滚。Agent 随后按自身官方方式安装 Skill、注册并信任本地 stdio MCP；不能热加载连接器时再新建会话或重启。用户端不安装 DWS，不需要企业凭证。
|
||||
服务端 MCP `instructions` 和工具描述包含完整审批工作流，因此远程模式不依赖本地 Skill 才能安全使用。宿主需要重新加载连接器时按其官方机制处理；OAuth 过期也由宿主标准刷新/重新授权流程解决，无需重装。
|
||||
|
||||
公开 `install.md` 是一份可直接交给 Agent 执行的逐步教程，为 Windows PowerShell 与 Linux/macOS 分别提供完整路径。它覆盖平台/架构检测、安装引导校验、国内下载回退、安装 JSON 验收、Skill/MCP 注册、连接器信任、首次登录、钉钉 OA 与薪福通双来源验证、更新、卸载和故障恢复。Windows 必须原样使用安装器返回的本地 `.cmd` stdio 配置；远程网关 URL 不能直接配置为 MCP，否则宿主可能显示 HTTP 302 或把本地 Bridge 误判为崩溃。
|
||||
|
||||
首次安装的 Agent 工具调用应预留至少 10 分钟。平台引导和安装器持续把不含凭证的阶段进度写入 stderr，stdout 只保留最终 JSON；Windows 即使宿主默认 shell 是 Git Bash，也必须转由 PowerShell bootstrap 执行，不能直接调用内部 Node 安装器。客户端用跨进程锁阻止并发安装，外部终止后再次运行会回收已经死亡的锁和残留 staging；离线 npm 展开超过 180 秒时会返回明确错误，不会无限静默等待。
|
||||
|
||||
Agent 必须在安装后立即展示 `postInstall.authChallenge.directUrl`，不得等到第一次审批查询，也不得声称链接已另行推送。用户授权后，Agent 通过 `approval_login` 确认登录并用 `source=all` 做一次双来源只读验证；首次成功认证响应还会在普通 `content.text` 和 `structuredContent.onboarding` 中返回一次性的简短使用示例，展示后不会重复，也不会自动执行任何写操作。
|
||||
|
||||
授权链接约十分钟有效。过期后不需要更新或重装：MCP 已加载时再次调用 `approval_login`；尚未加载时执行安装结果中的 `loginCommand`（等价于稳定客户端的 `login --json`）。两条入口复用同一本地 OAuth 会话，都会返回当前有效链接或自动生成新链接。
|
||||
|
||||
首次授权会先显示网关自己的 OAuth 确认页，列出请求客户端、返回域名、权限范围或设备授权码；用户确认后才跳转钉钉。客户端名称由客户端自行声明，因此应同时核对域名或授权码。短暂的网关 5xx/网络故障不会清除本地 refresh token，也不会强迫用户重新登录。
|
||||
|
||||
客户端后续可使用稳定 CLI：
|
||||
|
||||
```text
|
||||
dingtalk-approval login --json
|
||||
dingtalk-approval print-path bridge
|
||||
dingtalk-approval print-config --format mcp-json
|
||||
dingtalk-approval doctor --json
|
||||
dingtalk-approval update --json
|
||||
dingtalk-approval uninstall --yes --json
|
||||
```
|
||||
|
||||
实际 `dingtalk-approval` 路径由首次安装结果的 `cliPath` 给出。`login` 只使用现有运行时与登录会话；`update` 会复用已固定的清单地址与公钥，并保留 OAuth 登录会话。更新完成后应重新连接该 MCP，Agent 不能单独重启连接器时再新建会话或重启。卸载默认删除客户端运行时、Skill、安装记录和 OAuth 会话；Agent 中名为 `dingtalk-approval` 的连接器通过其官方入口删除。
|
||||
只有宿主明确不支持远程 Streamable HTTP MCP 或标准 OAuth 时，才使用 `compat-install.md` 安装本地 Bridge。兼容引导仍支持 Windows、Linux、macOS x64/ARM64 和无 Node 环境，并使用固定 Ed25519 清单与 SHA-256 校验。PowerShell 发行脚本带 UTF-8 BOM，Node 探测避免 Windows PowerShell 5.1 吞引号；Windows 下载优先使用 `curl.exe`，连接、低速或 90 秒总超时会明确失败并换固定来源，不再静默等待 300 秒。
|
||||
|
||||
## 数据与安全
|
||||
|
||||
|
||||
Reference in New Issue
Block a user