dsh-oauth-mcp 0.0.2 → 0.0.3

package/README.md

@@ -12,102 +12,216 @@
 
 授权过的远端工具以 `mcp_oauth__<serverId>__<tool>` 的名字出现。
 
-## 宿主自带的 MCP 客户端不够用在哪
+## 目录
 
-宿主自带的 `@deepseek-ai/dsh-mcp-client` 只有 `stdio` 和 `streamable-http` 两种传输，请求头写死在配置里，没有授权码流程，没有 PKCE，也没有令牌刷新。
+1. [安装](#1-安装)
+2. [添加服务器](#2-添加服务器)
+3. [授权](#3-授权)
+4. [查看状态](#4-查看状态)
+5. [使用远端工具](#5-使用远端工具)
+6. [改配置](#6-改配置)
+7. [开发](#7-开发)
+8. [发布](#8-发布)
+9. [遇到问题怎么办](#9-遇到问题怎么办)
+10. [详细文档](#10-详细文档)
 
-要求 OAuth 的远程 MCP 服务器对未授权请求返回 `401` 和 `WWW-Authenticate`，里面写着授权服务器的地址。用宿主自带客户端接这类服务器，只能手工把一个不会自己过期的 Bearer 串写进配置，过期后改配置、重启，再改一次。
+## 1. 安装
 
-本插件把整条 OAuth 链路做在插件里：令牌过期会静默续期，收到 `401` 会先刷新再重放一次。厂商差异收在一张数据表 `knownProfiles` 里，加一家新厂商只改数据，不改代码。
-
-## 安装
+前置条件：已经装好并运行过 DSH 桌面应用。
 
 ### 从 npm 装
 
-```
-dsh plugin --profile desktop add dsh-oauth-mcp
-```
+1. 在 DSH 的终端里执行：
+
+   ```sh
+   dsh plugin --profile desktop add dsh-oauth-mcp
+   ```
+
+2. 看命令的返回值：
+
+   - `application: applied` —— 已经装上并生效，往下走
+   - `application: restart-required` —— 改动要下次启动才生效，重启 DSH
 
-宿主会读包里的 `cordis.patch.yml`，在 profile 里插入一条 `id: dsh-oauth-mcp` 的条目，加载 `dsh-oauth-mcp`。
+3. 打开「设置 → OAuth 授权管理」，确认这一节存在。
 
-装载会返回 `application: restart-required`，必须重启 DSH 客户端。重启之后设置页出现「OAuth 授权管理」页签，`/oauth-mcp` 开始响应，agent 的工具列表里出现两个 `dsh_oauth_mcp_*` 工具。
+看不到这一节时，先确认第 2 步的返回值，重启一次；还不行看[遇到问题怎么办](#9-遇到问题怎么办)。
 
 ### 从源码目录装
 
-要改代码就用这条路径。仓库用 pnpm，版本由 package.json 的 `packageManager` 字段固定，先装依赖：
+要改代码就用这条路径。仓库用 pnpm，版本由 package.json 的 `packageManager` 字段固定。
 
-```
-cd <本插件目录>
-pnpm install
-```
+1. 装依赖：
 
-再用宿主的插件安装入口装载（`plugin_manager install_bundle`，`target` 填本目录的绝对路径），命令行等价写法是 `dsh plugin add <本插件目录的绝对路径>`。profile 里这个包是指向源码目录的链接，改完源码只要重启客户端，不用重新装载。
+   ```sh
+   cd <本插件目录>
+   pnpm install
+   ```
 
-也可以先打包再装：
+2. 用宿主的插件安装入口装载（`plugin_manager install_bundle`，`target` 填本目录的绝对路径），命令行等价写法是：
 
-```
-pnpm pack                                     # 产出 dsh-oauth-mcp-0.0.1.tgz
-dsh plugin add ./dsh-oauth-mcp-0.0.1.tgz
+   ```sh
+   dsh plugin add <本插件目录的绝对路径>
+   ```
+
+3. 看返回值。需要重启就重启 DSH（见上面第 2 步）。
+
+profile 里这个包是指向源码目录的链接，改完源码只要重启客户端，不用重新装载。
+
+### 从打包文件装
+
+```sh
+pnpm pack                                     # 产出 dsh-oauth-mcp-<版本号>.tgz
+dsh plugin add ./dsh-oauth-mcp-<版本号>.tgz
 dsh plugin list | grep oauth                  # 确认装上了
 ```
 
-### 构建
+## 2. 添加服务器
 
-仓库有一步构建。浏览器那一半是浏览器以传统脚本方式加载的，import 不了同目录文件，所以 `client/index.js` 里的组件是生成出来的副本。改完 `client/panel.js`、`client/toolview.js`、`client/commandview.js` 或 `lib/profiles/known-profiles.js`，跑一次 `pnpm run build`，它会把厂商表、浏览器副本和语言文件一起重新生成，且是幂等的；`test/unit/client-sync.test.js` 会检查副本与来源逐行一致。
+1. 打开 设置 →「OAuth 授权管理」，点「添加服务器」。
 
-插件本体是纯 JavaScript，宿主直接吃 `index.js`，运行时只依赖 `@deepseek-ai/schemastery`。
+2. 在厂商下拉里选一家。内置 40 家实测过的远程 MCP 服务器，选中之后服务器地址、ID、名称、默认权限范围、授权服务器地址自动填好。
 
-## 配置
+3. 勾选权限范围，保存。
 
-设置 →「OAuth 授权管理」→「添加服务器」：填 `id` 和 `url`，勾选权限范围，保存。厂商下拉里有 40 家实测过的远程 MCP 服务器，选中之后服务器地址、ID、名称、默认权限范围、授权服务器地址自动填好。
+下拉里选「自定义」就全部手填。ID 留空会按地址自动生成。
 
-面板能改的字段只有 `servers`、`defaultScopes`、`autoConnect` 三个。`callbackMode`、`callbackPort`、`callbackPath`、`toolPrefix` 在面板里只读展示，要改去宿主的配置文件（设置 → 通用设置 →「打开配置文件」，改 profile 里 `dsh-oauth-mcp` 条目的 `config:`），保存后宿主重启本插件。
+也可以直接在地址框里输入厂商地址，插件只自动填 ID，不动名称和权限范围。
 
-GitHub、Zendesk、Slack、PagerDuty、MongoDB Atlas、Render、Shopify、Atlassian 八家要多做一步，见 [docs/vendors.md](docs/vendors.md)。
+服务器行右侧的胶囊标签是配置状态：「已启用」表示插件会尝试自动连接这台服务器，「已停用」表示插件跳过它。
 
-完整的插件配置项表和服务器条目表见 [docs/usage.md](docs/usage.md#2-配置)。
+## 3. 授权
 
-## 授权
+1. 在会话里发起授权：
 
-```
-/oauth-mcp authorize <serverId | 服务器地址>
-```
+   ```text
+   /oauth-mcp authorize <serverId | 服务器地址>
+   ```
+
+   写地址时插件会当场把它加入服务器列表，命中已知厂商时还会补上默认权限范围与授权服务器地址。
+
+2. 命令结果是一张卡片，卡片里有可点的授权链接，一行可以复制的纯 URL。
+
+3. 在浏览器里打开链接。同意动作发生在厂商自己的网页上，插件不代点。
 
-命令结果是一张卡片，卡片里有可点的授权链接、一行可以复制的纯 URL。同意动作发生在厂商自己的网页上，插件不代点。
+4. 授权完成后插件跳回 `http://127.0.0.1:39271/oauth-mcp/callback`，页面显示成功提示。页面上看不到任何令牌、code 或 state。
 
+回调端口被占用时插件自动降级到 `host-web` 或 `manual-only`。`manual-only` 模式下把浏览器地址栏里的整条回调 URL 粘回来完成授权：
+
+```text
+/oauth-mcp complete <serverId> <回调 URL>
 ```
+
+## 4. 查看状态
+
+```text
 /oauth-mcp status
 ```
 
 `status` 报告每台服务器是否已授权、过期时间、有没有刷新令牌、是否已连接、工具数。令牌本身不显示。
 
-命令结果在对话里怎么显示，见 [docs/usage.md](docs/usage.md#4-命令结果在对话里怎么显示)。界面语言跟随宿主，见 [docs/usage.md](docs/usage.md#5-界面语言)。
+看授权后拿到哪些工具：
 
-## 详细文档
-
-| 文档 | 内容 |
-| --- | --- |
-| [docs/usage.md](docs/usage.md) | 字段表、命令与工具参考、回调模式、令牌存储、错误码、故障排查 |
-| [docs/vendors.md](docs/vendors.md) | 40 家远程 MCP 服务器的 OAuth 元数据实测表 |
-| [docs/verification.md](docs/verification.md) | 12 步手工验收清单 |
-| [docs/contract.md](docs/contract.md) | 模块级接口契约 |
-| [docs/review-2026-11-07.md](docs/review-2026-11-07.md) | 六个方面的评审记录：已改的问题与剩下的清单 |
-| [DESIGN.md](DESIGN.md) | 设计全文与未决问题 |
-| [TASKS.md](TASKS.md) | 任务与验收记录 |
+```text
+/oauth-mcp tools
+```
 
-## 跑测试
+命令的完整用法：
 
+```text
+/oauth-mcp status [serverId]              查看每台服务器的状态
+/oauth-mcp tools [serverId]               查看授权后拿到的工具
+/oauth-mcp authorize <serverId | url>     授权一台服务器
+/oauth-mcp complete <serverId> <url>      用回执 URL 完成授权
+/oauth-mcp disconnect <serverId>          断开连接（凭据保留）
+/oauth-mcp cancel <serverId>             取消进行中的授权
+/oauth-mcp help                           列出这些用法
 ```
-cd <本插件目录>
-pnpm install
-pnpm test               # 等价于 node --test "test/**/*.test.js"
-```
 
-仓库记录的最近一次全量运行是 **640 例**，全绿。用例分单元、协议契约、端到端、宿主集成、冒烟五类，外加发布清单与仓库卫生两条守卫。端到端有两种：`test/e2e/full-flow.test.js` 走协议层，`test/e2e/host-flow.test.js` 走完整链路。
+## 5. 使用远端工具
+
+授权过的服务器，它的工具以 `mcp_oauth__<serverId>__<tool>` 注册成宿主工具。
+
+例如授权了 `linear`，远端的 `list_issues` 工具在宿主里叫 `mcp_oauth__linear__list_issues`。
+
+用的时候有两种写法：直接描述要做的事，agent 会自己挑合适的工具；或者点名调用，名字从 `/oauth-mcp tools` 里复制。
+
+默认前缀 `mcp_oauth` 与宿主自带的 `mcp__<server>__<tool>` 不冲突。
+
+### 惰性工具
 
-`node --test test/` 在 Node v24 上不可用：`--test` 的位置参数按 glob 解析，`test/` 会被当成模块去加载。
+授权 3 家服务器可能有 70 多个远端工具。全部挂在模型的工具表上，每一步都要背着它们的定义 —— 与本次任务无关的那部分也在里面。
 
-## 发布
+默认开着惰性工具（`lazyTools`）：
+
+1. 工具表里只有一个入口工具 `mcp_oauth`，远端工具的名字模型都看不到。
+2. agent 调用 `mcp_oauth`（可以带 `{"server":"notion"}` 指定一台，不带就列全部）。
+3. 答案里是服务器列表和它公开的工具名。
+4. 下一步起这些工具进入工具表，可以直接调用。揭示是当轮生效的。
+
+agent 凭记忆硬调没揭示的工具会被拦下，理由里写明要先调用 `mcp_oauth`。
+
+揭示状态按会话隔离：同一个会话里揭示一次就一直有效，换个会话回到没揭示的状态，不落盘。
+
+实测（DSH 桌面版 0.2.2-rc.1，授权了 notion 与 context7）：
+
+| | 工具表里的工具数 | 远端工具数 |
+| --- | --- | --- |
+| `lazyTools` 关 | 132 | 79 |
+| `lazyTools` 开 | 54 | 0 |
+
+面板里可以随时关掉这个开关，关掉后远端工具一直挂在工具表上。
+
+## 6. 改配置
+
+面板能改的字段只有 `servers`、`defaultScopes`、`autoConnect`、`lazyTools` 四个，写完立即生效，插件不重启。
+
+`callbackMode`、`callbackPort`、`callbackPath`、`toolPrefix` 在面板里只读展示，要改去宿主的配置文件（设置 → 通用设置 →「打开配置文件」，改 profile 里 `dsh-oauth-mcp` 条目的 `config:`），保存后宿主重启本插件。
+
+| 配置项 | 默认值 | 说明 |
+| --- | --- | --- |
+| `callbackMode` | `dedicated-port` | 回调接收方式：`dedicated-port` / `host-web` / `manual-only` |
+| `callbackPort` | `39271` | 回环监听端口；被占用时自动降级 |
+| `callbackPath` | `/oauth-mcp/callback` | 回调路径 |
+| `toolPrefix` | `mcp_oauth` | 远端工具的前缀，最终工具名为 `<prefix>__<serverId>__<tool>` |
+| `authorizationTimeoutMs` | `300000` | 一次授权请求的有效期 |
+| `defaultScopes` | `[]` | 服务器没有单独配置权限范围时使用的默认值 |
+| `autoConnect` | `true` | 插件启动时自动连接已启用的服务器 |
+| `servers` | `[]` | 服务器清单 |
+| `lazyTools` | `true` | 远端工具只在揭示之后进工具表 |
+
+改配置不影响令牌。令牌存在 `ctx.credentials` 里，不在插件配置里。但已建立的 MCP 会话会断开，并在下次连接时重建。
+
+GitHub、Zendesk、Slack、PagerDuty、MongoDB Atlas、Render、Shopify、Atlassian 八家要多做一步，见 [docs/vendors.md](docs/vendors.md)。
+
+完整的插件配置项表和服务器条目表见 [docs/usage.md](docs/usage.md#2-配置)。
+
+## 7. 开发
+
+仓库有一步构建。浏览器那一半是浏览器以传统脚本方式加载的，import 不了同目录文件，所以 `client/index.js` 里的组件是生成出来的副本。
+
+1. 改完 `client/panel.js`、`client/toolview.js`、`client/commandview.js` 或 `lib/profiles/known-profiles.js` 后重新生成：
+
+   ```sh
+   pnpm run build
+   ```
+
+   它把厂商表、浏览器副本和语言文件一起重新生成，且是幂等的。`test/unit/client-sync.test.js` 会检查副本与来源逐行一致。
+
+2. 跑测试：
+
+   ```sh
+   cd <本插件目录>
+   pnpm install
+   pnpm test               # 等价于 node --test "test/**/*.test.js"
+   ```
+
+   仓库记录的最近一次全量运行是 **660 例**，全绿。用例分单元、协议契约、端到端、宿主集成、冒烟五类，外加发布清单与仓库卫生两条守卫。端到端有两种：`test/e2e/full-flow.test.js` 走协议层，`test/e2e/host-flow.test.js` 走完整链路。
+
+   `node --test test/` 在 Node v24 上不可用：`--test` 的位置参数按 glob 解析，`test/` 会被当成模块去加载。
+
+插件本体是纯 JavaScript，宿主直接吃 `index.js`，运行时只依赖 `@deepseek-ai/schemastery`。
+
+## 8. 发布
 
 版本号写在 `package.json` 的 `version` 字段里。
 
@@ -116,3 +230,27 @@ pnpm test               # 等价于 node --test "test/**/*.test.js"
 CI 用 pnpm 装依赖（`pnpm install --frozen-lockfile`），每次 push 和 PR 都会在 Node 22 与 Node 24 上跑一遍测试套件。
 
 npm 发布那一步需要 GitHub 仓库里配一个 `NPM_TOKEN` secret。
+
+## 9. 遇到问题怎么办
+
+| 现象 | 原因 | 处理 |
+| --- | --- | --- |
+| 重启后设置页没有「OAuth 授权管理」 | 装载返回 `restart-required`，改动要下次启动才生效 | 重启 DSH 客户端；还不行就重新装载一次 |
+| 面板里服务器列表是空的 | 客户端脚本没连上宿主的服务 | 硬刷新浏览器（`Ctrl+Shift+R`） |
+| 改了代码但行为没变 | 宿主没有热重载 | 重启 DSH，然后在浏览器里硬刷新 |
+| 状态里报 `credential_service_unavailable` | 宿主还没提供凭据服务 | 重启 DSH |
+| 端口 39271 被占用 | 回环端口不可用 | 插件自动降级到 `host-web` 或 `manual-only` |
+
+更细的排查见 [docs/usage.md](docs/usage.md#9-故障排查)。
+
+## 10. 详细文档
+
+| 文档 | 内容 |
+| --- | --- |
+| [docs/usage.md](docs/usage.md) | 字段表、命令与工具参考、回调模式、令牌存储、错误码、故障排查 |
+| [docs/vendors.md](docs/vendors.md) | 40 家远程 MCP 服务器的 OAuth 元数据实测表 |
+| [docs/verification.md](docs/verification.md) | 12 步手工验收清单 |
+| [docs/contract.md](docs/contract.md) | 模块级接口契约 |
+| [docs/review-2026-11-07.md](docs/review-2026-11-07.md) | 六个方面的评审记录：已改的问题与剩下的清单 |
+| [DESIGN.md](DESIGN.md) | 设计全文与未决问题 |
+| [TASKS.md](TASKS.md) | 任务与验收记录 |

package/client/index.js

@@ -91,6 +91,9 @@ window.__ModuleLoader__.load({
       'panel.global.toolPrefix': '工具名前缀',
       'panel.global.defaultScopes': '默认权限范围',
       'panel.global.autoConnect': '启动时自动连接',
+      'panel.global.lazyTools': '惰性工具',
+      'panel.global.lazyToolsHint':
+      '远端工具只有在 agent 调用 mcp_oauth 揭示之后才进工具表，这样每一步就不必背着它们的定义。关掉则一直挂着。',
       'panel.global.restartHint': '回调方式、回调端口、回调路径与工具名前缀在宿主的配置文件里改（设置 → 通用设置 → 打开配置文件），保存后宿主会重启本插件。',
       'panel.servers.vendor': '厂商',
       'panel.servers.vendor.custom': '自定义（手动填写地址）',
@@ -182,6 +185,9 @@ window.__ModuleLoader__.load({
       'panel.global.toolPrefix': 'Tool name prefix',
       'panel.global.defaultScopes': 'Default scopes',
       'panel.global.autoConnect': 'Connect on startup',
+      'panel.global.lazyTools': 'Lazy tools',
+      'panel.global.lazyToolsHint':
+      'The remote tools enter the tool table only after the agent reveals them with the mcp_oauth tool, so no step carries their definitions. Turn it off to keep them in the table all the time.',
       'panel.global.restartHint':
       'Callback mode, callback port, callback path and the tool name prefix are edited in the host configuration file (Settings → General → Open configuration file); the host restarts this plugin afterwards.',
       'panel.servers.vendor': 'Vendor',
@@ -3312,6 +3318,21 @@ function createPanelComponent(React, options = {}) {
             }),
             h('span', { style: style.muted }, t('panel.global.autoConnect')),
           ),
+          h(
+            'label',
+            { className: 'dsh-oauth-mcp-panel-check', style: style.check },
+            h('input', {
+              type: 'checkbox',
+              checked: config.lazyTools !== false,
+              onChange: (event) => void writeField('lazyTools', event.target.checked),
+            }),
+            h('span', { style: style.muted }, t('panel.global.lazyTools')),
+          ),
+          h(
+            'div',
+            { className: 'dsh-oauth-mcp-panel-hint', style: style.muted },
+            t('panel.global.lazyToolsHint'),
+          ),
           h(
             'div',
             { className: 'dsh-oauth-mcp-panel-hint', style: style.muted },

package/index.js

@@ -34,9 +34,11 @@ import { createMcpSession } from './lib/mcp/session.js'
 import { createAuthFetch } from './lib/mcp/auth-fetch.js'
 import { createToolRegistry } from './lib/mcp/tool-registry.js'
 import { createToolExecutor } from './lib/mcp/tool-executor.js'
+import { createRevealState } from './lib/mcp/reveal.js'
 import { createOauthMcpService } from './lib/service.js'
 import { createAuthorizeTool } from './lib/tools/authorize.js'
 import { createStatusTool } from './lib/tools/status.js'
+import { createRevealTool } from './lib/tools/reveal.js'
 import { renderStatusTable, renderScopeDetails, renderToolTable } from './lib/view-model.js'
 import { redactText } from './lib/util/redact.js'
 import { readConfigArray, readConfigField } from './lib/util/config.js'
@@ -95,6 +97,7 @@ export const Config = z.object({
   autoConnect: z.boolean().default(true).volatile(),
   servers: z.array(ServerSchema).default([]).volatile(),
   locale: z.string().default('').volatile(),
+  lazyTools: z.boolean().default(true).volatile(),
 })
 
 /**
@@ -238,10 +241,18 @@ export async function apply(ctx, config) {
     disconnect: (serverId) => disconnectServer(serverId),
   }
 
+  // The lazy exposure state. While it is on, the remote tools are only offered
+  // to the model after the model asked for them through the entry tool.
+  const reveal = createRevealState({
+    enabled: config.lazyTools !== false,
+    toolPrefix: config.toolPrefix,
+  })
+
   const toolRegistry = createToolRegistry({
     tools: ctx.tools,
     toolPrefix: config.toolPrefix,
     logger,
+    admissionFor: (serverId) => reveal.admission(serverId),
     callTool: async (serverId, remoteToolName, args, options) => {
       const connection = connectionMap.get(serverId)
       if (!connection?.executor) {
@@ -435,6 +446,26 @@ export async function apply(ctx, config) {
   )
   dispose(ctx.tools.register(createStatusTool({ service, logger, config, settings })))
 
+  // --- the lazy exposure -----------------------------------------------------
+  // While the lazy exposure is on, the remote tools are not in the model's
+  // tool table until the model asks for them through the `mcp_oauth` entry
+  // tool. The entry tool itself is always in the table: it is the only hint
+  // the model gets that the remote tools exist.
+  dispose(ctx.tools.register(createRevealTool({ reveal, service, locale: () => config.locale })))
+
+  // A model may remember a tool name from an earlier step and call it even
+  // though the tool is not in this step's table. The guard turns that call
+  // into an explanation instead of an opaque failure.
+  if (typeof ctx.tools.guard === 'function') {
+    try {
+      dispose(ctx.tools.guard((exec) => reveal.guardFor(exec)))
+    } catch (guardError) {
+      logger?.warn?.('dsh-oauth-mcp: the tool guard did not register', {
+        error: String(guardError?.message ?? guardError),
+      })
+    }
+  }
+
   // --- the host command ------------------------------------------------------
   if (commands?.register) {
     dispose(

package/lib/build-info.js

@@ -12,13 +12,13 @@ import { createTranslator } from './i18n/index.js'
 export const PLUGIN_ID = 'dsh-oauth-mcp'
 
 /** The version of the plugin. It is reported to every server it talks to. */
-export const PLUGIN_VERSION = '0.0.2'
+export const PLUGIN_VERSION = '0.0.3'
 
 /**
  * Short marker of the current source revision. Bump it whenever the behaviour
  * of the user facing surfaces (commands, tools, panel, callback pages) changes.
  */
-export const BUILD_STAMP = '2026-11-08-release-timer-fix'
+export const BUILD_STAMP = '2026-11-08-lazy-tools'
 
 /**
  * One line that names the version and the build of the running code.

package/lib/mcp/reveal.js

@@ -0,0 +1,264 @@
+/**
+ * Lazy exposure of the remote MCP tools.
+ *
+ * The problem this module solves: every tool of every authorized server used to
+ * sit in the model's tool table for the whole session. A profile that
+ * authorized three servers carried thirty-odd remote tool schemas in every
+ * step, whether the task touched the desktop or not.
+ *
+ * The host already has the primitive for this. `@deepseek-ai/dsh-tools` lets a
+ * registration carry a `when` condition:
+ *
+ * ```js
+ * tools.register(definition, { when: (context) => boolean })
+ * ```
+ *
+ * The condition is evaluated once per model step, before the step's tool table
+ * is built. A tool whose condition returns `false` is not in that step's tool
+ * table at all — the model neither sees its schema nor knows its name. The
+ * condition receives `{ agent, modelSelection, signal }`, so the decision can
+ * be per session.
+ *
+ * This module owns the state behind that decision:
+ *
+ * * {@link createRevealState} keeps, per agent, the set of servers whose tools
+ *   the model has asked for. The state lives in a `WeakMap` keyed by the live
+ *   agent, so a new session starts over and a finished agent is collected.
+ * * {@link RevealState#admission} produces the `when` condition for one
+ *   server.
+ * * {@link RevealState#guard} produces the dispatch veto. The `when` condition
+ *   already keeps an unrevealed tool out of the tool table, but the model may
+ *   remember a name from an earlier step and call it anyway; the guard turns
+ *   that call into an explanation instead of an opaque failure.
+ *
+ * The reveal is per session on purpose. A user who authorized three servers
+ * does not want to re-reveal them in every new conversation, but a task that
+ * never touches a remote server should not pay for their schemas either. The
+ * compromise this module takes: the state is per agent, and the entry tool
+ * reveals everything on request.
+ *
+ * @module dsh-oauth-mcp/mcp/reveal
+ */
+
+/**
+ * The state of the reveal, for every agent that asked for tools.
+ */
+export class RevealState {
+  /**
+   * The revealed servers per agent.
+   *
+   * @type {WeakMap<object, Set<string>>}
+   */
+  #agents = new WeakMap()
+
+  /**
+   * The servers that were revealed to every agent.
+   *
+   * A server revealed here is offered to every session. The plugin uses it
+   * for the servers the user marked as always available; nothing sets it yet,
+   * but the code path exists so the semantics do not change later.
+   *
+   * @type {Set<string>}
+   */
+  #global = new Set()
+
+  /**
+   * Whether lazy exposure is on at all.
+   *
+   * When it is off every remote tool is admitted, exactly as before this
+   * module existed. The setting belongs to the plugin configuration.
+   *
+   * @type {boolean}
+   */
+  #enabled
+
+  /**
+   * The prefix of the public tool names, used to recognise them in a dispatch.
+   *
+   * @type {string}
+   */
+  #toolPrefix
+
+  /**
+   * Build the state.
+   *
+   * @param {object} [options] The options.
+   * @param {boolean} [options.enabled=true] Whether lazy exposure is on.
+   * @param {string} [options.toolPrefix='mcp_oauth'] The prefix of the public tool names.
+   */
+  constructor({ enabled = true, toolPrefix = 'mcp_oauth' } = {}) {
+    this.#enabled = enabled !== false
+    this.#toolPrefix = typeof toolPrefix === 'string' && toolPrefix.length > 0 ? toolPrefix : 'mcp_oauth'
+  }
+
+  /**
+   * Whether lazy exposure is on.
+   *
+   * @returns {boolean} True when the tools are revealed on demand.
+   */
+  get enabled() {
+    return this.#enabled
+  }
+
+  /**
+   * The servers revealed to one agent.
+   *
+   * @param {object | undefined | null} agent The agent.
+   * @returns {Set<string>} The revealed server ids.
+   */
+  #revealedFor(agent) {
+    if (!agent || typeof agent !== 'object') return this.#global
+    let revealed = this.#agents.get(agent)
+    if (!revealed) {
+      revealed = new Set(this.#global)
+      this.#agents.set(agent, revealed)
+    }
+    return revealed
+  }
+
+  /**
+   * Whether one server is revealed to one agent.
+   *
+   * @param {object | undefined | null} agent The agent.
+   * @param {string} serverId The server id.
+   * @returns {boolean} True when the tools of that server may be offered.
+   */
+  isRevealed(agent, serverId) {
+    if (!this.#enabled) return true
+    if (this.#global.has(serverId)) return true
+    return this.#revealedFor(agent).has(serverId)
+  }
+
+  /**
+   * Reveal servers to one agent.
+   *
+   * @param {object | undefined | null} agent The agent.
+   * @param {string[]} serverIds The servers to reveal.
+   * @returns {string[]} The server ids that are revealed afterwards.
+   */
+  reveal(agent, serverIds) {
+    if (!agent || typeof agent !== 'object') return []
+    const revealed = this.#revealedFor(agent)
+    const added = []
+    for (const serverId of serverIds) {
+      if (typeof serverId !== 'string' || serverId.length === 0) continue
+      if (revealed.has(serverId)) continue
+      revealed.add(serverId)
+      added.push(serverId)
+    }
+    return added
+  }
+
+  /**
+   * Reveal every server to one agent.
+   *
+   * @param {object | undefined | null} agent The agent.
+   * @param {string[]} serverIds Every known server id.
+   * @returns {string[]} The server ids that are revealed afterwards.
+   */
+  revealAll(agent, serverIds) {
+    return this.reveal(agent, serverIds)
+  }
+
+  /**
+   * The `when` condition for the tools of one server.
+   *
+   * The condition is what the host evaluates per model step. It returns true
+   * when the tools of that server may be offered to the model.
+   *
+   * @param {string} serverId The server id.
+   * @returns {(context: { agent?: unknown }) => boolean} The condition.
+   */
+  admission(serverId) {
+    if (!this.#enabled) return () => true
+    return (context) => this.isRevealed(context?.agent, serverId)
+  }
+
+  /**
+   * The dispatch veto for the tools of one server.
+   *
+   * The veto runs when a tool is about to be dispatched. It refuses a call to
+   * a server that was not revealed and explains how to reveal it. It returns
+   * `undefined` for a call it allows, which is what the host expects.
+   *
+   * @param {string} serverId The server id.
+   * @returns {(exec: { name?: string, agent?: unknown }) => string | undefined} The veto.
+   */
+  guard(serverId) {
+    if (!this.#enabled) return () => undefined
+    return (exec) => {
+      if (this.isRevealed(exec?.agent, serverId)) return undefined
+      return this.#refusal(serverId)
+    }
+  }
+
+  /**
+   * The refusal the guard gives for a server that was not revealed.
+   *
+   * @param {string} serverId The server id.
+   * @returns {string} The message.
+   */
+  #refusal(serverId) {
+    return (
+      `The tools of the MCP server "${serverId}" are not revealed in this session. ` +
+      `Call the "${REVEAL_TOOL_NAME}" tool with {"server":"${serverId}"} first, ` +
+      'then call the tool again.'
+    )
+  }
+
+  /**
+   * The dispatch veto for every remote tool of the plugin.
+   *
+   * The host calls this before every tool dispatch. It recognises the remote
+   * tools by their public name and refuses the ones whose server was not
+   * revealed; every other tool of the host passes through untouched.
+   *
+   * @param {{ name?: string, agent?: unknown }} exec The pending call.
+   * @returns {string | undefined} The refusal, or undefined when the call is allowed.
+   */
+  guardFor(exec) {
+    if (!this.#enabled) return undefined
+    const serverId = this.#serverIdOf(exec?.name)
+    if (serverId === undefined) return undefined
+    if (this.isRevealed(exec?.agent, serverId)) return undefined
+    return this.#refusal(serverId)
+  }
+
+  /**
+   * The server a public tool name belongs to.
+   *
+   * The public name is `<prefix>__<serverId>__<toolName>`, so the server id
+   * is the middle part. A name that does not have that shape is not a remote
+   * tool of this plugin.
+   *
+   * @param {unknown} name The public tool name.
+   * @returns {string | undefined} The server id, or undefined.
+   */
+  #serverIdOf(name) {
+    if (typeof name !== 'string') return undefined
+    if (!name.startsWith(`${this.#toolPrefix}__`)) return undefined
+    const rest = name.slice(this.#toolPrefix.length + 2)
+    const separator = rest.indexOf('__')
+    if (separator <= 0) return undefined
+    return rest.slice(0, separator)
+  }
+}
+
+/**
+ * The name of the tool that reveals the remote tools.
+ *
+ * @type {string}
+ */
+export const REVEAL_TOOL_NAME = 'mcp_oauth'
+
+/**
+ * Build the reveal state of the plugin.
+ *
+ * @param {object} [options] The options.
+ * @param {boolean} [options.enabled=true] Whether lazy exposure is on.
+ * @param {string} [options.toolPrefix='mcp_oauth'] The prefix of the public tool names.
+ * @returns {RevealState} The state.
+ */
+export function createRevealState(options = {}) {
+  return new RevealState(options)
+}

package/lib/mcp/tool-registry.js

@@ -108,10 +108,11 @@ function buildDescription(serverId, remoteToolName, remoteDescription) {
  * @param {object} [options.logger] The host logger; every call is optional.
  * @param {(serverId: string, remoteToolName: string, args: object, callOptions: { timeoutMs?: number, signal?: AbortSignal }) => Promise<unknown>} [options.callTool] The injected executor that performs `tools/call`.
  * @param {number} [options.timeoutMs] The timeout of one tool call, in milliseconds.
+ * @param {(serverId: string) => ((context: { agent?: unknown }) => boolean)} [options.admissionFor] The per-server condition that decides whether the tools of that server are offered to the model. The host evaluates it once per model step; a tool whose condition is false is not in that step's tool table.
  * @returns {object} The registry: `sync`, `unregisterServer`, `dispose`, `hostToolName`.
  */
 export function createToolRegistry(options = {}) {
-  const { tools, logger, callTool } = options
+  const { tools, logger, callTool, admissionFor } = options
   const toolPrefix = typeof options.toolPrefix === 'string' && options.toolPrefix.length > 0
     ? options.toolPrefix
     : DEFAULT_TOOL_PREFIX
@@ -121,6 +122,23 @@ export function createToolRegistry(options = {}) {
     throw new TypeError('createToolRegistry requires the host tool service.')
   }
 
+  /**
+   * The admission condition of one server.
+   *
+   * Without a condition every tool of every server is offered to the model,
+   * which is the behaviour before the lazy exposure existed. With one, the
+   * host evaluates it per model step and leaves the tools of a server that
+   * was not revealed out of that step's tool table.
+   *
+   * @param {string} serverId The server id.
+   * @returns {(context: { agent?: unknown }) => boolean} The condition.
+   */
+  function admission(serverId) {
+    if (typeof admissionFor !== 'function') return () => true
+    const condition = admissionFor(serverId)
+    return typeof condition === 'function' ? condition : () => true
+  }
+
   /** Registrations per server: `serverId` → `remoteToolName` → registration. */
   const registrations = new Map()
   /** Public name → the registration that owns it. */
@@ -239,7 +257,7 @@ export function createToolRegistry(options = {}) {
 
     let disposer
     try {
-      disposer = tools.register(definition)
+      disposer = tools.register(definition, { when: admission(serverId) })
     } catch (registerError) {
       error(`dsh-oauth-mcp: the host refused the tool "${name}".`, registerError)
       return

package/lib/tools/reveal.js

@@ -0,0 +1,137 @@
+/**
+ * The `mcp_oauth` agent tool: the entry point of the lazy exposure.
+ *
+ * While lazy exposure is on, the remote tools of the authorized servers are
+ * not in the model's tool table. This tool is the way in: the model calls it
+ * to learn which servers are authorized and which tools they expose, and the
+ * tools it asks for become callable from the next step on.
+ *
+ * The tool is the only one the plugin keeps in the table unconditionally, so
+ * it is also the tool that tells the model that the others exist. Its
+ * description has to carry that job on its own: the model sees this tool and
+ * nothing else.
+ *
+ * @module dsh-oauth-mcp/tools/reveal
+ */
+
+import { REVEAL_TOOL_NAME } from '../mcp/reveal.js'
+
+export { REVEAL_TOOL_NAME }
+
+/** JSON Schema of the value the tool resolves with. */
+const REVEAL_OUTPUT_SCHEMA = Object.freeze({
+  type: 'array',
+  description: 'The servers whose tools were revealed, and the tools they expose.',
+  items: {
+    type: 'object',
+    properties: {
+      serverId: { type: 'string', description: 'The identifier of the revealed MCP server.' },
+      label: { type: 'string', description: 'The human readable label of the server.' },
+      authorized: { type: 'boolean', description: 'Whether the server has a usable grant.' },
+      connected: { type: 'boolean', description: 'Whether the MCP session is established.' },
+      tools: {
+        type: 'array',
+        items: { type: 'string' },
+        description:
+          'The public names of the tools of this server, for example "mcp_oauth__notion__search". They are callable from the next step on.',
+      },
+    },
+    required: ['serverId', 'label', 'authorized', 'connected', 'tools'],
+  },
+})
+
+/**
+ * The description of the entry tool.
+ *
+ * It is written for a model that has no other MCP tool in its table: it says
+ * what the tool is for, when to call it, and what comes back.
+ *
+ * @returns {string} The description.
+ */
+function buildDescription() {
+  return (
+    'Reveal the tools of the OAuth protected MCP servers of this profile. ' +
+    'The tools of those servers are not in your tool table until you ask for them, ' +
+    'so that every step does not carry their schemas. ' +
+    'Call it with {"server":"<serverId>"} to reveal one server, ' +
+    'or without arguments to list the authorized servers. ' +
+    'The answer lists the server and the names of its tools; those names are callable from the next step on.'
+  )
+}
+
+/**
+ * Build the entry tool.
+ *
+ * @param {object} options The options.
+ * @param {import('../mcp/reveal.js').RevealState} options.reveal The reveal state.
+ * @param {{ status: (serverId?: string) => Promise<object[]>, listToolNames: (serverId: string) => string[] }} options.service The plugin service.
+ * @param {() => string} [options.locale] The current locale.
+ * @returns {object} The tool definition.
+ */
+export function createRevealTool({ reveal, service, locale }) {
+  return {
+    name: REVEAL_TOOL_NAME,
+    description: buildDescription(),
+    parameters: {
+      type: 'object',
+      properties: {
+        server: {
+          type: 'string',
+          description:
+            'The id of the MCP server to reveal, for example "notion". Leave it out to list the authorized servers.',
+        },
+      },
+    },
+    output: { schema: REVEAL_OUTPUT_SCHEMA, render: (value) => value },
+    execute: async (args, exec) => {
+      const agent = exec?.agent
+      const requested = typeof args?.server === 'string' ? args.server.trim() : ''
+
+      const rows = await service.status(requested || undefined)
+      if (rows.length === 0) {
+        return [
+          {
+            type: 'text',
+            text: requested
+              ? `No MCP server with the id "${requested}" is configured in this profile.`
+              : 'No MCP server is configured in this profile. Add one in the settings, then authorize it.',
+          },
+        ]
+      }
+
+      // Reveal what the model asked for. Without a server id every authorized
+      // server is revealed: the model asked what is there, and the answer is
+      // more useful than another round trip.
+      const wanted = rows.filter((row) => row.authorized).map((row) => row.serverId)
+      const target = requested ? rows.filter((row) => row.serverId === requested) : rows
+      const revealIds = target.filter((row) => row.authorized).map((row) => row.serverId)
+      reveal.reveal(agent, revealIds)
+
+      const lines = []
+      for (const row of target) {
+        const tools = service.listToolNames(row.serverId)
+        lines.push(
+          [
+            `${row.serverId}: ${row.label}`,
+            row.authorized ? 'authorized' : 'not authorized yet',
+            row.connected ? 'connected' : 'not connected',
+            tools.length > 0 ? `tools: ${tools.join(', ')}` : 'no tools yet',
+          ].join(' — '),
+        )
+      }
+      if (requested && revealIds.length === 0) {
+        lines.push(`The server "${requested}" is not authorized yet, so its tools were not revealed.`)
+      }
+      if (wanted.length === 0 && !requested) {
+        lines.push('No server is authorized yet. Use the oauth-mcp command to authorize one.')
+      }
+
+      return [
+        {
+          type: 'text',
+          text: lines.join('\n'),
+        },
+      ]
+    },
+  }
+}

package/locale/en.json

@@ -45,6 +45,8 @@
   "panel.global.toolPrefix": "Tool name prefix",
   "panel.global.defaultScopes": "Default scopes",
   "panel.global.autoConnect": "Connect on startup",
+  "panel.global.lazyTools": "Lazy tools",
+  "panel.global.lazyToolsHint": "The remote tools enter the tool table only after the agent reveals them with the mcp_oauth tool, so no step carries their definitions. Turn it off to keep them in the table all the time.",
   "panel.global.restartHint": "Callback mode, callback port, callback path and the tool name prefix are edited in the host configuration file (Settings → General → Open configuration file); the host restarts this plugin afterwards.",
   "panel.servers.vendor": "Vendor",
   "panel.servers.vendor.custom": "Custom (type the address yourself)",

package/locale/zh-CN.json

@@ -45,6 +45,8 @@
   "panel.global.toolPrefix": "工具名前缀",
   "panel.global.defaultScopes": "默认权限范围",
   "panel.global.autoConnect": "启动时自动连接",
+  "panel.global.lazyTools": "惰性工具",
+  "panel.global.lazyToolsHint": "远端工具只有在 agent 调用 mcp_oauth 揭示之后才进工具表，这样每一步就不必背着它们的定义。关掉则一直挂着。",
   "panel.global.restartHint": "回调方式、回调端口、回调路径与工具名前缀在宿主的配置文件里改（设置 → 通用设置 → 打开配置文件），保存后宿主会重启本插件。",
   "panel.servers.vendor": "厂商",
   "panel.servers.vendor.custom": "自定义（手动填写地址）",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-oauth-mcp",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "OAuth 2.1 client and MCP bridge for DSH: discover and authorize remote MCP servers, keep tokens fresh, and expose their tools",
   "keywords": [
     "dsh",