mcp-client: one unsupported tool inputSchema keyword rejects the entire MCP server (Playwright MCP registers zero tools)

[astread777-collab]

Summary

When an MCP server advertises even one tool whose inputSchema uses a JSON Schema keyword outside the enforced subset, dsh-mcp-client ends up registering zero tools from that server. The all-or-nothing swap in syncTools rolls back the whole generation because a single schema fails assertSupportedJsonSchema.

In practice this makes Playwright MCP completely unusable through DSH: every one of its 26 tool schemas carries "inputSchema": { "$schema": "https://json-schema.org/draft/2020-12/schema", ... }, so the entire browser server is dropped. Sessions then have no mcp__browser__* tools at all, and agents typically fall back to launching their own headless Chromium from bash — which sites such as Google risk-block — producing confusing downstream failures that look like an IP or login problem instead of a tool-registration one.

Reproduction

1. Install and start Playwright MCP (streamable HTTP):

   npm i -g @playwright/mcp@0.0.81
   playwright-mcp --cdp-endpoint http://127.0.0.1:9223 --port 8935

2. Add this to a profile cordis.patch.yml:

   - insert:
     - id: mcp-browser
       name: '@deepseek-ai/dsh-mcp-client'
       config:
         serverName: browser
         transport: streamable-http
         url: http://127.0.0.1:8935/mcp

3. Start a new DSH session → no mcp__browser__* tools exist in the tool catalog (verified on 0.1.5-rc.2 and 0.1.6-alpha.2; other streamable-http servers in the same profile register fine).
4. The server itself is healthy — a direct MCP handshake works:

   POST /mcp initialize → HTTP 200, mcp-session-id header,
   result.serverInfo = { name: "Playwright", version: "1.64.0-alpha-2026-09-14" }
   tools/list → 26 tools
   

Current behavior

Running assertSupportedJsonSchema (from @deepseek-ai/dsh-tools) against each of the 26 Playwright MCP tool schemas:

FAIL: browser_navigate — unsupported JSON schema: schema.$schema is not a supported keyword
     (subset: type/oneOf/properties/required/additionalProperties/items/enum/const + annotations)
... all 26 tools fail on `$schema`; additionally:
FAIL: browser_drop           — schema.properties.data.propertyNames is not a supported keyword;
                               schema.properties.data.additionalProperties must be a boolean
FAIL: browser_network_request — schema.properties.index.minimum / .maximum are not supported keywords

In packages/mcp/mcp-client/src/tools.ts, syncTools builds the full next generation in phase 1 and registers it in phase 2. The ToolRuntime registration validates parameters against the enforced subset; when one tool's schema throws, the catch block disposes everything already registered for that server:

mcp-client(browser): tool registration failed, no tools registered: ...

Result: zero tools from the server — not 25 of 26. The only trace is a single error log line; the session otherwise looks healthy.

Note the asymmetry in the same file: supportedOutputSchema() already degrades gracefully for unsupported output schemas (try/catch → undefined fallback), while an unsupported input schema takes down the whole server.

Expected behavior

One tool with an out-of-subset schema should not disable an entire MCP server. Suggested options, in order of preference:

1. Sanitize at the MCP boundary: strip keywords outside the enforced subset from incoming tool inputSchemas (they are advisory to the model anyway; the subset engine cannot validate them) and log a warning per affected tool. This preserves the full server and keeps registration total.
2. Degrade per tool: register the tools with supported schemas, skip the offenders with a logged warning — instead of the all-or-nothing rollback.
3. At minimum, accept $schema as an annotation (it is a pure annotation in JSON Schema 2020-12) — though this alone would not fix Playwright MCP (propertyNames, minimum/maximum, object-valued additionalProperties would still fail).

Environment

• DSH 0.1.5-rc.2 (npm) and 0.1.6-alpha.2 / master ddefc45fbc — same code path in packages/mcp/mcp-client/src/tools.ts
• Linux x86_64, Node v22.23.2 / v24.19.0
• @playwright/mcp 0.0.81 (server "Playwright" 1.64.0-alpha-2026-09-14), streamable-http transport

Workaround (running in production)

A stdio proxy in front of the HTTP server that sanitizes tools/list schemas to the supported subset and forwards everything else verbatim. Wired into DSH as a transport: stdio entry pointing at the script below; verified end-to-end (all 26 tools registered, real browsing works). ~180 lines, pure Node, zero dependencies:

browser-bridge.mjs

#!/usr/bin/env node
/**
 * browser-bridge — stdio MCP proxy in front of a local streamable-http MCP server.
 * Strips unsupported keywords from tools/list inputSchemas (DSH enforced subset:
 * type/oneOf/properties/required/additionalProperties/items/enum/const + annotations
 * description/title/default/examples; additionalProperties coerced to boolean).
 */
const UPSTREAM = process.env.BROWSER_BRIDGE_UPSTREAM ?? 'http://127.0.0.1:8935/mcp';
const SERVER_INFO = { name: 'browser-bridge', version: '1.0.0' };

const STRUCTURAL = new Set(['type', 'oneOf', 'properties', 'required', 'additionalProperties', 'items', 'enum', 'const']);
const ANNOTATIONS = new Set(['description', 'title', 'default', 'examples']);

function sanitize(node) {
  if (Array.isArray(node)) return node.map(sanitize);
  if (node && typeof node === 'object') {
    const out = {};
    for (const [k, v] of Object.entries(node)) {
      if (!STRUCTURAL.has(k) && !ANNOTATIONS.has(k)) continue; // drop $schema, minimum, maximum, propertyNames, ...
      if (k === 'properties' && v && typeof v === 'object' && !Array.isArray(v)) {
        const props = {};
        for (const [pk, pv] of Object.entries(v)) props[pk] = sanitize(pv);
        out[k] = props;
      } else if (k === 'additionalProperties' && v !== undefined && typeof v !== 'boolean') {
        out[k] = true; // object-valued additionalProperties → "anything allowed"
      } else {
        out[k] = sanitize(v);
      }
    }
    return out;
  }
  return node;
}

let sessionId = null;
let initializing = null;

async function post(body, withSession = true) {
  const headers = { 'Content-Type': 'application/json', 'Accept': 'application/json, text/event-stream' };
  if (withSession && sessionId) headers['mcp-session-id'] = sessionId;
  const res = await fetch(UPSTREAM, { method: 'POST', headers, body: JSON.stringify(body) });
  const sid = res.headers.get('mcp-session-id');
  if (sid) sessionId = sid;
  if (!res.ok) throw new Error(`upstream HTTP ${res.status}: ${(await res.text().catch(() => '')).slice(0, 200)}`);
  return await res.text();
}

function parseBody(text) {
  const trimmed = text.trim();
  if (trimmed === '') return [];
  if (trimmed.startsWith('{')) return [JSON.parse(trimmed)];
  const out = [];
  for (const line of trimmed.split('\n')) {
    if (line.startsWith('data:')) {
      try { out.push(JSON.parse(line.slice(5).trim())); } catch { /* keep-alive/comment */ }
    }
  }
  return out;
}

async function ensureSession() {
  if (sessionId) return;
  if (!initializing) {
    initializing = (async () => {
      sessionId = null;
      await post({ jsonrpc: '2.0', id: 1, method: 'initialize',
        params: { protocolVersion: '2025-03-26', capabilities: {}, clientInfo: SERVER_INFO } }, false);
      await post({ jsonrpc: '2.0', method: 'notifications/initialized' }).catch(() => {});
    })().finally(() => { initializing = null; });
  }
  await initializing;
}

async function upstreamCall(method, params, id) {
  for (let attempt = 0; attempt < 2; attempt++) {
    try {
      await ensureSession();
      const text = await post({ jsonrpc: '2.0', id, method, params });
      const msgs = parseBody(text).filter((m) => m && (m.id === id || m.method));
      const resp = msgs.find((m) => m.id === id);
      if (!resp) throw new Error(`no response for id ${id} in upstream reply`);
      return resp;
    } catch (err) {
      if (attempt === 0 && /session|404|HTTP 5/i.test(String(err.message))) { sessionId = null; continue; }
      throw err;
    }
  }
}

function send(message) { process.stdout.write(JSON.stringify(message) + '\n'); }
function reply(id, result) { send({ jsonrpc: '2.0', id, result }); }
function replyError(id, code, message) { send({ jsonrpc: '2.0', id, error: { code, message } }); }

async function handle(request) {
  const { id, method, params } = request;
  switch (method) {
    case 'initialize':
      reply(id, { protocolVersion: params?.protocolVersion ?? '2025-03-26', capabilities: { tools: {} }, serverInfo: SERVER_INFO });
      return;
    case 'ping':
      reply(id, {});
      return;
    case 'tools/list': {
      const resp = await upstreamCall('tools/list', {}, id ?? 1);
      if (resp.error) throw new Error(resp.error.message ?? 'upstream tools/list error');
      const tools = (resp.result?.tools ?? []).map((t) => ({ ...t, inputSchema: sanitize(t.inputSchema ?? { type: 'object' }) }));
      reply(id, { tools });
      return;
    }
    case 'tools/call': {
      let resp;
      try {
        resp = await upstreamCall('tools/call', params, id ?? 1);
      } catch (err) {
        const msg = String(err?.message ?? err);
        if (/fetch failed|ECONNREFUSED|HTTP 5\d\d/i.test(msg)) {
          reply(id, { content: [{ type: 'text', text: `Upstream MCP server not reachable: ${msg}` }], isError: true });
        } else {
          replyError(id, -32603, msg);
        }
        return;
      }
      if (resp.error) throw new Error(resp.error.message ?? 'upstream tools/call error');
      reply(id, resp.result ?? { content: [{ type: 'text', text: '(empty result)' }] });
      return;
    }
    default:
      if (id !== undefined) replyError(id, -32601, `method not found: ${String(method)}`);
  }
}

process.stdin.setEncoding('utf8');
let buffer = '';
let stdinClosed = false;
let inFlight = 0;
function maybeExit() { if (stdinClosed && inFlight === 0) process.exit(0); }
process.stdin.on('data', (chunk) => {
  buffer += chunk;
  let idx;
  while ((idx = buffer.indexOf('\n')) >= 0) {
    const line = buffer.slice(0, idx).trim();
    buffer = buffer.slice(idx + 1);
    if (line === '') continue;
    let request;
    try { request = JSON.parse(line); } catch {
      send({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'parse error' } });
      continue;
    }
    if (request && typeof request === 'object' && request.jsonrpc === '2.0' && request.method) {
      inFlight++;
      handle(request)
        .catch((err) => { if (request.id !== undefined) replyError(request.id, -32603, `internal error: ${err?.message ?? String(err)}`); })
        .finally(() => { inFlight--; maybeExit(); });
    } else if (request && request.id !== undefined) {
      replyError(request.id, -32600, 'invalid request');
    }
  }
});
process.stdin.on('close', () => { stdinClosed = true; maybeExit(); });

Per CONTRIBUTING.md I understand external PRs are not currently accepted; on request I can share a working patch implementing option 1 (sanitize + warn in syncTools) or the full prototype above for internal use.

[PerryLink]

Confirmed, and one part of the mechanism is different in a way that matters for the fix.

$schema really is what kills it. assertSupportedJsonSchema walks every key of every node and accepts exactly two sets; anything else becomes a violation:

packages/core/tools/src/json-schema.ts:257   for (const key of Object.keys(node)) {
:258   if (CONSTRAINT_KEYWORDS.has(key)) continue
:259   if (ANNOTATION_KEYWORDS.has(key)) { ...lossless-JSON check...; continue }
:267   violations.push(`${path}.${key} is not a supported keyword (subset: type/oneOf/properties/required/additionalProperties/items/enum/const + annotations)`)

The enforced subset is the twelve fields of JsonSchemaNode (json-schema.ts:31-56): type, oneOf, properties, required, additionalProperties, items, enum, const, description, title, default, examples. $schema is none of them, and it is not an annotation, so every Playwright tool lands on :267. The resulting JsonSchemaError (:65-72) is thrown from assertSupportedJsonSchema(candidate) at packages/mcp/mcp-client/src/tools.ts:188, inside createMcpToolDefinition.

Where the all-or-nothing happens is the correction. It is not the swap phase. syncTools (tools.ts:113-162) has two phases, and the schema assertion runs in Phase 1 (:119-143), which builds the entire definition map before the registry is touched. A throw there means Phase 2 never runs:

• There is nothing to roll back, because nothing was registered yet. The rollback at :152-160 exists for a different failure - a conflicting registration in the mcp__<server>__ namespace - and its comment says so.
• On a re-sync, the previous generation is also not disposed (:146 is Phase 2), so an already-registered generation survives. The "zero tools" outcome is specifically the first sync, where no previous generation exists.

That distinction is what makes the cheap fix cheap: the failure is per-tool and happens before any registration, so skipping the offending tool - or degrading only its schema to the unconstrained node - is a local change inside the Phase 1 loop. No rollback machinery is involved, and no registry state needs unwinding.

One thing from your report worth repeating for whoever hits this next: the practical symptom is that every browser tool vanishes silently while the agent falls back to launching its own Chromium from bash, which reads as an authentication or IP problem rather than a tool-registration one. That misdirection is the expensive part of this bug, not the missing tools.

Boundary: read from the committed tree at c36a83ff6b (dsh-0.1.7-alpha.1). I did not run Playwright MCP against a live profile.

[mengge237]

这条缺陷在 0.2.0-rc.2 上仍然复现，而且能打死整台服务器的关键字不止 $schema 这一类。

版本：@deepseek-ai/dsh 0.2.0-rc.2、@deepseek-ai/dsh-tools 0.2.0-rc.2、@deepseek-ai/dsh-mcp-client 0.2.0-rc.2、@modelcontextprotocol/client 2.0.0（都在同一棵运行树上实测）。

病例：阿里云百炼 Harness 的 7 台 Streamable HTTP MCP 服务器，共 11 个工具。它们的工具 schema 长这样：

{"type":"object","properties":{"query":{"type":"string","minLength":1,"maxLength":500}},"required":["query"]}

把宿主自己的 assertSupportedJsonSchema 抠出来对同一批工具跑，4 个采样工具全部落在同一个违规点：

schema.properties.query.minLength is not a supported keyword
(subset: type/oneOf/properties/required/additionalProperties/items/enum/const + annotations)

$schema 不是必要条件，minLength/maxLength 这类标量约束同样能一条打死整台服务器。

离线复现（不需要 MCP 服务器，直接用宿主自己的校验函数）：

# <TREE> 指本机运行树里 @deepseek-ai/dsh 的目录；出厂形状回 rejected，降级之后回 accepted
DSH_TOOLS=<TREE>/../dsh-tools/lib/index.js node -e '
const t = require(process.env.DSH_TOOLS);
try { t.assertSupportedJsonSchema({ type:"object", properties:{ query:{ type:"string", minLength:1, maxLength:500 } }, required:["query"] }); console.log("accepted"); }
catch (e) { console.log("rejected:", e.message); }'
# 出厂形状（0.2.0-rc.2）实测输出：
# rejected: unsupported JSON schema: schema.properties.query.minLength is not a supported keyword
#   (subset: type/oneOf/properties/required/additionalProperties/items/enum/const + annotations);
#   schema.properties.query.maxLength is not a supported keyword (subset: ...)

这条链上多出来的误导：可见的错误不在注册侧，而在调用侧 —— list_mcp_resources 与工具调用回的是
mcp-client(<serverName>): server is disconnected（判据是 !generation || connectedAt === undefined）。
实际上连接是通的：用宿主自己的客户端包复跑，connect 与 listTools 都正常返回工具名；
失败发生在 Phase 1 建定义表那一步，但报出来的是"没连上"。按鉴权、按 URL、按代理各排查一轮都对得上，最后才落到注册侧。
这比"工具静默消失"又多偏一层，因为报错本身把人指向传输层。

就地降级这条路本机走过一遍：只在 Phase 1 降级该工具的 schema（把不支持的键剥掉而不是拒绝），
剥后 assertObjectJsonSchema、jsonSchemaToTs、jsonSchemaToPy 三条下游全部通过，4/4 工具注册成功。
一个顺带的观察：被剥掉的约束，厂商往往在 description 里重复了一遍（本例的 description 就写着"长度：>=1 and <=500"），
所以模型侧的信息并不会丢。

[vishalhabib99]

One thing nobody in this thread has said yet: the MCP spec explicitly allows this, so the server is sending valid tool schemas.

From the spec's JSON Schema usage section (2025-11-25):

• Schemas MAY include a $schema field to declare their dialect.
• With no $schema, the default is JSON Schema 2020-12. Clients MUST support 2020-12.
• Clients MUST handle unsupported dialects gracefully, by returning an error that says the dialect isn't supported.

So the server isn't at fault here: Playwright's $schema: .../draft/2020-12/schema declares the one dialect every client must support. minLength, maximum and propertyNames (from @mengge237's case and the original report) are ordinary 2020-12 keywords. Any schema-heavy server will hit this, not just Playwright.

On the fix, building on @PerryLink's point that the throw happens in Phase 1, before anything is registered:

1. Strip per tool and keep the constraint as text. Drop the keywords outside the subset, but add them to the property's description (for example "(min length 1, max 500)") so the model still sees them. As @mengge237 noticed, many servers already repeat them in the description. When they don't, this keeps the information.
2. Make the degradation visible. The costly part of this bug is the misdirection: tools vanish silently, or the client reports server is disconnected when the connection is fine. A single warning line per server would save people hours of chasing auth and proxies, something like browser: 26/26 tools registered, 26 schemas simplified ($schema, minimum, maximum, propertyNames).
3. Never fail the whole server on one tool. If a schema can't be simplified safely, skip that tool and name it in the same warning.

Until a fix lands, @astread777-collab's stdio bridge above is the working fix. Per @PerryLink's trace, the zero-tools result happens only on the first sync. A re-sync keeps the previous generation, which explains why it can look intermittent.

[PerryLink]

你引的规范条款把这条从"体验问题"变成"合规问题"——这一点很关键

1. 你引的三条我都收下，并把它们的要求明确到"必须"

你引 MCP 规范（2025-11-25 basic#json-schema-usage）：

• $schema MAY 出现（即服务端带上它是合法的）；
• 缺 $schema 时默认 JSON Schema 2020-12；
• 客户端 MUST 支持 2020-12；
• 客户端 MUST 优雅处理不支持的方言（返回指明方言不支持的报错）。

⇒ 关键在于最后一条是 MUST。于是本条的性质是：

服务端发的是合法 schema；客户端遇到它不支持的输入 schema 关键字时，不是"优雅处理"（说明是哪个关键字/方言不支持），而是把整个工具/整条链路拒掉。

建议把这一句放在报告最前面——"违反规范 MUST 条款"与"我认为应该更宽容"在优先级上完全不同。

2. 与 #8817 是同一族（建议互引）

我在另一条里核到：mcp-client/src/tools.ts:234 把 parameters: inputSchema 逐字透传（取出在 :135、解构在 :229），而输出侧有独立处理。⇒ 也就是说：

• 输入 schema 既不被校验、也不被规整、更不会被"优雅拒绝"；
• 它直接进模型看到的工具参数 ⇒ 在 PTC 下参数会渲染成 unknown（那条报告的结论）。

⇒ 两条合起来：输入 schema 这条路上缺少一层处理（该校验的没校验、该降级的没降级）。建议互引，并把它写成同一条原则——"不支持的 schema/关键字应当在工具装载期被判明并给出可读诊断，而不是静默劣化或整体拒绝"。

3. 线程标题的改动我注意到了（是改进）

这条的标题已从泛泛的表述改成 "mcp-client: one unsupported tool inputSchema keyword rej…"——指名了组件与症状。⇒ 这是好的改动，请把同样的精确度用到正文首段（一句话说清"哪个关键字、被拒的后果是什么"）。

4. 请补两样（让"必须优雅处理"这条可验收）

1. 是哪一个关键字（$schema？还是别的 2020-12 关键字）——规范要求"指明方言/关键字"，所以具体名字本身就是诉求的一部分；
2. 被拒的后果是哪一个：是该工具不可用、还是整台服务器的工具全部不可用？（你在原报告里写的是"能打死整台服务器"）⇒ 这个区别决定严重度，也是这条最重的地方。

5. 版本

请补版本（当前最新 0.2.1-alpha.1）。我核到 tools.ts:234 的逐字透传仍在 ⇒ 这条不需要等新版即可提交。

一条边界

我确认的是输入 schema 在 tools.ts:234 被原样透传（这一半），以及规范把"优雅处理不支持的方言"写成 MUST（引用你的链接）。"一个关键字打死整台服务器"这一后果以你们几位报告者的实测为准——我没有可复现的 MCP 服务器。

[mengge237]

规范那条我收下，顺序按你说的改：先把「客户端遇到不支持的输入 schema 关键字，规范要求的是优雅报错（指明关键字/方言），这里是整条链路拒掉」放在最前，再讲现象与复现。

版本补上，顺便钉成两版对照 —— 今天把两个版本的出厂 tarball 各解一份，用同一段 schema 各跑一次宿主自己的断言函数，命令是 npm pack @deepseek-ai/dsh-tools@<版本>，再对解出来的 lib/index.js 调 assertSupportedJsonSchema：

0.2.0-rc.2    rejected: schema.properties.query.minLength is not a supported keyword (...); schema.properties.query.maxLength is not a supported keyword (...)
0.2.1-alpha.1 rejected: 同一行报文，逐字相同

两版都拒，说明这条跨 0.2.0-rc.2 → 0.2.1-alpha.1 存活。你问的两样，我们这例的答案是：关键字是 minLength/maxLength（$schema 是另一条报告的引子），后果是整台服务器 —— 同一台 MCP 的 11 个工具全部注册为零，不是一个工具不可用；这两句 09-29 那条里已经给过，这里收成一句，方便直接贴进报告首段。

#8817 可以互引，输入侧那条我也在出厂产物上对了一眼：dsh-mcp-client@0.2.1-alpha.1 里 parameters: inputSchema 仍是逐字透传（构建件 lib/index.js:185），跟你在源码里核到的是同一处。边界说清：0.2.1-alpha.1 我只跑了出厂件里的断言函数，没装它跑真实宿主；「注册为零」这个后果是在 0.2.0-rc.2 上实测的。