qixin-ai-data/dsh-qixin-insight-mcp-oauth

dsh-qixin-insight-mcp-oauth

License: MIT
npm
node

启信慧眼 MCP OAuth 插件

DeepSeek Harness 插件：
用 OAuth 2.1 + PKCE 授权接入启信慧眼 MCP 服务端，
把它的工具挂进对话。

装上，在浏览器里登录一次，启信慧眼的企业数据工具就以 mcp__qixin_insight__
出现在对话里。不用贴 API key，不用填服务地址，任何配置文件里都不会出现 token。

- 环境要求
- 安装
- 使用
- 工作原理
- 配置
- 安全说明
- 卸载
- 已知限制
- 开发
- 相关标准

环境要求

| | |
| --- | --- |
| DeepSeek Harness | dsh CLI 与一个 profile（下面的例子用 web） |
| Node.js | ^22.19.0 \|\| >=24.0.0 |
| 启信慧眼AI开放平台账号 | 能完成授权页登录即可 |

@deepseek-ai/ 与 zod 由宿主 profile 提供，不需要单独安装：dsh 启动时会把自身依赖
链接进 profile 的模块解析路径。

安装

让 Agent 装（最省事）

把这句话发给你的 DeepSeek Harness 对话：

帮我安装这个插件 https://github.com/qixin-ai-data/dsh-qixin-insight-mcp-oauth

从 npm 安装

dsh plugin --profile web add dsh-qixin-insight-mcp-oauth
然后重启 dsh

从源码安装

git clone https://github.com/qixin-ai-data/dsh-qixin-insight-mcp-oauth.git
cd dsh-qixin-insight-mcp-oauth
npm install && npm run build
dsh plugin --profile web add "link:$(pwd)"
然后重启 dsh

包内自带 cordis.patch.yml（bundle patch），dsh plugin add 会完成依赖安装与
bundle 注册，并往 profile 的配置树里合入一行插件条目。这一行不带 config: 块，
没有任何东西需要填。

启动前可以先验证这一层：

dsh --profile web --dump-config   # 应出现 "# == dsh-qixin-insight-mcp-oauth" 层

使用

通常什么都不用做。autoConnect 默认开启：插件激活且没有有效授权时会自己发起授权、
打开浏览器。登录完成、回调落地，工具就出现了。

如果你关掉了浏览器，或者想重新连接，说一句就行：

| 你说 | 效果 |
| --- | --- |
| 「连接启信慧眼mcp」 | qixin_insight_mcp_connect——打开浏览器登录，完成后挂载 MCP 工具 |
| 「启信慧眼mcp连上了吗」 | qixin_insight_mcp_status——连接状态、受众绑定、token 过期时间、已挂载的工具前缀 |
| 「断开启信慧眼mcp」 | qixin_insight_mcp_disconnect——撤销 refresh_token、卸载工具、删除本地凭证 |

背后是三个工具：

| 工具 | 说明 |
| --- | --- |
| qixin_insight_mcp_connect | 发现 → 注册 → 打开浏览器 → 交换 code → 挂载 MCP。已有授权时复用、必要时自动刷新，不会重复弹授权页。 |
| qixin_insight_mcp_status | 是否已授权、token 过期时间、已挂载的工具前缀、是否需要重新授权。 |
| qixin_insight_mcp_disconnect | 先走 RFC 7009 吊销，再卸载工具并删除本地 grant。 |

token 会在过期前自动刷新，重启宿主后自动恢复连接。这两件事都不需要你操心。

工作原理

插件激活时先走 restore()：已存 grant 仍在、且受众绑定与配置的 url 匹配，就直接
挂载，下面这些一步都不发生。没有可用授权时才走完整的 authorize()：

sequenceDiagram
autonumber
participant P as 插件
participant M as 启信慧眼 MCP
participant A as 授权服务器
participant B as 浏览器

P->>M: RFC 9728 取受保护资源元数据
M-->>P: 规范资源标识 + 授权服务器列表
P->>A: RFC 8414 取 AS 元数据
A-->>P: 端点集合（校验 issuer 与所询问的对象一致）
P->>P: RFC 8252 绑环回监听器（随机端口）此刻才知道确切的 redirect_uri
P->>A: RFC 7591 动态客户端注册（结果缓存复用）
A-->>P: client_id
P->>P: RFC 7636 生成 S256 code_challenge 与 state
P->>B: 打开系统浏览器跳转授权页
B->>A: 用户登录并同意
A->>B: 302 重定向到 redirect_uri
B->>P: 环回端口收到 code，比对 state
P->>B: 授权成功页，2 秒后自关闭
P->>A: RFC 6749 code + code_verifier 交换 token
A-->>P: access_token / refresh_token
P->>P: RFC 8707 存下绑定到规范资源的 grant
P->>P: 以子 fiber 挂载 MCP client，工具可用

「打开系统浏览器跳转授权页」这一步，用户看到的就是这一屏：

启信慧眼授权页

绑环回监听器必须排在动态注册之前：RFC 7591 要求申报确切的 redirect_uri，
而随机端口在绑定前是未知的。

access_token 过期前，会话会刷新 token 并重挂 MCP client。重挂是被迫的，
不是偷懒：mcp-client 的 transport 在构造时就把请求头固化成静态的 requestInit，
没有换 token 的口子。代价是一次 tools/list 往返的工具抖动，且只发生在
token 生存期边界上。

配置

正常使用不需要看这一节。 每个字段都有默认值，且默认值就是启信慧眼生产环境的正确取值。
这些是留给自建部署、无头环境、多账号场景的应急出口。

要覆盖的话，写在 profile 自己的 cordis.patch.yml 里：

- id: qixin-insight-mcp
name: 'dsh-qixin-insight-mcp-oauth'
config:
url: https://mcp.your-deployment.example/mcp
openBrowser: false

| 字段 | 默认值 | 什么时候才需要改 |
| --- | --- | --- |
| url | https://mcp.qixin.com/mcp | 指向自建或预发的 MCP 端点 |
| serverName | qixin_insight | 最好别动：改了会重命名所有 mcp__qixin_insight__ 工具，引用它们的提示词或技能会失效 |
| scope | mcp:tools | 部署方定义了不同的 scope |
| clientName | WorkBuddy | 只有在启信慧眼同步改白名单时才改，见下方说明 |
| issuer | 自动发现 | 部署方不提供 RFC 9728 资源元数据 |
| callbackHost | localhost | 仅当白名单登记的 redirect_uri 主机变化时；只接受 loopback 取值（localhost、127.0.0.1、::1） |
| callbackPath | /oauth/callback | 仅当白名单登记的 redirect_uri 路径变化时 |
| callbackPort | 0（随机） | 授权服务器做完整 URI 精确匹配，而不是 RFC 8252 §7.3 的 host + path 匹配 |
| authorizeTimeoutMs | 300000 | 用户需要超过 5 分钟才能登录完 |
| requestTimeoutMs | 15000 | 到 OAuth 端点的网络较慢 |
| refreshSkewMs | 300000 | 最好别动：超过 token 生存期一半时会被自动压到一半 |
| openBrowser | true | 无头环境：关掉后授权 URL 会打进日志，手动打开 |
| autoConnect | true | 你更希望显式调用 qixin_insight_mcp_connect |
| persistCredentials | true | 关掉即仅内存，每次重启都要重新授权 |
| toolTimeoutMs | 60000 | MCP 查询耗时较长 |
| account | default | 一次安装里持有多个启信慧眼身份。小写字母、数字、连字符 |

clientName、callbackHost、callbackPath 不是普通的展示默认值。启信慧眼按注册时提交的
client_name 与 redirect_uris 做白名单校验，取值不在范围内会在注册阶段返回
HTTP 400，整个流程走不下去。改它们等于要求对方同步改白名单。

安全说明

- 公开客户端，无 client_secret。 PKCE 只接受 S256。服务端声明了 PKCE 但不含 S256 时
直接拒绝，而不是悄悄降级成 plain。
- issuer 是校验出来的，不是信任来的。 RFC 8414 §3.3 要求元数据文档里的 issuer
与所询问的对象一致。少了这道检查，能在我们被指向的 URL 上提供元数据的攻击者
就可以把整个流程重定向到他自己的服务器。
- token 不会进 cordis.yml。 MCP client 通过 ctx.plugin() 以子 fiber 挂载，
而不是写入配置树，所以 Authorization: Bearer … 这个头永远不会被序列化到磁盘。
- grant 存在 ctx.credentials（DSH 凭证服务）而不是自建存储，因为那个 seam
才提供跨进程写互斥。只有非密文的客户端注册信息留在插件自己的存储域里。
- 恢复时强制校验受众绑定。 已存 grant 的 resource 与配置的 url 不符时直接丢弃：
它属于另一个身份，而且按 RFC 8707 本来也会被拒。
- 环回监听器只绑 loopback。 callbackHost 为 localhost 时，同一端口上同时绑
127.0.0.1 与 ::1——localhost 解析到哪一栈由系统决定，Node 17+ 和 macOS 常把
::1 排在前面。绝不绑 0.0.0.0 或 ::：授权码明文出现在回调请求的 query 里，
绑通配地址等于把它交给同网段的任何人。
- 断开是真的吊销。 qixin_insight_mcp_disconnect 会先调用 RFC 7009 吊销端点，再删本地的东西，
所以服务端那侧的 refresh_token 也随之失效。

卸载

移除插件之前先执行 qixin_insight_mcp_disconnect：

断开启信慧眼 mcp

dsh plugin --profile web remove dsh-qixin-insight-mcp-oauth
然后重启 dsh

重启这一步不能省。 dsh plugin remove 只改磁盘上的 profile 与 bundle 列表，
正在运行的进程保留本次启动时的 bundle 集合，插件的 fiber 和它注册的工具都还活着——
qixin_insight_mcp_* 仍然出现在对话里、仍然能调用，看起来像没卸掉。移除、添加、
更新 bundle 都是这样，只有 profile 或 home 的 cordis.patch.yml 编辑才走热重载。

卸载本身不会清理凭证。harness 没有卸载钩子——disabled: true、删除配置条目、
热重载、进程退出，cordis 跑的是同一个 disposer，没有任何信号能区分它们。
在那里删 grant 等于为了罕见情形牺牲三种常见情形，也把「重启后自动恢复」这件事废掉了，
所以插件是刻意保留的。跳过断开会留下：

- DSH 凭证服务里的 grant 记录（本地提供方下，即 $DSH_HOME/.credentials.yaml 中
qixin-insight-mcp 下的一条）；
- qixin_insight_mcp 存储域里的非密文客户端注册信息；
- 服务端仍然有效的 refresh_token。 手改凭证文件只是让本机忘掉这个 token，
并不吊销它。只有 qixin_insight_mcp_disconnect 会吊销。

插件已经卸掉的情况下，去启信慧眼账号的已授权应用页面撤销授权，再手工删掉残留记录。

已知限制

- 一个插件条目对应一个 MCP 端点。 端点固定是刻意的设计；需要两个的话，
再加一条指向不同 url、用不同 account 的条目。
- token 轮换会有短暂的工具抖动。 重挂时一次 tools/list 往返，
只发生在 token 生存期边界上，见工作原理。
- 服务端不签发 refresh_token 时要重新完整授权。 access_token 过期后会重新走一遍
浏览器流程。
- 没有设置页 UI。 三个对话工具是唯一入口。第三方插件是可以注册 DSH 设置卡片的，
这里不做只是取舍：多一个 UI 面就多一份要同步的状态。以后要加，工具层不用改。
- 卸载后的清理是手动的。 见卸载。

开发

npm run build                    # tsc -b，产出到 lib/
npx tsc -p tsconfig.test.json    # 只类型检查测试，不产出
npm test                         # vitest run
npm run test:coverage            # 阈值：lines/functions/statements 85%，branches 80%

相关标准

RFC 6749（授权码）·
7009（吊销）·
7591（动态注册）·
7636（PKCE）·
8252（原生应用 / 环回重定向）·
8414（AS 元数据）·
8707（资源指示器）·
9728（受保护资源元数据）

许可

MIT