dsh-qixin-insight-mcp-oauth

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

装上，在浏览器里登录一次，启信慧眼的企业数据工具就以 mcp__qixin_insight__<tool> 出现在对话里。不用贴 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 绑环回监听器（随机端口）<br/>此刻才知道确切的 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