@deepseek-ai/dsh-mcp-client 0.1.5-rc.2 → 0.1.6-alpha.2

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # 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: de646256888f1c271ad94a4c863338dfb02551e6
-README.zh.md: 2c71060ec309e823ff3456207881e27ab9aca553
+README.md: a241dda5d77da5cea1d7092a99d670ead564ba03
+README.zh.md: dbebdae8675aecf9c1107f53c9aeec9469def1df

package/README.md

@@ -9,7 +9,7 @@ English | [中文](README.zh.md)
 
 ## Summary
 
-`dsh-mcp-client` lets the model call tools from external Model Context Protocol (MCP) servers as native harness tools. Configure one server per entry, and its tools appear under stable names such as `mcp__github__create_issue`. Use it for filesystem, GitHub, database, memory, or other MCP tool servers; no server is enabled by default. Tool definitions add tokens to every model request, while a slow or crashed server can delay startup or make its tools fail until recovery. The package bridges tools only; MCP resources and prompts are unsupported.
+`dsh-mcp-client` lets the model use tools and resources from external Model Context Protocol (MCP) servers. Configure one server per entry; its tools use names such as `mcp__github__create_issue`. No server is enabled by default. Shipped profiles already provide [shared resource discovery and reading](../mcp-resources/README.md). An empty caller scope adds no MCP tools or prompt text. Server instructions join the logged system prompt as literal text; MCP prompt templates are unsupported. Slow or crashed servers can delay startup or fail calls until recovery.
 
 ## Table of Contents
 
@@ -25,7 +25,7 @@ English | [中文](README.zh.md)
 <a id="use-this-package"></a>
 ## Use this package
 
-Add `dsh-mcp-client` when the model should call tools from an external MCP server as if they were native. One configuration entry per server is the entire setup: give the server a short unique name and a transport, and its tools appear as `mcp__<serverName>__<tool>`. Choose stdio when the server runs as a local program and Streamable HTTP when it runs as a service. If you already use MCP tool servers from another client, the same server rows work here.
+Add `dsh-mcp-client` when the model should call tools from an external MCP server as if they were native. Give each server a unique name and transport. The official SDK selects the 2026-07-28 protocol when available and falls back to supported legacy revisions. Choose stdio for a local program and Streamable HTTP for a service; stdio negotiation starts a temporary probe process before the serving process.
 
 ### Minimal configuration
 
@@ -58,7 +58,8 @@ Add one entry per server; nothing else is required. After the harness starts, th
 | `serverName` | required | Namespace for the server's tool names; `[A-Za-z0-9_-]{1,32}`, unique inside one registration scope |
 | `command` / `args` / `env` / `cwd` | — | stdio: executable, arguments, extra env merged over scrubbed ambient env, working directory |
 | `url` / `headers` | — | streamable-http: endpoint URL and extra request headers |
-| `toolCallTimeoutMs` | `60,000` | Timeout per `tools/call` invocation |
+| `toolCallTimeoutMs` | `60,000` | Timeout per `tools/call` or resource request |
+| `maxInstructionBytes` | `32,768` | Maximum UTF-8 bytes of server instructions including attribution; an oversized value rejects the connection |
 | `failOnStartupError` | `false` | Reject plugin activation when the initial connection or tool synchronization fails |
 | `reconnect.enabled` | `true` | Reconnect automatically after a lost connection |
 | `reconnect.initialDelayMs` | `500` | First reconnect delay; doubles per consecutive failed attempt |
@@ -67,7 +68,7 @@ Add one entry per server; nothing else is required. After the harness starts, th
 
 The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-mcp-client) is the exhaustive source for every accepted field.
 
-After startup, the server's tools appear as `mcp__<serverName>__<tool>` — try a prompt that uses one. If the initial connection fails, the harness still starts but no tools from that server appear, and an error is logged; set `failOnStartupError: true` to make a startup failure abort the harness instead.
+After startup, the server's tools appear as `mcp__<serverName>__<tool>` — try a prompt that uses one. If the initial connection fails, the harness still starts but no tools from that server appear, and an error is logged. Setting `failOnStartupError: true` rejects plugin activation; [app-boot's startup policy](../../boot/app-boot/README.md) still permits an optional MCP entry to fail without aborting the harness.
 
 ### Tool naming and coexistence
 
@@ -76,7 +77,7 @@ The model sees each tool under a stable server-qualified name: `mcp__<serverName
 - Two servers publishing the same tool name (for example `search`) coexist under their own namespaces.
 - Two entries using the same server name: the later one fails to load with a clear error.
 - A server that lists the same tool twice gets its tool list rejected as invalid, and the previous tool set stays active.
-- A repeated non-empty `tools/list` continuation cursor rejects that update immediately, including cycles through empty pages; the previous tool set stays active and later updates can still succeed.
+- The SDK owns discovery pagination and its page limit. A discovery failure preserves the previous tools; malformed cursor chains follow the SDK's behavior.
 - An update that conflicts with an already-registered tool name is rejected entirely — you never get a partial tool set from that server.
 
 ### Calling tools and reading results
@@ -115,19 +116,22 @@ This section explains the design decisions behind the bridge and points at the c
 |---|---|
 | [`src/index.ts`](src/index.ts) | Plugin entry: `Config` schema, `serverName` reservation, activation await |
 | [`src/connection.ts`](src/connection.ts) | Connection supervisor: client generations, reconnect policy, attempt budget, disposal |
+| [`src/server-context.ts`](src/server-context.ts) | Resource-provider registration and literal server instructions |
 | [`src/tools.ts`](src/tools.ts) | Tool bridge: discovery, naming, registration swap, execution, image projection |
 | [`src/transport.ts`](src/transport.ts) | Transport factory: stdio spawn with scrubbed env, Streamable HTTP |
 | — | No runtime invariant companion is published; MCP generations contribute through the tool registry, but the bridge exposes no independent server-to-tool snapshot after an asynchronous resync. |
 
+The exported `createMcpToolDefinition(ctx, options)` adapts an upstream tool schema and raw-result callback to the same canonical values, errors, and durable image projection. Each callback receives the exact `ToolExecution`, including its Agent and cancellation signal; SDK spec-type validation checks its result before projection. Callers own registration, cancellation deadlines, and provider teardown. The native Cua Driver provider uses this adapter without opening an MCP transport.
+
 ### Lifecycle and sync
 
-`apply` resolves the reconnect policy, reserves the `serverName` inside the current registration scope, starts the supervisor, and awaits the initial connection plus discovery. Independent Agent scopes may reuse the same namespace because their tools and transports are isolated; a duplicate inside one scope fails at load. The supervisor serializes every sync — initial, notification, and reconnect — through one queue so two syncs can never interleave their dispose-previous/register-next swap. Disposal cancels pending reconnects, closes the live client, waits for the in-flight attempt and queued syncs to quiesce, and unregisters the current generation.
+`apply` resolves the reconnect policy, reserves the `serverName` inside the current registration scope, starts the supervisor, and awaits the initial connection plus discovery. Independent Agent scopes may reuse the same namespace because their tools and transports are isolated; a duplicate inside one scope fails at load. The supervisor serializes every sync — initial, notification, and reconnect — through one queue so two syncs can never interleave their dispose-previous/register-next swap. Disposal cancels pending reconnects, closes the negotiating transport or attached client, waits for the in-flight attempt and queued syncs to quiesce, and unregisters the current generation.
 
-The supervisor listens for `notifications/tools/list_changed` and queues a re-sync; a fetch-phase failure keeps the previous generation registered, while a registration conflict rolls back the attempted generation. Each outage shares one attempt budget: after `maxAttempts` consecutive failures the tools are unregistered and reconnection stops, and a connection that stays up past `maxDelayMs` resets the budget.
+The SDK receives tool-list changes through legacy notifications or a modern subscription. The supervisor queues each re-sync; a fetch failure keeps the previous generation registered, while a registration conflict rolls back the attempted generation. Each outage shares one attempt budget: after `maxAttempts` consecutive failures the tools are unregistered and reconnection stops, and a connection that stays up past `maxDelayMs` resets the budget.
 
 ### Tool execution internals
 
-A tool call sends an uncached `tools/call` request carrying the raw MCP name, the JSON arguments, the abort signal, and the configured timeout; the public name is never sent to the server and never parsed back. Canonical success is `{ content: JsonValue[], structuredContent? }`, preserving the complete MCP JSON blocks for programmatic and PTC mode callers. A supported advertised `outputSchema` validates `structuredContent`; unsupported schema vocabulary falls back to unconstrained `JsonValue`. An MCP `isError` result throws before any image persistence, so the registry produces a failed tool result. Image batches are decoded and validated as a whole before any member is saved; any refusal projects every image as diagnostic text.
+A tool call uses the SDK with the raw name, complete tool definition, JSON arguments, abort signal, and configured timeout. The SDK owns protocol validation, advertised output-schema validation, and modern request headers. Canonical success is `{ content: JsonValue[], structuredContent? }`, preserving valid MCP JSON blocks for programmatic and PTC mode callers. An MCP `isError` result throws before image persistence. The bridge validates each image batch before saving it; a refusal projects every image as diagnostic text.
 
 ### Environment scrubbing (stdio)
 
@@ -157,11 +161,11 @@ Read these pages when the package-level contract is not enough. They move from t
 
 #### What the model sees
 
-After initial discovery succeeds, every 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.
+After discovery succeeds, SDK-admitted MCP tools appear as native tools named `mcp__<serverName>__<rawName>` (or their deterministic normalized form), with the server description and input schema. A re-sync replaces the generation; disposal or an exhausted reconnect budget removes it. A server without the tools capability connects with an empty tool set.
 
 #### Token effect
 
-The tool descriptions and input schemas enter every request while the tools are registered; re-syncs replace rather than accumulate schemas, and the server-qualified name adds tokens to every tool definition and call.
+The tool descriptions and input schemas enter every request while the tools are registered; re-syncs replace rather than accumulate schemas, and the server-qualified name adds tokens to every tool definition and call. A configured client also enables the [shared resource tools and server-name prompt](../mcp-resources/README.md#model-experience).
 
 #### KV Cache effect
 
@@ -181,6 +185,20 @@ Arguments, mapped text, and durable image references are retained until compacti
 
 Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV-cache entries.
 
+### Server instructions
+
+#### What the model sees
+
+One server-labeled section contains the nonblank instructions returned by each successful connection. Absent or blank instructions add no prompt text. Braces remain literal. A replacement connection publishes its instructions only after discovery succeeds; disposal or exhausted recovery removes the section.
+
+#### Token effect
+
+Server instructions contribute text to model requests while their scoped section is active. Resource documents enter history only through explicit resource reads.
+
+#### KV Cache effect
+
+Unchanged instructions retain identical prompt text. Updated or removed instructions change the next assembled system message and its reusable prefix.
+
 ## Known Limitations and Deferred Work
 
 <a id="known-limitations-and-deferred-work"></a>
@@ -188,11 +206,11 @@ Append-only; newly visible content follows the reusable request prefix and does
 
 These limits describe what you cannot do with this plugin and when it needs operational attention. They are current package constraints, not a comparison with other MCP clients or a task backlog.
 
-- **Tools are the only bridged MCP capability** — Resources and Prompts have no harness consumer mechanism and are deferred.
-- **Startup and discovery timeouts are inherited from the MCP SDK** — the plugin exposes no connection or discovery timeout; each `initialize` and paginated `tools/list` request uses the SDK's 60-second request 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 through the SDK transport's own recovery, so an unreachable HTTP server is retried per call rather than respawned by the supervisor.
+- **Resources are read on demand** — shipped profiles provide the [shared resource service](../mcp-resources/README.md); resource subscriptions and MCP prompt templates are unsupported.
+- **Startup and discovery timeouts are inherited from the MCP SDK** — the plugin exposes no separate connection or discovery timeout. Negotiation and discovery use the SDK's 60-second request default; discovery also uses its page limit. Plugin unload closes the transport to interrupt pending startup requests before awaiting teardown.
+- **Reconnect handles failed negotiation and transport close** — a failed initial probe or crashed stdio child uses the configured reconnect budget. Once HTTP is connected, request failures use the SDK transport's recovery rather than respawning the connection.
 - **Image is the only durable rich-result bridge** — PNG, JPEG, WebP, and GIF enter Native context after exact capability proof. Audio and embedded-resource payloads remain execution-local with explicit diagnostics, while resource links preserve only their name and URI as text.
-- **Unsupported MCP output schemas are not enforced** — `structuredContent` falls back to `JsonValue` when the advertised schema uses vocabulary outside the harness subset.
+- **Invalid protocol results or output schemas fail through the SDK** — the bridge does not accept legacy `toolResult` substitutes or bypass advertised schema validation.
 - **Task-required MCP tools are rejected at call time** — a tool that requires the task-based execution extension throws instead of bridging; the extension is not implemented.
 
 <a id="dev-note"></a>
@@ -204,9 +222,9 @@ These limits describe what you cannot do with this plugin and when it needs oper
 This Dev Note is working context for maintainers: open design questions and directions that are not decided. It is explicitly non-authoritative — shipped behavior, limits, and accepted rationale live in the sections above, the package code, and the linked Agent Notes.
 
 - The public-name algorithm is a v1 contract pinned by tests; changing it after release would break session history and permission rules.
-- An explicit DSH-owned connection and discovery timeout is an open direction; the SDK's 60-second default bounds startup and teardown.
+- An explicit DSH-owned connection and discovery timeout is an open direction; the SDK's 60-second default bounds startup requests.
 - Reconnect ownership for Streamable HTTP is open: per-request retry is SDK behavior, and the supervisor could also own the HTTP generation.
-- Bridging MCP Resources needs a harness-side injection decision (system prompt, on demand, or model-triggered); bridging Prompts needs a prompt-template concept the harness lacks.
+- MCP prompt templates need a separate user-selection and invocation mechanism.
 - The pinned MCP SDK is still evolving; a breaking upstream change requires updating the bridge.
 
 </details>

package/README.zh.md

@@ -9,7 +9,7 @@ kind: "package-reference"
 
 ## 概述
 
-`dsh-mcp-client` 让模型把外部 MCP（Model Context Protocol）服务器的工具当作 harness 原生工具调用。每台服务器配置一条记录，其工具便会以稳定名称出现，例如 `mcp__github__create_issue`。可将它用于文件系统、GitHub、数据库、记忆或其他 MCP 工具服务器；默认不启用任何服务器。工具定义会为每次模型请求增加 token；缓慢或崩溃的服务器可能延迟启动，或让工具调用失败直至恢复。本包只桥接工具；MCP resources 与 prompts 不受支持。
+`dsh-mcp-client` 让模型使用外部 MCP（Model Context Protocol）服务器的工具与资源。每台服务器配置一条记录；其工具使用 `mcp__github__create_issue` 这样的名称。默认不启用任何服务器。随附 profile 已提供[共享资源发现与读取](../mcp-resources/README.zh.md)。调用方作用域为空时，不添加 MCP 工具或提示词文本。服务器指令作为字面文本加入已记录的系统提示词；MCP 提示词模板不受支持。缓慢或崩溃的服务器可能延迟启动，或让调用失败直至恢复。
 
 ## 目录
 
@@ -25,7 +25,7 @@ kind: "package-reference"
 <a id="use-this-package"></a>
 ## 使用本包
 
-当模型需要把外部 MCP 服务器的工具当作原生工具调用时，添加 `dsh-mcp-client`。每台服务器一条配置项就是全部设置：给服务器一个简短的唯一名称和一种传输方式，它的工具就会以 `mcp__<serverName>__<tool>` 形式出现。服务器作为本地程序运行时选择 stdio，作为服务运行时选择 Streamable HTTP。如果你已经用其他客户端连接过 MCP 工具服务器，同样的配置行在这里也能用。
+当模型需要像调用原生工具一样调用外部 MCP 服务器时，添加 `dsh-mcp-client`。为每台服务器指定唯一名称和传输方式。官方 SDK 优先选择可用的 2026-07-28 协议，并回退到支持的旧版协议。本地程序使用 stdio，远端服务使用 Streamable HTTP；stdio 协商会先启动临时探测进程，再启动实际服务进程。
 
 ### 最小配置
 
@@ -58,16 +58,17 @@ kind: "package-reference"
 | `serverName` | 必填 | 服务器工具名称的 namespace；`[A-Za-z0-9_-]{1,32}`，在一个注册作用域内唯一 |
 | `command` / `args` / `env` / `cwd` | — | stdio：可执行文件、参数、合并到清洗过的环境之上的额外环境变量、工作目录 |
 | `url` / `headers` | — | streamable-http：端点 URL 与额外请求标头 |
-| `toolCallTimeoutMs` | `60,000` | 每次 `tools/call` 调用的超时 |
+| `toolCallTimeoutMs` | `60,000` | 每次 `tools/call` 或资源请求的超时 |
+| `maxInstructionBytes` | `32,768` | 包括服务器归属信息在内的服务器指令 UTF-8 字节上限；超出时连接失败 |
 | `failOnStartupError` | `false` | 初始连接或工具同步失败时拒绝插件激活 |
 | `reconnect.enabled` | `true` | 连接丢失后自动重新连接 |
 | `reconnect.initialDelayMs` | `500` | 首次重连延迟；每次连续失败尝试翻倍 |
 | `reconnect.maxDelayMs` | `30,000` | 退避上限；同时是重置尝试预算所需的正常运行时长 |
 | `reconnect.maxAttempts` | `10` | 每次中断内连续失败尝试次数上限，超出后放弃 |
 
-生成的[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-mcp-client)是每个受支持字段及其 JSDoc 的穷尽式真源。
+生成的[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-mcp-client)是每个受支持字段的穷尽式真源。
 
-启动后，服务器的工具会以 `mcp__<serverName>__<tool>` 形式出现——试着用一条提示词调用其中一个。如果初始连接失败，harness 仍会启动，但该服务器的工具不会出现，并会记录一条错误；设置 `failOnStartupError: true` 可让启动失败改为中止 harness。
+启动后，服务器的工具会以 `mcp__<serverName>__<tool>` 形式出现——试着用一条提示词调用其中一个。如果初始连接失败，harness 仍会启动，但该服务器的工具不会出现，并会记录一条错误。设置 `failOnStartupError: true` 会拒绝插件激活；[app-boot 的启动策略](../../boot/app-boot/README.zh.md)仍允许可选 MCP 配置项失败，而不中止 harness。
 
 ### 工具命名与共存
 
@@ -76,7 +77,7 @@ kind: "package-reference"
 - 发布相同工具名称（例如 `search`）的两个服务器会在各自的 namespace 下共存。
 - 两条配置项使用相同的服务器名称时，后加载的一条会在加载时以明确错误失败。
 - 服务器在工具列表中两次列出同一工具时，其工具列表会被作为无效列表拒绝，上一组工具保持可用。
-- `tools/list` 返回重复的非空续传游标时会立即拒绝本次更新，包括经过空页的循环；上一组工具保持可用，后续更新仍可成功。
+- SDK 负责发现分页及页数上限。发现失败会保留之前的工具；格式错误的游标链遵循 SDK 的处理行为。
 - 工具更新与已有工具名称冲突时，该更新会被整体拒绝——绝不会得到该服务器的部分工具集。
 
 ### 调用工具与读取结果
@@ -104,7 +105,7 @@ kind: "package-reference"
 ### 设计理念
 
 - **服务器限定身份。** 每个 MCP 工具都有稳定的身份 `(serverName, rawName)`。namespace 是本地配置，绝不采用远程 `serverInfo.name`——远程名称不可信、在部署间不唯一、且升级时可能变化，这些都不允许静默重命名面向模型的工具。
-- **命名是固定约定。** 公开名称是 `(serverName, rawName)` 的纯函数，并满足 DeepSeek 函数名称约定；有损规范化会追加 12 位十六进制 SHA-256 hash，使不同身份绝不会折叠。会话历史与权限规则因此能在 HMR 替换、重新同步和其他服务器变化后保持有效。
+- **命名是固定约定。** 公开名称是 `(serverName, rawName)` 的纯函数，并满足 DeepSeek 函数名称约定；有损规范化会追加 12 位十六进制 SHA-256 hash，使不同身份绝不会折叠。会话历史与权限规则因此能在 HMR（热模块替换）、重新同步和其他服务器变化后保持有效。
 - **原始名称是唯一的协议名称。** `tools/call` 始终收到原始名称；公开名称绝不会发给服务器，也绝不会被解析来还原原始名称。
 - **要么完整世代，要么没有。** 同步会原子地交换世代：获取失败保留上一世代，注册冲突则回滚整个尝试中的世代。
 - **一个规范值，一个投影。** 执行器返回协议完整的规范 `McpResult`；另一个有序投影准备 Native 内容，`finalizeContent` 只在注册表的执行后结果未变时安装它，因此策略块与值替换保持权威。
@@ -114,20 +115,23 @@ kind: "package-reference"
 | 文件 | 职责 |
 |---|---|
 | [`src/index.ts`](src/index.ts) | 插件入口：`Config` schema、`serverName` 预留、激活等待 |
-| [`src/connection.ts`](src/connection.ts) | 连接监督器：客户端世代、重连策略、尝试预算、dispose |
+| [`src/connection.ts`](src/connection.ts) | 连接监督器：客户端世代、重连策略、尝试预算、dispose（资源释放） |
+| [`src/server-context.ts`](src/server-context.ts) | 资源提供方注册与字面服务器指令 |
 | [`src/tools.ts`](src/tools.ts) | 工具桥接：发现、命名、注册交换、执行、图片投影 |
 | [`src/transport.ts`](src/transport.ts) | 传输工厂：带清洗环境的 stdio spawn、Streamable HTTP |
-| — | 不发布运行时不变式伴生入口；世代只能通过工具注册表观察。 |
+| — | 不发布运行时不变式伴生入口；MCP 世代会通过工具注册表发挥作用，但桥接在异步重新同步后不提供独立的服务器工具映射快照。 |
+
+导出的 `createMcpToolDefinition(ctx, options)` 将上游工具 schema 和原始结果回调适配到相同的规范值、错误和持久化图像投影。每次回调都收到原样的 `ToolExecution`，包括其 Agent 和取消信号；SDK 的规范类型校验会在投影前检查返回结果。调用方负责注册、取消截止时间和提供方卸载。原生 Cua Driver 提供方使用此适配函数，无需打开 MCP 传输。
 
 ### 生命周期与同步
 
-`apply` 解析重连策略、在当前注册作用域内预留 `serverName`、启动监督器，并等待初始连接加发现完成。独立 Agent 作用域可以复用相同 namespace，因为其工具与传输彼此隔离；同一作用域内重复会在加载时失败。监督器把所有同步——初始、通知与重连——串行到同一条队列，因此两次同步绝不会交错执行各自的先 dispose 后注册交换。dispose 会取消待执行的重连、关闭活动客户端、等待进行中的尝试与排队同步完全停稳，然后注销当前世代。
+`apply` 解析重连策略、在当前注册作用域内预留 `serverName`、启动监督器，并等待初始连接加发现完成。独立 agent（智能体）作用域可以复用相同 namespace，因为其工具与传输彼此隔离；同一作用域内重复会在加载时失败。监督器把所有同步——初始、通知与重连——串行到同一条队列，因此两次同步绝不会交错执行各自的先 dispose 后注册交换。dispose 会取消待执行的重连、关闭协商中的传输或已绑定的客户端、等待进行中的尝试与排队同步完全停稳，然后注销当前世代。
 
-监督器监听 `notifications/tools/list_changed` 并排队一次重新同步；获取阶段失败时保留上一世代注册，注册冲突则回滚本次尝试的世代。每次中断共享一个尝试预算：连续失败达到 `maxAttempts` 次后工具被注销、重连停止；连接存活超过 `maxDelayMs` 会重置预算。
+SDK 通过旧版通知或现代协议订阅接收工具列表变化。监督器将每次重新同步排队；获取失败时保留之前的注册代，注册冲突则回滚本次尝试。每次故障共享一个尝试预算：连续失败达到 `maxAttempts` 后注销工具并停止重连；连接持续超过 `maxDelayMs` 则重置预算。
 
 ### 工具执行内部细节
 
-工具调用会发送一次未缓存的 `tools/call` 请求，携带原始 MCP 名称、JSON 参数、中止信号与配置的超时；公开名称绝不会发给服务器，也绝不会被解析还原。规范成功值是 `{ content: JsonValue[], structuredContent? }`，为程序化调用方与 PTC mode 调用方保留完整的 MCP JSON 块。受支持且已声明的 `outputSchema` 会验证 `structuredContent`；不受支持的 schema 词汇回退为不受约束的 `JsonValue`。MCP 的 `isError` 结果会在任何图片持久化之前抛出，使注册表产生失败的工具结果。图片批次会先整体解码并校验，再保存任一成员；任何拒绝都会把每张图片投影为诊断文本。
+工具调用向 SDK 提供原始名称、完整工具定义、JSON 参数、取消信号及配置的超时。SDK 负责协议校验、已声明输出 schema 的校验和现代协议请求 header。成功结果规范值为 `{ content: JsonValue[], structuredContent? }`，为编程调用方及 PTC 模式保留有效的 MCP JSON 块。MCP `isError` 结果会在图片持久化前抛出。桥接器在保存前校验整批图片；拒绝时将每张图片投影为诊断文本。
 
 ### 环境清洗（stdio）
 
@@ -157,11 +161,11 @@ kind: "package-reference"
 
 #### 模型看到什么
 
-初始发现成功后，每个已声明的 MCP 工具都会显示为名为 `mcp__<serverName>__<rawName>`（或其确定性规范化形式）的原生工具，并携带服务器提供的描述与输入 schema。成功的重新同步——包括自动重连后的同步——会替换整个世代；对插件执行 dispose（资源释放）或重连预算耗尽会移除该世代。
+发现成功后，SDK 接受的 MCP 工具以原生工具名称 `mcp__<serverName>__<rawName>`（或其确定性规范化形式）出现，携带服务器描述和输入 schema。重新同步会替换注册代；释放或重连预算耗尽会移除工具。未声明 tools 能力的服务器以空工具集连接。
 
 #### Token 影响
 
-工具注册期间，工具描述与输入 schema 会进入每次请求；重新同步会替换而非累积 schema，服务器限定名称也会为每个工具定义和调用增加 token。
+工具注册期间，工具描述与输入 schema 会进入每次请求；重新同步会替换而非累积 schema，服务器限定名称也会为每个工具定义和调用增加 token。已配置客户端还会启用[共享资源工具与服务器名称提示词](../mcp-resources/README.zh.md#model-experience)。
 
 #### KV Cache 影响
 
@@ -171,7 +175,7 @@ kind: "package-reference"
 
 #### 模型看到什么
 
-公开工具名称和 JSON 参数保留在 assistant 历史中。规范值始终为程序化调用方与 PTC mode 调用方保留完整的 MCP JSON 块与可选结构化内容；受支持的图片块在确切路由能力得到证明后，按原始顺序与文本一起投影。被拒绝的图片、音频、嵌入资源、资源链接与未知块继续以有界文本诊断可见；MCP `isError` 会在图片持久化之前拒绝调用。
+公开工具名称和 JSON 参数保留在 assistant 历史中。规范值始终为程序化调用方与 PTC 模式调用方保留完整的 MCP JSON 块与可选结构化内容；受支持的图片块在确切路由能力得到证明后，按原始顺序与文本一起投影。被拒绝的图片、音频、嵌入资源、资源链接与未知块继续以有界文本诊断可见；MCP `isError` 会在图片持久化之前拒绝调用。
 
 #### Token 影响
 
@@ -181,6 +185,20 @@ kind: "package-reference"
 
 仅追加；新可见内容位于可复用请求前缀之后，不会使现有 KV-cache 条目失效。
 
+### 服务器指令
+
+#### 模型看到什么
+
+每个成功连接返回的非空白指令保存在一个带服务器名称的段落中。未返回指令或指令仅含空白时，不向提示词添加文本。花括号保持字面值。替代连接仅在发现成功后发布其指令；释放或耗尽恢复预算时移除该段落。
+
+#### Token 影响
+
+作用域段落生效期间，服务器指令为模型请求贡献文本。资源文档仅通过显式资源读取进入历史。
+
+#### KV Cache 影响
+
+未变化的指令保留相同提示词文本。更新或移除指令会改变下一次组装的系统消息及其可复用前缀。
+
 ## 已知限制与延期工作
 
 <a id="known-limitations-and-deferred-work"></a>
@@ -188,11 +206,11 @@ kind: "package-reference"
 
 这些限制说明你无法用本插件做什么、以及何时需要运维注意。它们是当前包约束，不是与其他 MCP 客户端的对比，也不是任务积压。
 
-- **只桥接 MCP 的工具能力**——Resources 与 Prompts 没有 harness 消费机制，暂缓实现。
-- **启动与发现超时继承自 MCP SDK**——插件不暴露连接或发现超时；每次 `initialize` 与分页 `tools/list` 请求都使用 SDK 默认的 60 秒请求超时，因此无响应的服务器或 cursor chain 在初始同步完成期间可能同时延迟激活与 teardown。
-- **重连在传输关闭时触发**——崩溃的 stdio 子进程会触发重连；Streamable HTTP 失败按请求经 SDK 传输自身的恢复机制暴露，因此不可达的 HTTP 服务器会按调用重试，而非由 supervisor 重新 spawn。
+- **资源按需读取**——随附 profile 提供[共享资源服务](../mcp-resources/README.zh.md)；资源订阅与 MCP 提示词模板不受支持。
+- **启动与发现超时继承自 MCP SDK**——插件不暴露单独的连接或发现超时。协商与发现使用 SDK 默认的 60 秒请求超时；发现也使用 SDK 的页数上限。插件卸载先关闭传输以中断待处理的启动请求，再等待清理。
+- **重连处理协商失败与传输关闭**——初始探测失败或 stdio 子进程崩溃都会使用配置的重连预算。HTTP 建立连接后，请求失败使用 SDK 传输的恢复机制，而非重新创建连接。
 - **图片是唯一的持久丰富结果桥接**——PNG、JPEG、WebP 与 GIF 在确切能力得到证明后进入 Native 上下文。音频与嵌入资源载荷仍只存在于执行局部并带明确诊断，资源链接只以文本保留名称与 URI。
-- **不强制执行不受支持的 MCP 输出 schema**——已声明 schema 使用 harness 子集之外的词汇时，`structuredContent` 回退为 `JsonValue`。
+- **无效的协议结果或输出 schema 由 SDK 拒绝**——桥接器不接受旧式 `toolResult` 替代结果，也不绕过已声明的 schema 校验。
 - **要求基于任务的 MCP 工具在调用时被拒绝**——要求使用基于任务的执行（task-based execution）扩展的工具会抛出异常而非被桥接；该扩展未实现。
 
 <a id="dev-note"></a>
@@ -204,9 +222,9 @@ kind: "package-reference"
 本开发备注是维护者的工作上下文：开放设计问题与尚未决定的探索方向。它明确不具权威性——已交付行为、限制与既定理由以上文、包代码与所链接的 Agent Note 为准。
 
 - 公开名称算法是由测试固定的 v1 约定；发布后更改会破坏会话历史与权限规则。
-- 由 DSH 显式拥有的连接与发现超时是开放的探索方向；SDK 的 60 秒默认值约束着启动与 teardown。
+- 由 DSH 显式拥有的连接与发现超时是开放的探索方向；SDK 的 60 秒默认值约束着启动请求。
 - Streamable HTTP 的重连归属仍未决定：按请求重试是 SDK 行为，supervisor 也可以拥有 HTTP 世代。
-- 桥接 MCP Resources 需要 harness 侧的注入决策（系统提示词、按需或模型触发）；桥接 Prompts 需要 harness 缺少的提示词模板概念。
+- MCP 提示词模板需要独立的用户选择和模板调用机制。
 - 固定的 MCP SDK 仍在演化；上游破坏性变更需要更新桥接。
 
 </details>

package/lib/index.js

@@ -1,14 +1,12 @@
 import z from "@deepseek-ai/schemastery";
 import { scopeOf } from "@deepseek-ai/dsh-scope";
 import { MAX_TIMER_DELAY_MS } from "@deepseek-ai/dsh-timeout";
-import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { ListToolsResultSchema, ToolListChangedNotificationSchema } from "@modelcontextprotocol/sdk/types.js";
-import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
-import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { Client, StreamableHTTPClientTransport, specTypeSchemas } from "@modelcontextprotocol/client";
+import { assertNever } from "@deepseek-ai/dsh-util-values";
+import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";
 import { scrubbedParentEnv } from "@deepseek-ai/dsh-subprocess";
 import { createHash } from "node:crypto";
 import { isDeepStrictEqual } from "node:util";
-import { z as z$1 } from "zod";
 import { isImageAdmissionError } from "@deepseek-ai/dsh-attachment";
 import { assertSupportedJsonSchema } from "@deepseek-ai/dsh-tools";
 //#region lib/types/transport.js
@@ -72,8 +70,6 @@ const MAX_PUBLIC_NAME_LENGTH = 64;
 const INVALID_NAME_CHARS = /[^A-Za-z0-9_-]/g;
 /** Hex chars of the SHA-256 identity hash appended on lossy normalization. */
 const HASH_LENGTH = 12;
-/** Raw result record: the bridge owns JSON-value validation after transport. */
-const RawCallToolResultSchema = z$1.record(z$1.string(), z$1.unknown());
 /** Raster formats supported by the durable attachment vocabulary. */
 const IMAGE_MEDIA_TYPES = [
 	"image/png",
@@ -83,26 +79,6 @@ const IMAGE_MEDIA_TYPES = [
 ];
 /** Canonical RFC 4648 base64, excluding whitespace and URL-safe aliases. */
 const CANONICAL_BASE64 = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
-/** List without mutating the SDK's per-page output-validator cache. */
-function listToolsUncached(client, cursor) {
-	return client.request({
-		method: "tools/list",
-		...cursor === void 0 ? {} : { params: { cursor } }
-	}, ListToolsResultSchema);
-}
-/** Call without the SDK pre-validating an output schema the bridge may not support. */
-function callToolUncached(client, rawName, args, exec, opts) {
-	return client.request({
-		method: "tools/call",
-		params: {
-			name: rawName,
-			arguments: args
-		}
-	}, RawCallToolResultSchema, {
-		signal: exec.signal,
-		timeout: opts.toolCallTimeoutMs
-	});
-}
 /**
 * Derive the model-facing public name for one MCP tool.
 *
@@ -129,9 +105,9 @@ function publicToolName(serverName, rawName) {
 *
 * Two phases keep the swap safe:
 *
-* 1. Fetch: drain uncached `tools/list` pagination and build the full next
+* 1. Fetch: let the SDK aggregate `tools/list` and build the full next
 *    generation of `ToolDefinition`s under public names. Any failure here
-*    (network error, duplicate raw name, repeated continuation cursor) rejects
+*    (network error or duplicate raw name) rejects
 *    and leaves the previous generation registered untouched.
 * 2. Swap: dispose the previous generation, register the new one. A registry
 *    conflict here can only mean a foreign registration squats on this
@@ -150,21 +126,27 @@ function publicToolName(serverName, rawName) {
 */
 async function syncTools(client, ctx, opts, previous) {
 	const definitions = /* @__PURE__ */ new Map();
-	const seenCursors = /* @__PURE__ */ new Set();
-	let cursor;
-	do {
-		const response = await listToolsUncached(client, cursor);
-		for (const tool of response.tools) {
-			const publicName = publicToolName(opts.serverName, tool.name);
-			if (definitions.has(publicName)) throw new Error(`mcp-client(${opts.serverName}): server listed tool "${tool.name}" more than once — invalid tool list`);
-			definitions.set(publicName, createDefinition(client, ctx, publicName, tool.name, tool.description ?? "", tool.inputSchema, supportedOutputSchema(tool.outputSchema), tool.execution?.taskSupport === "required", opts));
-		}
-		cursor = response.nextCursor;
-		if (cursor) {
-			if (seenCursors.has(cursor)) throw new Error(`mcp-client(${opts.serverName}): server repeated a tools/list continuation cursor — invalid tool list`);
-			seenCursors.add(cursor);
-		}
-	} while (cursor);
+	const response = client.getServerCapabilities()?.tools === void 0 ? { tools: [] } : await client.listTools(void 0, { cacheMode: "refresh" });
+	for (const tool of response.tools) {
+		const publicName = publicToolName(opts.serverName, tool.name);
+		if (definitions.has(publicName)) throw new Error(`mcp-client(${opts.serverName}): server listed tool "${tool.name}" more than once — invalid tool list`);
+		definitions.set(publicName, createMcpToolDefinition(ctx, {
+			name: publicName,
+			rawName: tool.name,
+			description: tool.description ?? "",
+			inputSchema: tool.inputSchema,
+			outputSchema: tool.outputSchema,
+			taskRequired: tool.execution?.taskSupport === "required",
+			call: (args, execution) => client.callTool({
+				name: tool.name,
+				arguments: args
+			}, {
+				signal: execution.signal,
+				timeout: opts.toolCallTimeoutMs,
+				toolDefinition: tool
+			})
+		}));
+	}
 	for (const dispose of previous.values()) dispose();
 	const disposers = /* @__PURE__ */ new Map();
 	try {
@@ -188,26 +170,21 @@ function supportedOutputSchema(candidate) {
 	}
 }
 /**
-* Build one generation-local tool definition and its execution-local rich projections.
-* @param client - connected MCP client used for calls.
+* Adapt an upstream MCP tool to canonical values and durable image content.
+* Registration, provider lifetime, deadlines, and transport belong to the caller.
 * @param ctx - plugin context carrying optional attachment and model services.
-* @param publicName - registry-qualified public tool name.
-* @param rawName - MCP wire tool name.
-* @param description - model-facing tool description.
-* @param parameters - MCP input schema.
-* @param structuredSchema - supported structured-output schema, when advertised.
-* @param taskRequired - whether this MCP tool requires unsupported task execution.
-* @param opts - bridge timeout and namespace options.
-* @returns a complete ToolRuntime definition.
+* @param options - upstream tool fields and its raw-result callback.
+* @returns the unregistered ToolRuntime definition.
 */
-function createDefinition(client, ctx, publicName, rawName, description, parameters, structuredSchema, taskRequired, opts) {
+function createMcpToolDefinition(ctx, options) {
+	const { name, rawName, description, inputSchema } = options;
 	const projections = /* @__PURE__ */ new WeakMap();
 	return {
-		name: publicName,
+		name,
 		description,
-		parameters,
-		output: createOutput(rawName, structuredSchema),
-		execute: createExecutor(client, ctx, rawName, taskRequired, opts, projections),
+		parameters: inputSchema,
+		output: createOutput(rawName, supportedOutputSchema(options.outputSchema)),
+		execute: createExecutor(ctx, options, projections),
 		finalizeContent(exec, result) {
 			const projection = projections.get(exec);
 			if (projection === void 0) return void 0;
@@ -243,31 +220,17 @@ function createOutput(rawName, structuredSchema) {
 	};
 }
 /**
-* Create an execute function for one MCP tool. The executor closes over the
-* raw MCP tool name and sends an uncached `tools/call` request with it (never
-* the public name), with abort signal and timeout, then maps the result to
-* harness ContentBlocks. Owning the raw request prevents the SDK's internal
-* per-page schema cache from pre-validating a different contract.
-*
-* When the MCP server returns `isError: true`, the executor throws so that
-* the ToolRuntime's catch path produces an `isError` result for the model.
+* Invoke the caller-owned raw-result callback and prepare canonical content.
+* MCP isError results reject before image storage so ToolRuntime records failure.
 */
-function createExecutor(client, ctx, rawName, taskRequired, opts, projections) {
+function createExecutor(ctx, options, projections) {
+	const { rawName, taskRequired } = options;
 	return async (args, exec) => {
 		if (taskRequired) throw new Error(`Tool "${rawName}" requires task-based execution, which this bridge does not support`);
-		const result = await callToolUncached(client, rawName, typeof args === "object" && args !== null ? args : {}, exec, opts);
-		if (!Array.isArray(result.content)) {
-			const rendered = "toolResult" in result ? JSON.stringify(result.toolResult) : "(no output)";
-			const text = typeof rendered === "string" ? rendered : "(no output)";
-			if (result.isError === true) throw new Error(text);
-			return {
-				content: [{
-					type: "text",
-					text
-				}],
-				...result.structuredContent !== void 0 ? { structuredContent: result.structuredContent } : {}
-			};
-		}
+		const argsObj = typeof args === "object" && args !== null ? args : {};
+		const parsed = specTypeSchemas.CallToolResult["~standard"].validate(await options.call(argsObj, exec));
+		if (parsed.issues !== void 0) throw new Error(`Tool "${rawName}" returned an invalid MCP result: ${parsed.issues.map((issue) => issue.message).join("; ")}`);
+		const result = parsed.value;
 		const content = result.content;
 		const text = extractText(content, rawName);
 		if (result.isError === true) throw new Error(text);
@@ -302,10 +265,10 @@ function isRecord(value) {
 function isImageMediaType(value) {
 	return IMAGE_MEDIA_TYPES.includes(value);
 }
-/** Decode one untrusted MCP image block without accepting base64 aliases. */
+/** Decode one projected image without accepting base64 aliases. */
 function decodeImage(block) {
-	if (block.mimeType === void 0 || !isImageMediaType(block.mimeType)) throw new Error("the declared media type is not PNG, JPEG, WebP, or GIF");
-	if (block.data === void 0 || !CANONICAL_BASE64.test(block.data)) throw new Error("the image data is not canonical base64");
+	if (!isImageMediaType(block.mimeType)) throw new Error("the declared media type is not PNG, JPEG, WebP, or GIF");
+	if (!CANONICAL_BASE64.test(block.data)) throw new Error("the image data is not canonical base64");
 	const data = Buffer.from(block.data, "base64");
 	if (data.toString("base64") !== block.data) throw new Error("the image data is not canonical base64");
 	return {
@@ -393,8 +356,7 @@ async function prepareImageProjection(ctx, exec, content, toolName) {
 * - text blocks: join with '\n'
 * - image/audio/resource blocks: replaced with a placeholder
 *
-* Defensive: fields that the MCP spec declares required (mimeType, text) are
-* guarded with fallbacks because this is a network trust boundary.
+* Policy-owned canonical-value replacements may omit fields required on the MCP wire.
 */
 function extractText(mcpContent, toolName) {
 	return projectContent(mcpContent, toolName).map((block) => block.text).join("\n");
@@ -475,6 +437,8 @@ const RECONNECT_DEFAULTS = Object.freeze({
 	maxDelayMs: 3e4,
 	maxAttempts: 10
 });
+/** Default UTF-8 byte limit for attributed server instructions. */
+const DEFAULT_MAX_INSTRUCTION_BYTES = 32768;
 const GENERATION_CLOSE_TIMEOUT_MS = 5e3;
 /**
 * The one explicit resolve step from raw reconnect config to the policy the
@@ -516,6 +480,7 @@ function resolveReconnectPolicy(config, path) {
 */
 function startConnection(ctx, config, policy) {
 	const label = `mcp-client(${config.serverName})`;
+	const incompleteDisposalMessage = `${label}: transport closure could not be confirmed during disposal — server shutdown may be incomplete`;
 	const opts = {
 		registrationFailure: "contain",
 		serverName: config.serverName,
@@ -526,10 +491,12 @@ function startConnection(ctx, config, policy) {
 		registrationFailure: "throw"
 	} : opts;
 	let disposed = false;
+	const maxInstructionBytes = config.maxInstructionBytes ?? 32768;
+	let serverInstructions = "";
 	/** Current generation: the connecting or connected client; undefined during backoff waits and after final failure. */
 	let client;
-	/** Close signal paired with {@link client}; captured by dispose before current ownership is cleared. */
-	let clientClosed;
+	/** Transport-aware close operation paired with {@link client}. */
+	let closeClient;
 	/** Live tool registrations owned by this server; only {@link enqueueSync} and dispose swap it. */
 	let disposers = /* @__PURE__ */ new Map();
 	let reconnectTimer;
@@ -560,9 +527,20 @@ function startConnection(ctx, config, policy) {
 	function generationDown(generation) {
 		if (!isCurrent(generation)) return;
 		client = void 0;
-		clientClosed = void 0;
+		closeClient = void 0;
 		scheduleReconnect();
 	}
+	/** Decide retry ownership after a failed connection's close barrier settles. */
+	function settleFailedGeneration(generation, quiesced) {
+		if (!isCurrent(generation)) return;
+		if (!quiesced) {
+			client = void 0;
+			closeClient = void 0;
+			ctx.logger.error(`${label}: failed generation could not confirm transport closure — reconnect stopped to avoid overlapping server processes; reload the plugin or restart the Host to retry`);
+			return;
+		}
+		generationDown(generation);
+	}
 	/** Wait for the transport-owned close signal without letting a broken transport wedge teardown forever. */
 	function waitForClose(closed) {
 		return new Promise((resolve) => {
@@ -590,6 +568,7 @@ function startConnection(ctx, config, policy) {
 			syncChain = syncChain.then(() => {
 				for (const dispose of disposers.values()) dispose();
 				disposers = /* @__PURE__ */ new Map();
+				serverInstructions = "";
 			});
 			ctx.logger.error(`${label}: giving up after ${policy.maxAttempts} consecutive failed reconnect attempts — tools unregistered; reload the plugin or restart the Host to reconnect`);
 			return;
@@ -617,19 +596,40 @@ function startConnection(ctx, config, policy) {
 		const generation = new Client({
 			name: "dsh-mcp-client",
 			version: "0.0.1"
-		}, { capabilities: {} });
+		}, {
+			capabilities: {},
+			versionNegotiation: { mode: "auto" },
+			listChanged: { tools: {
+				autoRefresh: false,
+				debounceMs: 0,
+				onChanged: () => {
+					refreshTools();
+				}
+			} }
+		});
 		const closed = Promise.withResolvers();
 		let attemptSettled = false;
 		let closeObserved = false;
+		let transport;
 		const hasClosed = () => closeObserved;
 		client = generation;
-		clientClosed = closed.promise;
+		closeClient = closeGeneration;
 		generation.onclose = () => {
 			closeObserved = true;
 			closed.resolve();
 			if (attemptSettled) generationDown(generation);
 		};
-		generation.setNotificationHandler(ToolListChangedNotificationSchema, async () => {
+		/** Unattached probes close through their transport; attached clients must also report transport closure. */
+		async function closeGeneration() {
+			const attached = generation.transport !== void 0;
+			try {
+				await (attached ? generation.close() : transport?.close());
+			} catch (_error) {
+				if (!attached) return hasClosed();
+			}
+			return !attached || hasClosed() || await waitForClose(closed.promise);
+		}
+		async function refreshTools() {
 			if (!isCurrent(generation)) return;
 			ctx.logger.info(`${label}: tool list changed, re-syncing`);
 			try {
@@ -637,31 +637,30 @@ function startConnection(ctx, config, policy) {
 			} catch (error) {
 				if (!disposed) ctx.logger.error(`${label}: tool re-sync failed: ${String(error)}`);
 			}
-		});
+		}
+		let instructions;
 		try {
-			await generation.connect(createTransport(config));
+			transport = createTransport(config);
+			await generation.connect(transport);
 			if (hasClosed()) {
 				attemptSettled = true;
 				generationDown(generation);
 				return;
 			}
+			if (!isCurrent(generation)) {
+				if (!await closeGeneration()) ctx.logger.error(incompleteDisposalMessage);
+				return;
+			}
+			const serverText = generation.getInstructions()?.trimEnd() ?? "";
+			instructions = serverText ? `### MCP server: ${config.serverName}\n\n${serverText}` : "";
+			if (Buffer.byteLength(instructions) > maxInstructionBytes) throw new Error(`${label}: server instructions exceed maxInstructionBytes (${maxInstructionBytes})`);
 			await enqueueSync(generation, startup ? startupOpts : opts);
 		} catch (error) {
 			if (firstAttemptError === void 0) firstAttemptError = error;
 			if (isCurrent(generation)) ctx.logger.warn(`${label}: connection attempt failed: ${String(error)}`);
-			try {
-				await generation.close();
-			} catch {}
-			const quiesced = hasClosed() || await waitForClose(closed.promise);
+			const quiesced = await closeGeneration();
 			attemptSettled = true;
-			if (!isCurrent(generation)) return;
-			if (!quiesced) {
-				client = void 0;
-				clientClosed = void 0;
-				ctx.logger.error(`${label}: failed generation did not close within ${GENERATION_CLOSE_TIMEOUT_MS}ms — reconnect stopped to avoid overlapping server processes; reload the plugin or restart the Host to retry`);
-				return;
-			}
-			generationDown(generation);
+			settleFailedGeneration(generation, quiesced);
 			return;
 		}
 		attemptSettled = true;
@@ -670,6 +669,7 @@ function startConnection(ctx, config, policy) {
 			return;
 		}
 		if (!isCurrent(generation)) return;
+		serverInstructions = instructions;
 		connectedAt = Date.now();
 		if (failedAttempts > 0) ctx.logger.info(`${label}: reconnected and re-synced tools (attempt ${failedAttempts}/${policy.maxAttempts})`);
 	}
@@ -681,22 +681,33 @@ function startConnection(ctx, config, policy) {
 			/* v8 ignore next -- defensive: firstAttemptError is always set when connect/sync fails */
 			return { error: firstAttemptError ?? /* @__PURE__ */ new Error(`${label}: initial connection failed`) };
 		}),
+		instructions: () => serverInstructions,
+		resources: { async request(request, exec) {
+			const generation = client;
+			if (!generation || connectedAt === void 0) throw new Error(`${label}: server is disconnected`);
+			const options = {
+				signal: exec.signal,
+				timeout: config.toolCallTimeoutMs
+			};
+			switch (request.method) {
+				case "resources/list": return await generation.listResources(request.cursor === void 0 ? void 0 : { cursor: request.cursor }, options);
+				case "resources/templates/list": return await generation.listResourceTemplates(request.cursor === void 0 ? void 0 : { cursor: request.cursor }, options);
+				case "resources/read": return await generation.readResource({ uri: request.uri }, options);
+				/* v8 ignore next 2 -- resource requests are the closed, typed tool operation union */
+				default: return assertNever(request);
+			}
+		} },
 		async dispose() {
 			disposed = true;
+			serverInstructions = "";
 			if (reconnectTimer !== void 0) {
 				clearTimeout(reconnectTimer);
 				reconnectTimer = void 0;
 			}
-			const current = client;
-			const currentClosed = clientClosed;
+			const close = closeClient;
 			client = void 0;
-			clientClosed = void 0;
-			if (current !== void 0) {
-				try {
-					await current.close();
-				} catch {}
-				if (currentClosed !== void 0 && !await waitForClose(currentClosed)) ctx.logger.error(`${label}: generation did not close within ${GENERATION_CLOSE_TIMEOUT_MS}ms during disposal — server shutdown may be incomplete`);
-			}
+			closeClient = void 0;
+			if (close !== void 0 && !await close()) ctx.logger.error(incompleteDisposalMessage);
 			await settling;
 			await syncChain;
 			for (const dispose of disposers.values()) dispose();
@@ -705,6 +716,32 @@ function startConnection(ctx, config, policy) {
 	};
 }
 //#endregion
+//#region lib/types/server-context.js
+/**
+* Publish connection-owned MCP resources and literal server instructions.
+*
+* @module @deepseek-ai/dsh-mcp-client
+*/
+/**
+* Contribute server context to the services enabled by this composition.
+* @param ctx - server plugin's registration scope and effect owner.
+* @param server - configured server identity.
+* @param connection - live resource operations and successful instruction snapshot.
+*/
+function registerServerContext(ctx, server, connection) {
+	ctx.inject(["mcpResources"], (inner) => {
+		inner.mcpResources.register(server, connection.resources);
+	});
+	ctx.inject(["systemPrompt"], (inner) => {
+		inner.systemPrompt.section({
+			name: `mcp:${server}`,
+			order: inner.systemPrompt.getSectionOrder("MCP_SERVERS"),
+			interpolate: false,
+			text: () => connection.instructions()
+		});
+	});
+}
+//#endregion
 //#region lib/types/index.js
 /**
 * MCP client bridge plugin: connects to an external MCP server and registers
@@ -724,7 +761,7 @@ function startConnection(ctx, config, policy) {
 const name = "mcp-client";
 /** Services required by this plugin. */
 const inject = ["tools"];
-/** Default timeout for individual MCP tool calls (ms). */
+/** Default timeout for individual MCP tool calls and resource requests (ms). */
 const DEFAULT_TOOL_CALL_TIMEOUT_MS = 6e4;
 /** Valid `serverName`, kept below the public tool-name budget. */
 const SERVER_NAME_PATTERN = /^[A-Za-z0-9_-]{1,32}$/;
@@ -749,6 +786,7 @@ const Config = z.union([z.object({
 	cwd: z.string().default(""),
 	toolCallTimeoutMs: z.number().default(DEFAULT_TOOL_CALL_TIMEOUT_MS),
 	failOnStartupError: z.boolean().default(false),
+	maxInstructionBytes: z.number().step(1).min(1).default(DEFAULT_MAX_INSTRUCTION_BYTES),
 	reconnect: Reconnect
 }), z.object({
 	transport: z.const("streamable-http"),
@@ -757,6 +795,7 @@ const Config = z.union([z.object({
 	headers: z.dict(String).default({}),
 	toolCallTimeoutMs: z.number().default(DEFAULT_TOOL_CALL_TIMEOUT_MS),
 	failOnStartupError: z.boolean().default(false),
+	maxInstructionBytes: z.number().step(1).min(1).default(DEFAULT_MAX_INSTRUCTION_BYTES),
 	reconnect: Reconnect
 })]);
 /**
@@ -781,11 +820,16 @@ async function apply(ctx, config) {
 		return () => void names.delete(config.serverName);
 	}, "mcp-client.serverName");
 	const connection = startConnection(ctx, config, reconnect);
-	ctx.effect(() => {
-		return () => connection.dispose();
-	}, "mcp-client.connection");
+	registerServerContext(ctx, config.serverName, connection);
+	let stopping;
+	const dispose = () => stopping ??= connection.dispose();
+	ctx.on("internal/plugin", (fiber) => {
+		if (fiber !== ctx.fiber || fiber.uid !== null) return;
+		return dispose();
+	}, { global: true });
+	ctx.effect(() => dispose, "mcp-client.connection");
 	const outcome = await connection.ready;
 	if (outcome.error !== void 0 && config.failOnStartupError) throw new Error(`mcp-client(${config.serverName}): initial connection or tool synchronization failed`, { cause: outcome.error });
 }
 //#endregion
-export { Config, apply, inject, name };
+export { Config, apply, createMcpToolDefinition, inject, name };

package/lib/types/connection.d.ts

@@ -15,6 +15,7 @@
  * @module
  */
 import type { Context } from '@deepseek-ai/cordis';
+import type { ServerContext } from './server-context.ts';
 import type { Config } from './index.ts';
 /** Automatic reconnect policy for one MCP server connection. */
 export interface ReconnectConfig {
@@ -29,6 +30,8 @@ export interface ReconnectConfig {
 }
 /** Defaults shared by the Config schema and {@link resolveReconnectPolicy}. */
 export declare const RECONNECT_DEFAULTS: Required<ReconnectConfig>;
+/** Default UTF-8 byte limit for attributed server instructions. */
+export declare const DEFAULT_MAX_INSTRUCTION_BYTES = 32768;
 /** Fully resolved reconnect policy captured at plugin load. */
 export type ResolvedReconnectPolicy = Readonly<Required<ReconnectConfig>>;
 /**
@@ -48,7 +51,7 @@ export interface ConnectionOutcome {
     error?: unknown;
 }
 /** Handle for one plugin instance's supervised connection. */
-export interface ConnectionHandle {
+export interface ConnectionHandle extends ServerContext {
     /**
      * Settles when the first connection attempt completes (success or failure).
      * The supervisor enters its reconnect loop regardless; the caller decides
@@ -56,9 +59,9 @@ export interface ConnectionHandle {
      */
     ready: Promise<ConnectionOutcome>;
     /**
-     * Stop reconnection, close the live client, wait for the in-flight attempt
-     * and queued tool syncs to quiesce, then unregister every tool this server
-     * still owns.
+     * Stop reconnection, close the negotiating transport or live client, wait
+     * for the in-flight attempt and queued tool syncs to quiesce, then
+     * unregister every tool this server still owns.
      */
     dispose(): Promise<void>;
 }

package/lib/types/index.d.ts

@@ -15,7 +15,8 @@
 import type { Context } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
 import type { ReconnectConfig } from './connection.ts';
-export type { McpResult } from './tools.ts';
+export { createMcpToolDefinition } from './tools.ts';
+export type { McpResult, McpToolDefinitionOptions } from './tools.ts';
 export type { ReconnectConfig, ResolvedReconnectPolicy } from './connection.ts';
 /** Cordis plugin name used by loader diagnostics. */
 export declare const name = "mcp-client";
@@ -39,10 +40,12 @@ export interface StdioConfig {
     env: Record<string, string>;
     /** Working directory for the child process. */
     cwd: string;
-    /** Per-tool-call timeout in milliseconds. */
+    /** Timeout per tool call or resource request in milliseconds. */
     toolCallTimeoutMs: number;
     /** Fail plugin activation when the initial connection or tool synchronization fails. */
     failOnStartupError: boolean;
+    /** Maximum UTF-8 bytes of attributed server instructions (default 32768). */
+    maxInstructionBytes?: number;
     /** Automatic reconnect policy after a lost connection; omission uses the defaults. */
     reconnect?: ReconnectConfig;
 }
@@ -60,10 +63,12 @@ export interface StreamableHttpConfig {
     url: string;
     /** Additional headers attached to MCP requests. */
     headers: Record<string, string>;
-    /** Per-tool-call timeout in milliseconds. */
+    /** Timeout per tool call or resource request in milliseconds. */
     toolCallTimeoutMs: number;
     /** Fail plugin activation when the initial connection or tool synchronization fails. */
     failOnStartupError: boolean;
+    /** Maximum UTF-8 bytes of attributed server instructions (default 32768). */
+    maxInstructionBytes?: number;
     /** Automatic reconnect policy after a lost connection; omission uses the defaults. */
     reconnect?: ReconnectConfig;
 }

package/lib/types/server-context.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Publish connection-owned MCP resources and literal server instructions.
+ *
+ * @module @deepseek-ai/dsh-mcp-client
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { McpResourceProvider } from '@deepseek-ai/dsh-mcp-resources';
+/** Connection-owned values used by the resource and prompt consumers. */
+export interface ServerContext {
+    /** Resource access through the current connection generation. */
+    resources: McpResourceProvider;
+    /**
+     * Read the last successfully connected server's attributed instructions.
+     * @returns literal prompt text, or an empty string when no server instructions are active.
+     */
+    instructions(): string;
+}
+/**
+ * Contribute server context to the services enabled by this composition.
+ * @param ctx - server plugin's registration scope and effect owner.
+ * @param server - configured server identity.
+ * @param connection - live resource operations and successful instruction snapshot.
+ */
+export declare function registerServerContext(ctx: Context, server: string, connection: ServerContext): void;
+//# sourceMappingURL=server-context.d.ts.map

package/lib/types/tools.d.ts

@@ -11,8 +11,9 @@
  *
  * @module
  */
-import type { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { type Client } from '@modelcontextprotocol/client';
 import type { Context } from '@deepseek-ai/cordis';
+import type { ToolDefinition, ToolExecution } from '@deepseek-ai/dsh-tools';
 import type { JsonValue } from '@deepseek-ai/dsh-util-values';
 /** Resolved options relevant to tool bridging. */
 export interface ToolBridgeOptions {
@@ -48,9 +49,9 @@ export declare function publicToolName(serverName: string, rawName: string): str
  *
  * Two phases keep the swap safe:
  *
- * 1. Fetch: drain uncached `tools/list` pagination and build the full next
+ * 1. Fetch: let the SDK aggregate `tools/list` and build the full next
  *    generation of `ToolDefinition`s under public names. Any failure here
- *    (network error, duplicate raw name, repeated continuation cursor) rejects
+ *    (network error or duplicate raw name) rejects
  *    and leaves the previous generation registered untouched.
  * 2. Swap: dispose the previous generation, register the new one. A registry
  *    conflict here can only mean a foreign registration squats on this
@@ -68,4 +69,34 @@ export declare function publicToolName(serverName: string, rawName: string): str
  *   disposers — the exact set of live registrations owned by this server.
  */
 export declare function syncTools(client: Client, ctx: Context, opts: ToolBridgeOptions, previous: ToolDisposers): Promise<ToolDisposers>;
+/** One upstream MCP tool and the callback that obtains its raw protocol result. */
+export interface McpToolDefinitionOptions {
+    /** ToolRuntime name presented to the model. */
+    name: string;
+    /** Upstream name used in result diagnostics. */
+    rawName: string;
+    /** Upstream model-facing description. */
+    description: string;
+    /** Upstream JSON input schema. */
+    inputSchema: Record<string, unknown>;
+    /** Advertised structured output schema, when present. */
+    outputSchema?: unknown;
+    /** Whether the upstream tool requires the unsupported task execution extension. */
+    taskRequired?: boolean;
+    /**
+     * Obtain one raw MCP result from the provider.
+     * @param args - model arguments admitted by the ToolRuntime.
+     * @param execution - exact ToolRuntime invocation, including its Agent and cancellation.
+     * @returns the external result object, validated before content projection.
+     */
+    call(args: Record<string, unknown>, execution: ToolExecution): Promise<unknown>;
+}
+/**
+ * Adapt an upstream MCP tool to canonical values and durable image content.
+ * Registration, provider lifetime, deadlines, and transport belong to the caller.
+ * @param ctx - plugin context carrying optional attachment and model services.
+ * @param options - upstream tool fields and its raw-result callback.
+ * @returns the unregistered ToolRuntime definition.
+ */
+export declare function createMcpToolDefinition(ctx: Context, options: McpToolDefinitionOptions): ToolDefinition;
 //# sourceMappingURL=tools.d.ts.map

package/lib/types/transport.d.ts

@@ -5,7 +5,7 @@
  *
  * @module
  */
-import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import type { Transport } from '@modelcontextprotocol/client';
 import type { Config } from './index.ts';
 /**
  * Create an MCP transport from the resolved plugin config.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-mcp-client",
   "description": "MCP client bridge: connects to MCP servers and registers their tools on ctx.tools",
-  "version": "0.1.5-rc.2",
+  "version": "0.1.6-alpha.2",
   "publishConfig": {
     "access": "public"
   },
@@ -27,30 +27,45 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/dsh-attachment": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-llm": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-scope": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-subprocess": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-timeout": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-tools": "^0.1.5-rc.2",
+    "@deepseek-ai/dsh-scope": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-attachment": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-llm": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-timeout": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-subprocess": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-tools": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-mcp-resources": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-system-prompt": "^0.1.6-alpha.2",
     "@deepseek-ai/cordis": "^4.0.2"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.12.0",
-    "zod": "^4.4.3",
-    "@deepseek-ai/schemastery": "^3.18.2"
+    "@modelcontextprotocol/client": "2.0.0",
+    "@deepseek-ai/schemastery": "^3.18.2",
+    "@deepseek-ai/dsh-util-values": "^0.1.6-alpha.2"
   },
   "devDependencies": {
     "@modelcontextprotocol/server-everything": "^2026.7.4",
     "@modelcontextprotocol/server-filesystem": "^2026.7.4",
-    "@deepseek-ai/dsh-attachment": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-llm": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-scope": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-subprocess": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-attachment-local": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-timeout": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-tools": "^0.1.5-rc.2",
+    "@modelcontextprotocol/server": "2.0.0",
+    "@modelcontextprotocol/node": "2.0.0",
+    "zod": "^4.4.3",
+    "@deepseek-ai/dsh-attachment": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-attachment-local": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-llm": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-scope": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-timeout": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-tools": "^0.1.6-alpha.2",
     "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-http-proxy": "^0.1.5-rc.2"
+    "@deepseek-ai/dsh-http-proxy": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-mcp-resources": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-system-prompt": "^0.1.6-alpha.2",
+    "@deepseek-ai/dsh-subprocess": "^0.1.6-alpha.2"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/dsh-mcp-resources": {
+      "optional": true
+    },
+    "@deepseek-ai/dsh-system-prompt": {
+      "optional": true
+    }
   }
 }