MCP client rejects content-only tool results (missing structuredContent) - breaks interop with servers declaring structured_output=false (e.g. OpenViking 0.4.17.1)

[buddha68]

Summary (EN)

dsh 0.1.2-rc.1's MCP client rejects tool results that contain only content blocks without structuredContent, even when the server explicitly declared structured_output=false for that tool (i.e. no outputSchema). This breaks interop with MCP servers whose tools legitimately return unstructured text/media output — allowed by the MCP spec, where structuredContent is optional.

环境 / Environment

• dsh: 0.1.2-rc.1（npm 全通道最新，next tag；Windows 11）
• 对端 / peer: OpenViking 0.4.17.1（PyPI 最新正式版；Volcengine 开源的 MCP 上下文数据库服务器，监听 127.0.0.1:1933，streamable HTTP）

症状 / Symptom

调用 OpenViking 提供的 MCP 工具 read 时，dsh 侧直接拒收结果：

Error: tool "mcp__openviking__read" returned invalid output: missing required property "value.structuredContent"

同一服务器的 search / list / write 等工具（返回结构化结果）校验通过，只有 read 失败。

服务端证据 / Server-side evidence

OpenViking 0.4.17.1 的 openviking/server/mcp_endpoint.py 第 501 行起：

@mcp.tool(structured_output=False)
async def read(uris: str | list[str]) -> str | list[ContentBlock]:

0.4.17 起 OpenViking 的 read 工具改为返回纯文本 / 媒体 content block（配合 MCP 原生媒体返回特性），并显式声明 structured_output=False——即不声明 outputSchema、按 MCP 规范合法地只返回 content。已核对上游 main 分支（1,480 行版本）该处一致，即官方尚未调整。

分析 / Analysis

• 按 MCP 规范，CallToolResult 的 structuredContent 是可选字段；工具未声明 outputSchema 时，客户端不应要求它。
• dsh 的 MCP 客户端在结果校验时似乎无条件要求 structuredContent（报错路径 value.structuredContent），导致任何合法返回 content-only 的服务器工具都会被拒。
• 双方均已处于各自最新发布版本（dsh 0.1.2-rc.1 为全通道最新；OpenViking 0.4.17.1 为最新稳定版），升级无法绕过，属于两侧互操作适配问题。

复现 / Repro

1. Windows 上 uv tool install "openviking[bot]==0.4.17.1"，启动 openviking-server --with-bot（127.0.0.1:1933）
2. dsh 挂接该 OpenViking MCP 端点
3. 调用工具 read，参数如 {"uris": "viking://user/<uid>/memories/profile.md"}
4. dsh 报上方错误；同一读取走 HTTP API / CLI（ov read）正常；search/list/write 正常

期望行为 / Expected behavior

工具未声明 outputSchema 时，客户端应接受仅含 content 的结果，不强制要求 structuredContent（MCP 规范行为）。

建议修复 / Suggested fix

放宽 dsh MCP 结果校验：仅当工具声明了 outputSchema 时才要求 structuredContent；否则接受 content-only 结果。

本地临时绕过 / Local workaround

改用 ov read CLI 或 MCP search（自带 read_content 全文返回）；OpenViking 的自动记忆召回/会话捕获走 HTTP API 直连，不受影响。

[buddha68]

Correction & root cause refinement (verified by restart test)

In the original post I wrote that the dsh MCP client "unconditionally requires structuredContent". That was inaccurate — after reading the source and running a controlled restart test, the actual failure chain is more nuanced, and neither side's current code is wrong:

1. dsh's validation is two-state, not unconditional (dsh-mcp-client/lib/index.js ~L229):

required: structuredSchema === void 0 ? ["content"] : ["content", "structuredContent"]

The client only requires structuredContent when the server actually broadcasts an outputSchema for that tool. That logic is correct.

2. What OpenViking changed between 0.4.15 and 0.4.17.1: in 0.4.15, read was declared as @mcp.tool() with a -> str return annotation, so it did broadcast an outputSchema. In 0.4.17.1, read became @mcp.tool(structured_output=False) (pure content blocks, to support native media returns) and no longer broadcasts outputSchema — verified by connecting directly with the MCP SDK and listing tools.

3. The actual trigger: a stale tool manifest cached by a long-lived client session. The client session's MCP bridge registered before the server upgrade, so it was still holding the 0.4.15-era tool manifest (in which read declared outputSchema). After the server upgrade, read responses changed shape (content-only), but the bridge never re-fetched tools/list — it validated the new response against the old manifest → missing required property "value.structuredContent" → rejection.

4. Verified fix: restart the client (or open a fresh session). After restarting dsh, the bridge re-registered with a fresh tools/list, only requires content, and read works again — zero patches needed. Confirmed on dsh + OpenViking 0.4.17.1.

TL;DR for anyone hitting this: if an MCP tool starts being rejected with missing required property "structuredContent" right after a server upgrade, restart the client first — a stale cached tool manifest from before the upgrade is the likely culprit. Only if a fresh session still fails is an actual client bug indicated.

Apologies for the imprecise framing in the original post — closing the loop here so the thread carries accurate information.

[Junaid-PK]

This looks like a stale discovered schema across the OpenViking upgrade, rather than 0.1.2-rc.1 unconditionally requiring structuredContent.

The guard proposed above is already in the exact rc.1 tag (and in the published npm artifact): the registered result schema requires only content when tool.outputSchema is absent, and requires structuredContent only when a supported outputSchema was discovered (source). That agrees with the MCP specification: outputSchema and structuredContent are optional; when a tool advertises an output schema, the server must return conforming structured content (spec).

There is a version transition that explains the exact error:

• OpenViking 0.4.16 registered read as plain @mcp.tool() returning str (source). FastMCP therefore advertised an outputSchema for { "result": string }.
• OpenViking 0.4.17+ changed it to @mcp.tool(structured_output=False) and a content-block-capable return (source), so current discovery correctly omits outputSchema.

If dsh discovered the 0.4.16 definition, then OpenViking was upgraded/restarted while dsh remained alive, the old registered definition can still validate the new content-only result. That produces exactly missing required property "value.structuredContent". This is especially plausible for Streamable HTTP: dsh documents that HTTP request recovery does not itself cause the connection supervisor to rebuild the tool generation (current limitation).

Try this order once:

1. Fully stop dsh.

2. Start OpenViking 0.4.17.1.

3. Confirm the wire definition:

   npx -y @modelcontextprotocol/inspector@latest --cli http://127.0.0.1:1933/mcp --transport http --method tools/list

   The read entry should have no outputSchema. Add the same --header "Name: Value" arguments as the dsh connection if your endpoint uses identity/auth headers.

4. Start dsh again (alternatively, edit/reload that MCP configuration entry so it performs a fresh tools/list).

If it still fails after a clean restart, the two most useful diagnostics are the Inspector's complete read object and:

where.exe dsh
dsh --version
npm ls -g --all @deepseek-ai/dsh-mcp-client @modelcontextprotocol/sdk

That will distinguish an unexpected wire outputSchema from a mixed/stale global install. If the Inspector shows no schema and those versions are the rc.1 set, then there is a second path registering the wrong definition and the report has enough evidence to narrow it further.

[buddha68]

@Junaid-PK Apologies for the late reply — and thank you: your diagnosis is correct, and it matches our environment exactly.

Timeline on our side: OpenViking was upgraded 0.4.16 → 0.4.17.1 while the dsh process stayed alive. The session opened before the upgrade kept the stale 0.4.16-discovered tool definition (with the advertised outputSchema), so content-only read results were rejected with missing required property "value.structuredContent". After fully restarting dsh — a fresh tools/list against 0.4.17.1 — read works normally, verified on 2026-09-04.

So: no unconditional structuredContent requirement in rc.1 — it was exactly the stale-discovered-schema transition you described. Your four-step verification procedure also matches what we did in practice. Thanks for the precise analysis and the source links — closing the loop here so the report reflects the confirmed root cause.