@dsh-cc/mcp-client 0.5.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/mcp/mcp-client/README.md
+README.md: 5c2ae4c5c608554a6c3b5ea02c41a80a4e36a08b
+README.zh.md: 655256c6931361b80d269bb37f2e5f83c9e1dc34

package/README.md

@@ -0,0 +1,149 @@
+# @dsh-cc/mcp-client
+
+English | [中文](README.zh.md)
+
+MCP client bridge plugin: connects to external [Model Context Protocol](https://modelcontextprotocol.io/) servers and registers their tools on `ctx.tools`, making them available to the model as native tools under server-qualified names (`mcp__<serverName>__<rawName>`).
+
+## Usage
+
+One plugin instance per MCP server in `cordis.yml`:
+
+```yaml
+- id: mcp-github
+  name: '@dsh-cc/mcp-client'
+  config:
+    serverName: github
+    transport: stdio
+    command: npx
+    args: ['-y', '@modelcontextprotocol/server-github']
+    env:
+      GITHUB_TOKEN: !!js process.env.GITHUB_TOKEN
+
+- id: mcp-web
+  name: '@dsh-cc/mcp-client'
+  config:
+    serverName: web
+    transport: streamable-http
+    url: http://localhost:3000/mcp
+    headers:
+      Authorization: !!js '`Bearer ${process.env.MCP_TOKEN}`'
+
+- id: mcp-feed
+  name: '@dsh-cc/mcp-client'
+  config:
+    serverName: feed
+    transport: sse
+    url: http://localhost:3001/sse
+    oauth:
+      redirectUrl: http://localhost:8787/callback
+```
+
+The model sees `mcp__github__create_issue`, `mcp__web__search`, … — the same server-qualified shape Claude Code and Codex use. HMR hot-swaps: editing the entry triggers disconnect + reconnect without process restart; an unchanged `serverName` reproduces identical tool names.
+
+## Config
+
+| Field | Transport | Required | Description |
+|---|---|---|---|
+| `transport` | both | yes | `"stdio"`, `"streamable-http"`, or `"sse"` |
+| `serverName` | both | yes | Namespace for this server's model-facing tool names; `[A-Za-z0-9_-]{1,32}`, unique across live instances |
+| `command` | stdio | yes | Executable to spawn |
+| `args` | stdio | no | Arguments passed to the command |
+| `env` | stdio | no | Extra env vars merged on top of scrubbed ambient env |
+| `cwd` | stdio | no | Working directory for the child process |
+| `url` | http | yes | MCP server URL |
+| `headers` | http | no | Extra headers (e.g. auth tokens) |
+| `oauth` | http | no | OAuth flow options (see below) |
+| `toolCallTimeoutMs` | both | no | Timeout per `callTool` invocation (default 60000) |
+| `failOnStartupError` | both | no | Reject plugin activation when initial connection or tool synchronization fails (default `false`) |
+| `reconnect.enabled` | both | no | Reconnect automatically after a lost connection (default `true`) |
+| `reconnect.initialDelayMs` | both | no | First reconnect delay in ms; doubles per consecutive failed attempt (default 500) |
+| `reconnect.maxDelayMs` | both | no | Backoff ceiling in ms; also the uptime after which the attempt budget resets (default 30000) |
+| `reconnect.maxAttempts` | both | no | Consecutive failed attempts per outage before giving up for good (default 10) |
+
+## Tool naming
+
+Every MCP tool has two names: the raw MCP name (sent on the wire in `tools/call`) and the public name `mcp__<serverName>__<rawName>` registered on `ctx.tools`. Public names are normalized to the DeepSeek function-name contract (64 chars, `[A-Za-z0-9_-]`); when replacement or truncation changes the name, a deterministic 12-hex-char hash of `(serverName, rawName)` is appended so distinct tools never collapse into one name. Names are pure functions of `(serverName, rawName)` — connection order, re-syncs, and other servers never rename a tool.
+
+- Two servers publishing the same raw name (e.g. `search`) coexist under their namespaces.
+- A duplicate `serverName` across live instances fails the later plugin instance at load.
+- A server listing the same tool name twice is rejected as an invalid tool list.
+- A foreign registration squatting on this server's namespace rolls back the whole generation (never a partial set), with a loud error.
+
+## Behavior
+
+- On connect: plugin activation awaits `listTools()` and publishes each tool under its public name before the composition starts its first turn — eagerly via `ctx.tools.register()`, or deferred through `ctx.toolSearch.registerDeferred` when that seam is mounted and the server lists at least `deferToolThreshold` tools (default 8). Initial connection, discovery, or registration failure is always logged; it rejects activation when `failOnStartupError` is true and otherwise activates with no tools.
+- Listens for `notifications/tools/list_changed` → re-syncs; a fetch-phase failure keeps the previous generation registered, while a registration conflict rolls back the attempted generation and leaves no tools from that server.
+- Tool execute: `client.callTool({ name: rawName, arguments }, { signal })` with timeout + abort support—the public name is never sent to the server.
+- Canonical success is `{ content: JsonValue[], structuredContent? }`; complete JSON MCP blocks survive for programmatic callers. A supported advertised `outputSchema` validates `structuredContent`; unsupported schema vocabulary falls back to unconstrained `JsonValue`.
+- Native/model rendering keeps the existing text projection: text blocks join with newlines while image, audio, resource, and unsupported blocks become placeholders.
+- On disconnect/crash: the supervisor restarts the original server config with exponential backoff (`reconnect.initialDelayMs` doubling up to `reconnect.maxDelayMs`) and re-runs discovery on success — the recovered generation replaces the previous one, so tools neither duplicate nor leak. During the outage the last good generation stays registered; calls against it fail until recovery.
+- Reconnection is budgeted per outage: after `reconnect.maxAttempts` consecutive failures the server's tools are unregistered and reconnection stops until an HMR reload or Host restart. A connection that survives past `maxDelayMs` resets the budget, so an occasionally-crashing server recovers indefinitely while a crash-looping one — even with briefly successful connects — still exhausts the cap instead of restarting forever.
+- Reconnect states are user-visible in logs: reconnecting (warn, with attempt count and delay), recovered (info), final failure and disabled-loss (error). Disposal cancels any pending reconnect. With `reconnect.enabled: false`, a lost connection keeps tools registered but failing until a reload — the manual-recovery behavior.
+- Stdio server stderr is piped, never inherited, so it cannot paint a TUI. The stream is appended to `$DSH_HOME/mcp-logs/<serverName>.log`, rotated at 4 MiB with one `.log.1` backup generation and a trimmed tail is attached to connection-failure / connection-lost warns. Headless users no longer see live server stderr on the terminal.
+
+## Capabilities
+
+Beyond tools, the bridge exposes a server's other MCP capabilities when the server declares them:
+
+- **Resources** — exposed as two server-qualified model tools, `mcp__<serverName>__list_mcp_resources` and `mcp__<serverName>__read_mcp_resource`, which call `resources/list` and `resources/read`. The `ctx.fs` seam (a real-filesystem abstraction over `FsTarget`/`readBytes`) cannot represent virtual MCP resources, so these bridge tools are the fallback the capability seam prescribes. Resource-list-change notifications re-register the bridge.
+- **Prompts** — each MCP prompt is registered as a skill on `ctx.skills` when the prompt capability is declared. Skill names map the `mcp__<server>__<prompt>` shape onto the registry's lowercase-kebab grammar (`mcp-<server>-<prompt>`). Argumentless prompts are resolved via `prompts/get` and their rendered text becomes the skill body; prompts that require arguments are documented with their argument contract instead. MCP-sourced skills are inert prose — never executable shell. Prompt-list-change notifications re-register the skills. Prompt bridging requires the `ctx.skills` service; without it the bridge is a no-op.
+- **OAuth** — network transports (`streamable-http`, `sse`) accept an `oauth` block. Tokens, registered-client information, the PKCE code verifier, and discovery state are persisted through the `ctx.credentials` reference seam (stored under derived credential references, never inline). The MCP SDK drives RFC 9728 → RFC 8414 metadata discovery, dynamic client registration, scheme-code PKCE, and token refresh through the provider; a mid-session `401` is retried once after dropping the stale token state. OAuth requires the `ctx.credentials` service.
+
+The supervisor keeps each capability's registrations live across an outage (last-good wins) and removes them on give-up or disposal, all through one serialized swap chain.
+
+## Services consumed
+
+| Service | Usage |
+|---|---|
+| `ctx.tools` | Register/unregister MCP tools and the resource bridge |
+| `ctx.toolSearch` | Optional: defer over-threshold listed tools (duck-typed; never a required inject) |
+| `ctx.skills` | Optional: register MCP prompt skills |
+| `ctx.credentials` | Optional: persist OAuth tokens and related state |
+
+## Model Experience
+
+### Discovered MCP tools
+
+#### What the model sees
+
+After initial discovery succeeds, each advertised MCP tool appears as a native tool named `mcp__<serverName>__<rawName>` (or its deterministic normalized form), with the server-provided description and input schema. A successful re-sync — including the one after an automatic reconnect — replaces the generation; plugin disposal or an exhausted reconnect budget removes it.
+
+When the `ctx.toolSearch` seam is mounted and this server lists at least **8 tools** (the default `deferToolThreshold`; counts the `tools/list` length including alwaysLoad tools), deferrable tools register **deferred** instead: they contribute name + description + a server-qualified search hint to the ToolSearch pool and stay out of the model-visible schema until a ToolSearch hit activates them (`activate` performs the real registration, callable exactly like any top-of-prompt tool afterward). A tool advertising `_meta['anthropic/alwaysLoad'] === true` registers eagerly even on a deferred server. Resource-bridge tools (`mcp__<server>__list_mcp_resources` / `read_mcp_resource`) always stay eager. Without the toolSearch seam — standalone deployments, other presets — every tool registers eagerly at any threshold.
+
+A generation swap (reconnect or `tools/list_changed`) disposes the previous generation first, which also unloads tools the model had activated via ToolSearch: after the swap those names are searchable again, and the model must search (or the session must re-activate) before calling them. Identical re-syncs on the same client are skipped by fingerprint and re-publish nothing.
+
+#### Token effect
+
+Data-dependent schema cost is paid on every request while the tools are registered — deferred tools pay it only after activation, replacing their schema cost with one ToolSearch tool plus per-hit activations. Re-sync replaces rather than accumulates schemas, and the server-qualified name adds tokens to every tool definition and call.
+
+#### KV Cache effect
+
+Prefix-stable while the discovered tool set and schemas are unchanged. A re-sync that adds, removes, renames, or changes a tool replaces definitions and may invalidate reuse from the first changed schema token; a reconnect that recovers an unchanged list reproduces identical definitions and stays prefix-stable. The first deferred registration also inserts the ToolSearch tool into the model-visible set (one-time prefix change; it stays registered afterward — hysteresis).
+
+### Tool-call history and results
+
+#### What the model sees
+
+The public tool name and JSON arguments remain in assistant history. Text result blocks are joined with newlines into one retained Native text result; image, audio, resource, and unsupported blocks become short placeholders there. Their full JSON blocks and optional structured content remain in the execution-local canonical value, and MCP `isError` rejects the call through the registry's error path.
+
+#### Token effect
+
+Arguments and mapped text are retained until compaction. Binary and resource payloads are discarded rather than added to context.
+
+#### KV Cache effect
+
+Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
+
+## Known Limitations and Deferred Work
+
+- **The defer threshold is per-server tool count, not context size** — a percentage-of-context or cross-server aggregate rule (Claude Code's ~10%) would defer more aggressively; three small servers of five tools each all stay eager. The threshold is also not configurable via plugin Config yet (tests pass it into `syncTools` directly).
+- **ToolSearch activation is process-global** — loading a deferred MCP tool makes it visible to every agent whose tool restriction admits the name, and there is no per-conversation discovery history (see the `dsh-tool-search` README).
+- **Programmatic `ctx.tools.execute` on a reserved-but-unactivated MCP name fails as unknown** — the definition does not exist until a ToolSearch hit activates it; no in-repo caller relies on this.
+- **Exact frontmatter MCP names must match the public (possibly hashed) name** — server-prefix wildcards sidestep most of that.
+
+- **Dynamic OAuth client registration is delegated to the MCP SDK** — the SDK owns RFC 9728/8414 metadata discovery, PKCE, dynamic client registration, and token refresh; this package supplies the credentials-backed persistence half of the `OAuthClientProvider` seam and the single 401 retry. An interactive `redirectToAuthorization` logs the URL for a headless host rather than driving a browser; completing the flow still requires an operator.
+- **Startup timeout is inherited from the MCP SDK** — DSH does not yet expose a connection/discovery timeout. Each initialize or paginated `tools/list` request uses the SDK's 60-second default, so an unresponsive server or cursor chain can delay both activation and teardown while the initial synchronization settles.
+- **Reconnect triggers on transport close** — a crashed stdio child fires it; Streamable HTTP failures surface per request and through the SDK transport's own SSE-stream recovery, so an unreachable HTTP server is retried per call rather than respawned by the supervisor.
+- **Native non-text rendering is lossy** — image, audio, and resource payloads become placeholders in model context even though the execution-local canonical value preserves their JSON blocks. Richer Native multimedia projection is deferred.
+- **Unsupported MCP output schemas are not enforced** — `structuredContent` falls back to `JsonValue` when the advertised schema uses vocabulary outside the harness subset.
+- **Resource bridging uses the two-tool fallback, not a filesystem provider** — the `ctx.fs` seam cannot represent virtual MCP resources; the ListMcpResources/ReadMcpResource model tools are the current surface.

package/README.zh.md

@@ -0,0 +1,150 @@
+# @dsh-cc/mcp-client
+
+[English](README.md) | 中文
+
+MCP 客户端桥接插件：连接外部 [Model Context Protocol](https://modelcontextprotocol.io/) 服务器，把它们的工具注册到 `ctx.tools`，使模型能够通过服务器限定名称（`mcp__<serverName>__<rawName>`）将其作为原生工具使用。
+
+## 用法
+
+`cordis.yml` 中每个 MCP 服务器使用一个插件实例：
+
+```yaml
+- id: mcp-github
+  name: '@dsh-cc/mcp-client'
+  config:
+    serverName: github
+    transport: stdio
+    command: npx
+    args: ['-y', '@modelcontextprotocol/server-github']
+    env:
+      GITHUB_TOKEN: !!js process.env.GITHUB_TOKEN
+
+- id: mcp-web
+  name: '@dsh-cc/mcp-client'
+  config:
+    serverName: web
+    transport: streamable-http
+    url: http://localhost:3000/mcp
+    headers:
+      Authorization: !!js '`Bearer ${process.env.MCP_TOKEN}`'
+
+- id: mcp-feed
+  name: '@dsh-cc/mcp-client'
+  config:
+    serverName: feed
+    transport: sse
+    url: http://localhost:3001/sse
+    oauth:
+      redirectUrl: http://localhost:8787/callback
+```
+
+模型会看到 `mcp__github__create_issue`、`mcp__web__search` 等工具，这与 Claude Code 和 Codex 使用的服务器限定形状相同。HMR（热模块替换）支持热替换：编辑配置项会触发断开 + 重新连接，无需重启进程；`serverName` 不变时会生成完全相同的工具名称。
+
+## 配置
+
+| 字段 | 传输 | 必填 | 描述 |
+|---|---|---|---|
+| `transport` | 两者 | 是 | `"stdio"`、`"streamable-http"` 或 `"sse"` |
+| `serverName` | 两者 | 是 | 该服务器面向模型工具名称的 namespace；`[A-Za-z0-9_-]{1,32}`，在存活实例中唯一 |
+| `command` | stdio | 是 | 要 spawn 的可执行文件 |
+| `args` | stdio | 否 | 传给命令的参数 |
+| `env` | stdio | 否 | 合并到已清理环境中的额外环境变量 |
+| `cwd` | stdio | 否 | 子进程工作目录 |
+| `url` | http | 是 | MCP 服务器 URL |
+| `headers` | http | 否 | 额外标头（例如认证 token） |
+| `oauth` | http | 否 | OAuth 流程选项（见下文） |
+| `toolCallTimeoutMs` | 两者 | 否 | 每次 `callTool` 调用的超时（默认 60000） |
+| `failOnStartupError` | 两者 | 否 | 初始连接或工具同步失败时拒绝插件激活（默认 `false`） |
+| `reconnect.enabled` | 两者 | 否 | 连接丢失后自动重新连接（默认 `true`） |
+| `reconnect.initialDelayMs` | 两者 | 否 | 首次重连延迟（毫秒）；每次连续失败尝试翻倍（默认 500） |
+| `reconnect.maxDelayMs` | 两者 | 否 | 退避上限（毫秒）；同时也是重置尝试预算所需的正常运行时长（默认 30000） |
+| `reconnect.maxAttempts` | 两者 | 否 | 每次中断期间连续失败尝试次数上限，超出后彻底放弃（默认 10） |
+
+## 工具命名
+
+每个 MCP 工具都有两个名称：通过 `tools/call` 在协议上传送的原始 MCP 名称，以及公开名称 `mcp__<serverName>__<rawName>`，后者注册到 `ctx.tools`。公开名称会规范化为 DeepSeek 函数名称约定（64 个字符、`[A-Za-z0-9_-]`）；如果替换或截断改变名称，就会追加 `(serverName, rawName)` 的确定性 12 位十六进制 hash，确保不同工具绝不会折叠为同一个名称。名称是 `(serverName, rawName)` 的纯函数：连接顺序、重新同步和其他服务器永远不会重命名工具。
+
+- 发布相同原始名称（例如 `search`）的两个服务器会在各自 namespace 下共存。
+- 存活实例中的重复 `serverName` 会使后加载的插件实例失败。
+- 服务器在工具列表中两次列出同一工具名称时，该列表会作为无效工具列表被拒绝。
+- 外部注册抢占该服务器 namespace 时，会回滚整个世代（绝不保留部分集合），并明确报错。
+
+## 行为
+
+- 连接时：插件激活会等待 `listTools()`，并在组合开始首个轮次前以公开名称发布每个工具——默认通过 `ctx.tools.register()` 即时注册；当 `ctx.toolSearch` seam 已挂载且该服务器列出的工具数达到 `deferToolThreshold`（默认 8）时，改为经 `registerDeferred` 延迟注册。初始连接、发现或注册失败始终会记录日志；`failOnStartupError` 为 true 时拒绝激活，否则插件仍会激活但不注册工具。
+- 监听 `notifications/tools/list_changed` → 重新同步；获取阶段失败时保留上一世代的注册，注册冲突则会回滚本次尝试的世代，并且不保留该服务器的任何工具。
+- 工具执行：`client.callTool({ name: rawName, arguments }, { signal })`，支持超时 + 中止；公开名称绝不会发给服务器。
+- 规范成功值是 `{ content: JsonValue[], structuredContent? }`；完整的 JSON MCP 块会保留给编程调用方。受支持且已声明的 `outputSchema` 会验证 `structuredContent`；不受支持的 schema 词汇会回退为不受约束的 `JsonValue`。
+- Native／模型渲染保留现有文本投影：文本块以换行连接，图片、音频、资源和不受支持的块会变成占位符。
+- 断开／崩溃时：supervisor 以指数退避（`reconnect.initialDelayMs` 逐次翻倍，上限 `reconnect.maxDelayMs`）重启原始服务器配置，成功后重新执行发现——恢复的世代会替换前一个，因此工具既不会重复也不会泄漏。中断期间最后一个正常世代保持注册；针对它的调用在恢复前会失败。
+- 重连按中断预算控制：连续失败达到 `reconnect.maxAttempts` 次后，该服务器的工具会被注销，重连停止，直到 HMR 重载或重启 Host。连接存活超过 `maxDelayMs` 会重置预算，因此偶尔崩溃的服务器可以无限恢复，而崩溃循环的服务器——即使短暂连接成功——仍会耗尽上限而非永远重启。
+- 重连状态在日志中对用户可见：reconnecting（warn，含尝试次数和延迟）、recovered（info）、最终失败和 disabled-loss（error）。dispose（资源释放）会取消任何待执行的重连。设置 `reconnect.enabled: false` 时，连接丢失后工具保持注册但调用失败，直到重载——即手动恢复行为。
+- stdio 服务器的 stderr 会被管道捕获、不再继承父进程，因此不会刷到 TUI。内容追加到 `$DSH_HOME/mcp-logs/<serverName>.log`，达到 4 MiB 时轮转并保留一份 `.log.1` 备份，截断后的尾部会附在连接失败 / 连接丢失的 warn 上。无界面运行时终端上也不再出现服务器的实时 stderr。
+
+## 消费的服务
+
+| 服务 | 用途 |
+|---|---|
+| `ctx.tools` | 注册／注销 MCP 工具及资源桥 |
+| `ctx.toolSearch` | 可选：把超过阈值的列出工具延迟注册（duck-type；不是必选 inject） |
+| `ctx.skills` | 可选：注册 MCP 提示词技能 |
+| `ctx.credentials` | 可选：持久化 OAuth token 及相关状态 |
+
+## 能力
+
+除工具外，当服务器声明其他 MCP 能力时，桥也会将其暴露出来：
+
+- **资源（Resources）**——以两个服务器限定的模型工具 `mcp__<serverName>__list_mcp_resources` 与 `mcp__<serverName>__read_mcp_resource` 暴露，分别调用 `resources/list` 与 `resources/read`。`ctx.fs` seam（针对真实文件系统的抽象，基于 `FsTarget`/`readBytes`）无法表达虚拟 MCP 资源，因此这两个桥接工具正是能力 seam 规定的回退方案。资源列表变更通知会重新注册桥。
+- **提示词（Prompts）**——当声明提示词能力时，每个 MCP 提示词都会作为技能注册到 `ctx.skills`。技能名把 `mcp__<server>__<prompt>` 形状映射到注册表的 lowercase-kebab 语法（`mcp-<server>-<prompt>`）。无参数提示词通过 `prompts/get` 解析，其渲染文本成为技能正文；需要参数的提示词则以参数约定作为文档。MCP 来源的技能是惰性纯文本——绝不包含可执行的 shell。提示词列表变更通知会重新注册技能。提示词桥需要 `ctx.skills` 服务；缺失时该桥为空操作。
+- **OAuth**——网络传输（`streamable-http`、`sse`）接受 `oauth` 配置块。token、已注册客户端信息、PKCE code verifier 与发现状态通过 `ctx.credentials` 引用 seam 持久化（存储在派生的凭据引用下，绝不内联）。MCP SDK 通过 provider 驱动 RFC 9728 → RFC 8414 元数据发现、动态客户端注册、授权码 PKCE 与 token 刷新；会话中途的 `401` 会在丢弃过期 token 状态后重试一次。OAuth 需要 `ctx.credentials` 服务。
+
+supervisor 在中断期间保持每个能力的注册存活（保留最后一个正常世代），并在放弃或 dispose 时移除，全部经由一条串行化的交换链。
+
+
+## 模型体验
+
+### 已发现的 MCP 工具
+
+#### 模型看到的内容
+
+初始发现成功后，每个已声明的 MCP 工具都会显示为名为 `mcp__<serverName>__<rawName>`（或其确定性规范化形式）的原生工具，并携带服务器提供的描述和输入 schema。成功的重新同步——包括自动重连后的同步——会替换整个世代；对插件执行 dispose（资源释放）或重连预算耗尽会移除该世代。
+
+当 `ctx.toolSearch` seam 已挂载、且该服务器列出的工具数达到 **8 个**（默认 `deferToolThreshold`；按 `tools/list` 数组长度计，含 alwaysLoad 工具）时，可延迟的工具改为**延迟注册**：它们向 ToolSearch 池贡献名称 + 描述 + 服务器限定的搜索提示，在 ToolSearch 命中激活之前不进入模型可见 schema（激活执行真正的注册，此后与任何提示词顶部的工具无异）。声明 `_meta['anthropic/alwaysLoad'] === true` 的工具即使在延迟服务器上也立即注册。资源桥工具（`mcp__<server>__list_mcp_resources` / `read_mcp_resource`）始终保持即时注册。没有 toolSearch seam 时——独立部署、其他 preset——任何阈值下全部工具都即时注册。
+
+世代替换（重连或 `tools/list_changed`）会先注销上一世代，这同时会卸载模型此前通过 ToolSearch 激活的工具：替换之后这些名字重新变为可搜索，模型必须再次搜索（或由会话重新激活）才能调用。同一客户端上的相同重新同步由 fingerprint 跳过，不会重新发布任何内容。
+
+#### Token 影响
+
+工具注册期间，每次请求都会承担数据相关的 schema 成本——延迟工具只在激活后才承担该成本，其 schema 成本被一个 ToolSearch 工具加每次命中的激活所取代。重新同步会替换而非累积 schema，服务器限定名称也会为每个工具定义和调用增加 token。
+
+#### KV Cache 影响
+
+只要已发现工具集合及其 schema 不变，前缀就保持稳定。增加、移除、重命名或更改工具的重新同步会替换定义，并可能使从第一个变化的 schema token 起的复用失效；恢复了未变列表的重连会生成完全相同的定义，前缀保持稳定。首个延迟注册还会把 ToolSearch 工具插入模型可见集合（一次性前缀变化；此后保持注册——迟滞）。
+
+### 工具调用历史与结果
+
+#### 模型看到的内容
+
+公开工具名称和 JSON 参数会保留在 assistant 历史中。文本结果块会以换行连接为一个保留的 Native 文本结果；图片、音频、资源和不受支持的块在其中变为简短占位符。它们的完整 JSON 块及可选结构化内容保留在执行局部的规范值中；MCP `isError` 会通过注册表的错误路径拒绝调用。
+
+#### Token 影响
+
+参数和映射后的文本会保留到压缩（compaction）发生时。二进制与资源载荷会被丢弃，而不会加入上下文。
+
+#### KV Cache 影响
+
+仅追加；新可见内容位于可复用请求前缀之后，不会使现有 KV-cache 条目失效。
+
+## 已知限制与暂缓事项
+
+- **延迟阈值按服务器工具数计，而非上下文占比**：按上下文百分比或跨服务器聚合的规则（Claude Code 的约 10%）会更激进地延迟；三个各 5 个工具的小服务器全部保持即时注册。阈值也尚不能通过插件 Config 配置（测试直接把选项传入 `syncTools`）。
+- **ToolSearch 激活是进程全局的**：加载一个延迟 MCP 工具后，凡工具限制放行该名字的 agent 都能看到它，且没有按会话的发现历史（见 `dsh-tool-search` README）。
+- **对已预留但未激活的 MCP 名字执行程序化 `ctx.tools.execute` 会以 unknown 失败**：定义在 ToolSearch 命中激活之前并不存在；仓库内没有调用方依赖此路径。
+- **frontmatter 里的精确 MCP 名字必须与公开名（可能带 hash 后缀）一致**：服务器前缀通配符可以绕开大多数此类问题。
+
+- **动态 OAuth 客户端注册委托给 MCP SDK**：SDK 负责 RFC 9728/8414 元数据发现、PKCE、动态客户端注册与 token 刷新；本包只提供基于凭据的 `OAuthClientProvider` seam 持久化半边与单次 401 重试。交互式 `redirectToAuthorization` 在 headless 主机上只记录 URL 而不会驱动浏览器；完成流程仍需操作者介入。
+- **启动超时继承自 MCP SDK**：DSH 尚未公开连接／发现超时。每次 initialize 请求或分页 `tools/list` 请求都使用 SDK 默认的 60 秒，因此在初始同步完成期间，无响应的 server 或 cursor chain 可能同时延迟激活与 teardown。
+- **重连在传输关闭时触发**：崩溃的 stdio 子进程会触发重连；Streamable HTTP 失败通过每次请求以及 SDK 传输自身的 SSE（Server-Sent Events）流恢复机制暴露，因此不可达的 HTTP 服务器会按调用重试，而非由 supervisor 重新 spawn。
+- **Native 非文本渲染有损**：图片、音频与资源载荷在模型上下文中会变成占位符，即使执行局部的规范值保留了其 JSON 块。更丰富的 Native 多媒体投影暂缓实现。
+- **不强制执行不受支持的 MCP 输出 schema**：已声明 schema 使用 harness 子集之外的词汇时，`structuredContent` 会回退到 `JsonValue`。
+- **资源桥使用两个工具的回退方案，而非文件系统 provider**：`ctx.fs` seam 无法表达虚拟 MCP 资源；当前表面是 ListMcpResources/ReadMcpResource 两个模型工具。

package/lib/auth.d.ts

@@ -0,0 +1,66 @@
+/**
+ * OAuth support: a `ctx.credentials`-backed `OAuthClientProvider` for the MCP
+ * SDK's streamable-HTTP and SSE transports.
+ *
+ * The SDK implements RFC 9728 → RFC 8414 metadata discovery, PKCE, dynamic
+ * client registration, and token refresh behind its `OAuthClientProvider`
+ * interface (driven by the transport's `authProvider` option). This module
+ * supplies the durable half of that seam: OAuth tokens, registered-client
+ * information, the PKCE code verifier, and discovery state are persisted through
+ * the `ctx.credentials` reference capability — values are stored under
+ * server-derived credential references rather than inline, so configuration
+ * surfaces never see the secret material.
+ *
+ * 401 handling: the transport auto-refreshes an expired access token against a
+ * stored refresh token before a request; a mid-session `401` surfaces as an
+ * `UnauthorizedError`, which the tool bridge retries once after invalidating
+ * and re-running the token flow ({@link retryUnauthorizedOnce}).
+ *
+ * @module
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { OAuthClientProvider, OAuthDiscoveryState } from '@modelcontextprotocol/sdk/client/auth.js';
+import type { OAuthClientInformationMixed, OAuthClientMetadata, OAuthTokens } from '@modelcontextprotocol/sdk/shared/auth.js';
+/** Config selecting an interactive OAuth flow for a network transport. */
+export interface OAuthConfig {
+    /** Redirect URL the user agent returns to after authorizing. */
+    redirectUrl?: string;
+    /** Stable OAuth client name reported to the authorization server. */
+    clientName?: string;
+    /**
+     * Credential-reference prefix (defaults to `MCP_OAUTH_<SERVER>`); the provider
+     * derives `_TOKENS`, `_CLIENT`, `_VERIFIER`, and `_DISCOVERY` refs from it.
+     */
+    credentialPrefix?: string;
+}
+/**
+ * `ctx.credentials`-backed {@link OAuthClientProvider}. Every artifact is a
+ * JSON value persisted under a derived credential reference; absent refs mean
+ * "no state" (unconfigured), and an empty stored value counts as unset.
+ */
+export declare class CredentialsOAuthClientProvider implements OAuthClientProvider {
+    private readonly ctx;
+    private readonly tokensRef;
+    private readonly clientRef;
+    private readonly verifierRef;
+    private readonly discoveryRef;
+    private readonly redirectUrlValue;
+    constructor(ctx: Context, serverName: string, config: OAuthConfig);
+    get redirectUrl(): string | URL | undefined;
+    get clientMetadata(): OAuthClientMetadata;
+    clientInformation(): Promise<OAuthClientInformationMixed | undefined>;
+    saveClientInformation(clientInformation: OAuthClientInformationMixed): Promise<void>;
+    tokens(): Promise<OAuthTokens | undefined>;
+    saveTokens(tokens: OAuthTokens): Promise<void>;
+    redirectToAuthorization(authorizationUrl: URL): void;
+    saveCodeVerifier(codeVerifier: string): Promise<void>;
+    codeVerifier(): Promise<string>;
+    saveDiscoveryState(state: OAuthDiscoveryState): Promise<void>;
+    discoveryState(): Promise<OAuthDiscoveryState | undefined>;
+    invalidateCredentials(scope: 'all' | 'client' | 'tokens' | 'verifier' | 'discovery'): Promise<void>;
+    /** Read a credential value, treating an empty value as unset. */
+    private read;
+    /** Persist a value; an empty value is removed rather than stored. */
+    private write;
+}
+//# sourceMappingURL=auth.d.ts.map

package/lib/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,KAAK,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,0CAA0C,CAAA;AACxG,OAAO,KAAK,EACV,2BAA2B,EAC3B,mBAAmB,EACnB,WAAW,EACZ,MAAM,0CAA0C,CAAA;AAGjD,0EAA0E;AAC1E,MAAM,WAAW,WAAW;IAC1B,gEAAgE;IAChE,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,qEAAqE;IACrE,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAC1B;AAQD;;;;GAIG;AACH,qBAAa,8BAA+B,YAAW,mBAAmB;IAQtE,OAAO,CAAC,QAAQ,CAAC,GAAG;IAPtB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAe;IAC3C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;IAC5C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAoB;gBAGlC,GAAG,EAAE,OAAO,EAC7B,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,WAAW;IAWrB,IAAI,WAAW,IAAI,MAAM,GAAG,GAAG,GAAG,SAAS,CAE1C;IAED,IAAI,cAAc,IAAI,mBAAmB,CAQxC;IAEK,iBAAiB,IAAI,OAAO,CAAC,2BAA2B,GAAG,SAAS,CAAC;IAKrE,qBAAqB,CAAC,iBAAiB,EAAE,2BAA2B,GAAG,OAAO,CAAC,IAAI,CAAC;IAIpF,MAAM,IAAI,OAAO,CAAC,WAAW,GAAG,SAAS,CAAC;IAK1C,UAAU,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAIpD,uBAAuB,CAAC,gBAAgB,EAAE,GAAG,GAAG,IAAI;IAO9C,gBAAgB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIrD,YAAY,IAAI,OAAO,CAAC,MAAM,CAAC;IAK/B,kBAAkB,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,CAAC;IAI7D,cAAc,IAAI,OAAO,CAAC,mBAAmB,GAAG,SAAS,CAAC;IAK1D,qBAAqB,CAAC,KAAK,EAAE,KAAK,GAAG,QAAQ,GAAG,QAAQ,GAAG,UAAU,GAAG,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAazG,iEAAiE;YACnD,IAAI;IAKlB,qEAAqE;YACvD,KAAK;CAOpB"}