* Tools: x-mcp-header annotation tooling + -32602 unknown-tool rendering (#1632) Card 9/10 of the SDK-v2 + New Spec stack. Adds SEP-2243 `x-mcp-header` tooling to the Tools tab and adjusts result rendering for SDK v2's unknown-tool behavior, and bumps the SDK to 2.0.0-beta.5. - **`core/json/xMcpHeader.ts`**: a faithful port of the SDK's (non-public) `scanXMcpHeaderDeclarations` — validates every SEP-2243 constraint (primitive types incl. `number`, RFC 9110 token, case-insensitive uniqueness, statically-reachable `properties`-only chain) and derives the mirrored `Mcp-Param-{Name}` params for a kept tool. - **Excluded tools**: the SDK silently drops tools with invalid annotations from `tools/list`. InspectorClient now re-lists the RAW (unfiltered) list and scans it to recompute the excluded set with reasons — gated to the modern non-stdio era (matching the SDK's gate), recomputed on every aggregate refresh, surfaced via a new `excludedToolsChange` event + `getExcludedTools()` and `useInspectorClient().excludedTools`. The Tools sidebar lists them struck-through under an "Excluded (SEP-2243)" divider with the reason on hover. - **Mirrored args**: ToolDetailPanel shows a "Mirrored request headers" section listing each arg → `Mcp-Param-{Name}` (with the browser-omits note). - **-32602 rendering**: SDK v2 rejects an unknown-tool call with `-32602` instead of an `isError` result, which previously rendered nothing. New ToolCallErrorPanel renders a thrown tool-call error, with a targeted "Unknown Tool" hint for `-32602`. Adds unit + Storybook + integration coverage (a real modern server with an invalid-header tool fixture) for every path. `npm run ci`-equivalent checks green. Closes #1632 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XNdjEPKLG637X8YmhDiEk5 * test-servers: x-mcp-header modern showcase config + preset (#1632) Register the `invalid_header_tool` fixture as a preset and add `xmcpheader-modern-http.json` — a modern HTTP showcase serving echo, a valid-header `get_weather`, and the invalid-header tool — so the Tools-tab x-mcp-header tooling (mirrored headers, excluded-tools surface, -32602 rendering) can be exercised manually. Documented in the README alongside the other per-SEP showcase configs. Smoke-tested end to end in the web client. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XNdjEPKLG637X8YmhDiEk5 * docs: add #1632 proof screenshots to pr-screenshots End-to-end web-client verification of the x-mcp-header Tools tooling against the modern showcase server: excluded-tools surface + reason, mirrored-headers section, and the -32602 unknown-tool error panel. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XNdjEPKLG637X8YmhDiEk5 * Respond to review: disambiguate -32602, doc/search nits (#1632) Addresses the review on PR #1735: 1. -32602 "Unknown Tool" mislabel: `-32602` is generic Invalid params, so a known tool called with bad arguments hit the same code and rendered under the definitive "Unknown Tool" heading. Replace `isUnknownToolError` with `classifyToolCallError(code, message)` → "unknown-tool" only when the message names it (not found / unknown tool / …), else "invalid-params" (new "Invalid Parameters" heading + schema hint), else "generic". 2. Double pagination walk: expand the `listAllTools` comment to document that the excluded-tools recompute is a deliberately un-cached second raw walk (doubles list round-trips on modern non-stdio, runs even on a cache-served aggregate) — accepted for a debugging tool, no-op on legacy/stdio. 3. Doc nit: `scanXMcpHeaderDeclarations` no longer claims to visit "$ref targets" — reworded to note `$ref` is never followed (refs resolve into the unreachable `$defs` body). 4. Search nit: the excluded-list filter now matches name AND title, matching the main tools filter. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XNdjEPKLG637X8YmhDiEk5 * Tighten unknown-tool matcher to be tool-scoped (#1632 re-review nit) The re-review noted the -32602 disambiguation was symmetric: broad markers ("does not exist", "unrecognized") could inversely mislabel a genuine invalid-params message (e.g. "property 'region' does not exist") as "Unknown Tool". Scope the not-found/does-not-exist family to require the word "tool" in the same clause (matching the SDK's "Tool <name> not found"); keep "unknown tool" / "no such tool" as standalone unambiguous markers. Adds a tool-less-"does not exist" test asserting it classifies as invalid-params. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XNdjEPKLG637X8YmhDiEk5 * Add trigger_invalid_params showcase tool + Invalid Parameters screenshot (#1632) Adds a `trigger_invalid_params` spec-error trigger to the modern showcase server: the injector answers its `tools/call` with a real `-32602 Invalid params` JSON-RPC error whose message does NOT name an unknown tool. This lets the "Invalid Parameters" branch of the tool-call error panel (added in the review response) be exercised live, distinct from the unknown-tool `-32602`. - `SPEC_ERROR_TRIGGERS` gains the `trigger_invalid_params` entry (HTTP 200, in-band -32602) + preset registration. - Enable `injectSpecErrors` on `xmcpheader-modern-http.json` and add the tool. - README + pr-screenshots README document it; adds the live "Invalid Parameters" proof screenshot. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01XNdjEPKLG637X8YmhDiEk5 --------- Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Cliff Hall
GitHub
parent
2259b1a3e1
commit
e70a11360c
1 changed files with 1610 additions and 86 deletions
|
|
@ -0,0 +1,175 @@
|
|||
import { describe, it, expect, afterEach, vi } from "vitest";
|
||||
import { InspectorClient } from "@inspector/core/mcp/inspectorClient.js";
|
||||
import { createTransportNode } from "@inspector/core/mcp/node/transport.js";
|
||||
import { eraToVersionNegotiation } from "@inspector/core/mcp/types.js";
|
||||
import type { ExcludedTool } from "@inspector/core/mcp/types.js";
|
||||
import {
|
||||
createTestServerHttp,
|
||||
type TestServerHttp,
|
||||
createTestServerInfo,
|
||||
createEchoTool,
|
||||
createGetWeatherTool,
|
||||
createInvalidHeaderTool,
|
||||
} from "@modelcontextprotocol/inspector-test-server";
|
||||
import type { ServerConfig } from "@modelcontextprotocol/inspector-test-server";
|
||||
|
||||
/**
|
||||
* Live coverage of the SEP-2243 excluded-tools surface (#1632). A modern
|
||||
* Streamable HTTP client MUST drop a tool whose `x-mcp-header` annotation
|
||||
* violates the spec; the SDK does so silently. `refreshExcludedTools()` re-lists
|
||||
* the RAW (unfiltered) `tools/list` and reports the dropped tools with the
|
||||
* constraint they broke, so the Tools tab can show *why* a tool vanished.
|
||||
*/
|
||||
describe("excluded tools (SEP-2243 x-mcp-header)", () => {
|
||||
let client: InspectorClient | null = null;
|
||||
let server: TestServerHttp | null = null;
|
||||
|
||||
afterEach(async () => {
|
||||
if (client) {
|
||||
try {
|
||||
await client.disconnect();
|
||||
} catch {
|
||||
// ignore
|
||||
}
|
||||
client = null;
|
||||
}
|
||||
if (server) {
|
||||
try {
|
||||
await server.stop();
|
||||
} catch {
|
||||
// ignore
|
||||
}
|
||||
server = null;
|
||||
}
|
||||
});
|
||||
|
||||
async function start(
|
||||
modern: ServerConfig["modern"] | undefined,
|
||||
maxPageSize?: number,
|
||||
): Promise<TestServerHttp> {
|
||||
const started = createTestServerHttp({
|
||||
serverInfo: createTestServerInfo("excluded-tools-test", "1.0.0"),
|
||||
// A valid tool, a valid-header tool, and an invalid-header tool.
|
||||
tools: [
|
||||
createEchoTool(),
|
||||
createGetWeatherTool(),
|
||||
createInvalidHeaderTool(),
|
||||
],
|
||||
...(modern ? { modern } : {}),
|
||||
...(maxPageSize ? { maxPageSize: { tools: maxPageSize } } : {}),
|
||||
});
|
||||
await started.start();
|
||||
server = started;
|
||||
return started;
|
||||
}
|
||||
|
||||
async function connect(
|
||||
url: string,
|
||||
era: "legacy" | "modern",
|
||||
): Promise<InspectorClient> {
|
||||
const connected = new InspectorClient(
|
||||
{ type: "streamable-http", url },
|
||||
{
|
||||
environment: { transport: createTransportNode },
|
||||
versionNegotiation: eraToVersionNegotiation(era),
|
||||
},
|
||||
);
|
||||
await connected.connect();
|
||||
client = connected;
|
||||
return connected;
|
||||
}
|
||||
|
||||
it("excludes the invalid-header tool from the managed list on a modern connection", async () => {
|
||||
const started = await start({});
|
||||
const connected = await connect(started.url, "modern");
|
||||
|
||||
const { tools } = await connected.listAllTools();
|
||||
const names = tools.map((t) => t.name);
|
||||
expect(names).toContain("echo");
|
||||
expect(names).toContain("get_weather");
|
||||
// The SDK drops the invalid-header tool from the aggregated list.
|
||||
expect(names).not.toContain("invalid_header_tool");
|
||||
});
|
||||
|
||||
it("surfaces the excluded tool with its reason after listAllTools (modern)", async () => {
|
||||
const started = await start({});
|
||||
const connected = await connect(started.url, "modern");
|
||||
|
||||
const events: ExcludedTool[][] = [];
|
||||
connected.addEventListener("excludedToolsChange", (e) => {
|
||||
events.push(e.detail);
|
||||
});
|
||||
|
||||
// listAllTools recomputes excluded tools as a side effect.
|
||||
await connected.listAllTools();
|
||||
|
||||
const excluded = connected.getExcludedTools();
|
||||
expect(excluded.map((x) => x.tool.name)).toEqual(["invalid_header_tool"]);
|
||||
expect(excluded[0]?.reason).toContain("RFC 9110 token");
|
||||
// The change event fired with the same set.
|
||||
expect(events.at(-1)?.map((x) => x.tool.name)).toEqual([
|
||||
"invalid_header_tool",
|
||||
]);
|
||||
});
|
||||
|
||||
it("refreshExcludedTools returns the excluded set directly (modern)", async () => {
|
||||
const started = await start({});
|
||||
const connected = await connect(started.url, "modern");
|
||||
|
||||
const excluded = await connected.refreshExcludedTools();
|
||||
expect(excluded.map((x) => x.tool.name)).toEqual(["invalid_header_tool"]);
|
||||
});
|
||||
|
||||
it("reports no excluded tools on a legacy connection (no exclusion there)", async () => {
|
||||
const started = await start(undefined);
|
||||
const connected = await connect(started.url, "legacy");
|
||||
|
||||
// Legacy servers don't exclude — the invalid-header tool stays in the list.
|
||||
const { tools } = await connected.listAllTools();
|
||||
expect(tools.map((t) => t.name)).toContain("invalid_header_tool");
|
||||
expect(connected.getExcludedTools()).toEqual([]);
|
||||
expect(await connected.refreshExcludedTools()).toEqual([]);
|
||||
});
|
||||
|
||||
it("clears excluded tools on disconnect", async () => {
|
||||
const started = await start({});
|
||||
const connected = await connect(started.url, "modern");
|
||||
await connected.listAllTools();
|
||||
expect(connected.getExcludedTools().length).toBe(1);
|
||||
|
||||
await connected.disconnect();
|
||||
client = null;
|
||||
expect(connected.getExcludedTools()).toEqual([]);
|
||||
});
|
||||
|
||||
it("walks every raw page to find the excluded tool (pagination)", async () => {
|
||||
// Page size 1 → the raw `tools/list` walk spans three pages; the invalid
|
||||
// tool is on the last one, so this exercises the cursor loop.
|
||||
const started = await start({}, 1);
|
||||
const connected = await connect(started.url, "modern");
|
||||
|
||||
const excluded = await connected.refreshExcludedTools();
|
||||
expect(excluded.map((x) => x.tool.name)).toEqual(["invalid_header_tool"]);
|
||||
});
|
||||
|
||||
it("listAllTools still returns tools if the excluded recompute throws", async () => {
|
||||
const started = await start({});
|
||||
const connected = await connect(started.url, "modern");
|
||||
// The excluded-tools recompute is best-effort: a failure must not fail the
|
||||
// tools list itself.
|
||||
vi.spyOn(connected, "refreshExcludedTools").mockRejectedValueOnce(
|
||||
new Error("boom"),
|
||||
);
|
||||
const { tools } = await connected.listAllTools();
|
||||
expect(tools.map((t) => t.name)).toContain("echo");
|
||||
});
|
||||
|
||||
it("is a no-op returning [] before connect (not modern)", async () => {
|
||||
const fresh = new InspectorClient(
|
||||
{ type: "streamable-http", url: "http://localhost:1/never" },
|
||||
{ environment: { transport: createTransportNode } },
|
||||
);
|
||||
// No round trip: the gate is false (era not modern), so it returns [].
|
||||
expect(await fresh.refreshExcludedTools()).toEqual([]);
|
||||
});
|
||||
});
|
||||
Loading…
Reference in a new issue