* 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
2 changed files with 1610 additions and 86 deletions
|
|
@ -111,6 +111,39 @@ describe("useInspectorClient", () => {
|
|||
expect(result.current.discoverResult).toEqual(discoverResult);
|
||||
});
|
||||
|
||||
it("subscribes to excludedToolsChange and updates (#1632)", () => {
|
||||
const client = new FakeInspectorClient();
|
||||
const { result } = renderHook(() => useInspectorClient(client));
|
||||
expect(result.current.excludedTools).toEqual([]);
|
||||
const excluded = [
|
||||
{
|
||||
tool: { name: "bad", inputSchema: { type: "object" as const } },
|
||||
reason:
|
||||
"value: x-mcp-header 'Bad Header' is not a valid RFC 9110 token",
|
||||
},
|
||||
];
|
||||
act(() => {
|
||||
client.setExcludedTools(excluded);
|
||||
});
|
||||
expect(result.current.excludedTools).toEqual(excluded);
|
||||
});
|
||||
|
||||
it("resets excludedTools to [] when client becomes null (#1632)", () => {
|
||||
const client = new FakeInspectorClient({ status: "connected" });
|
||||
client.setExcludedTools([
|
||||
{
|
||||
tool: { name: "bad", inputSchema: { type: "object" as const } },
|
||||
reason: "invalid",
|
||||
},
|
||||
]);
|
||||
const { result, rerender } = renderHook(({ c }) => useInspectorClient(c), {
|
||||
initialProps: { c: client as FakeInspectorClient | null },
|
||||
});
|
||||
expect(result.current.excludedTools.length).toBe(1);
|
||||
rerender({ c: null });
|
||||
expect(result.current.excludedTools).toEqual([]);
|
||||
});
|
||||
|
||||
it("resets protocolEra / discoverResult to defaults when client becomes null", () => {
|
||||
const client = new FakeInspectorClient({
|
||||
status: "connected",
|
||||
|
|
|
|||
281
clients/web/src/test/core/xMcpHeader.test.ts
Normal file
281
clients/web/src/test/core/xMcpHeader.test.ts
Normal file
|
|
@ -0,0 +1,281 @@
|
|||
import { describe, it, expect } from "vitest";
|
||||
import {
|
||||
scanXMcpHeaderDeclarations,
|
||||
getMirroredHeaderParams,
|
||||
MCP_PARAM_HEADER_PREFIX,
|
||||
X_MCP_HEADER_KEY,
|
||||
} from "@inspector/core/json/xMcpHeader.js";
|
||||
import type { Tool } from "@modelcontextprotocol/client";
|
||||
|
||||
function tool(inputSchema: Tool["inputSchema"]): Tool {
|
||||
return { name: "t", inputSchema };
|
||||
}
|
||||
|
||||
describe("scanXMcpHeaderDeclarations", () => {
|
||||
it("returns valid with no declarations for a schema without annotations", () => {
|
||||
const scan = scanXMcpHeaderDeclarations({
|
||||
type: "object",
|
||||
properties: { a: { type: "string" }, b: { type: "integer" } },
|
||||
});
|
||||
expect(scan).toEqual({ valid: true, declarations: [] });
|
||||
});
|
||||
|
||||
it("returns valid for a non-object schema (nothing to scan)", () => {
|
||||
expect(scanXMcpHeaderDeclarations(null)).toEqual({
|
||||
valid: true,
|
||||
declarations: [],
|
||||
});
|
||||
expect(scanXMcpHeaderDeclarations("nope")).toEqual({
|
||||
valid: true,
|
||||
declarations: [],
|
||||
});
|
||||
expect(scanXMcpHeaderDeclarations(undefined)).toEqual({
|
||||
valid: true,
|
||||
declarations: [],
|
||||
});
|
||||
});
|
||||
|
||||
it("collects a valid string declaration with its path and header name", () => {
|
||||
const scan = scanXMcpHeaderDeclarations({
|
||||
type: "object",
|
||||
properties: {
|
||||
region: { type: "string", [X_MCP_HEADER_KEY]: "Region" },
|
||||
},
|
||||
});
|
||||
expect(scan).toEqual({
|
||||
valid: true,
|
||||
declarations: [
|
||||
{ path: ["region"], headerName: "Region", type: "string" },
|
||||
],
|
||||
});
|
||||
});
|
||||
|
||||
it("accepts integer, boolean, and number typed properties", () => {
|
||||
const scan = scanXMcpHeaderDeclarations({
|
||||
type: "object",
|
||||
properties: {
|
||||
count: { type: "integer", [X_MCP_HEADER_KEY]: "Count" },
|
||||
flag: { type: "boolean", [X_MCP_HEADER_KEY]: "Flag" },
|
||||
ratio: { type: "number", [X_MCP_HEADER_KEY]: "Ratio" },
|
||||
},
|
||||
});
|
||||
expect(scan.valid).toBe(true);
|
||||
if (scan.valid) {
|
||||
expect(scan.declarations.map((d) => d.headerName)).toEqual([
|
||||
"Count",
|
||||
"Flag",
|
||||
"Ratio",
|
||||
]);
|
||||
}
|
||||
});
|
||||
|
||||
it("collects declarations nested at any depth via properties chains", () => {
|
||||
const scan = scanXMcpHeaderDeclarations({
|
||||
type: "object",
|
||||
properties: {
|
||||
filter: {
|
||||
type: "object",
|
||||
properties: {
|
||||
city: { type: "string", [X_MCP_HEADER_KEY]: "City" },
|
||||
},
|
||||
},
|
||||
},
|
||||
});
|
||||
expect(scan).toEqual({
|
||||
valid: true,
|
||||
declarations: [
|
||||
{ path: ["filter", "city"], headerName: "City", type: "string" },
|
||||
],
|
||||
});
|
||||
});
|
||||
|
||||
it("rejects an annotation on the root schema (empty path)", () => {
|
||||
const scan = scanXMcpHeaderDeclarations({
|
||||
type: "object",
|
||||
[X_MCP_HEADER_KEY]: "Root",
|
||||
});
|
||||
expect(scan.valid).toBe(false);
|
||||
if (!scan.valid) expect(scan.reason).toContain("<root>");
|
||||
});
|
||||
|
||||
it("rejects a non-string annotation value", () => {
|
||||
const scan = scanXMcpHeaderDeclarations({
|
||||
type: "object",
|
||||
properties: { a: { type: "string", [X_MCP_HEADER_KEY]: 42 } },
|
||||
});
|
||||
expect(scan.valid).toBe(false);
|
||||
if (!scan.valid) expect(scan.reason).toContain("non-empty string");
|
||||
});
|
||||
|
||||
it("rejects an empty-string annotation value", () => {
|
||||
const scan = scanXMcpHeaderDeclarations({
|
||||
type: "object",
|
||||
properties: { a: { type: "string", [X_MCP_HEADER_KEY]: "" } },
|
||||
});
|
||||
expect(scan.valid).toBe(false);
|
||||
if (!scan.valid) expect(scan.reason).toContain("non-empty string");
|
||||
});
|
||||
|
||||
it("rejects a header name that is not an RFC 9110 token", () => {
|
||||
const scan = scanXMcpHeaderDeclarations({
|
||||
type: "object",
|
||||
properties: {
|
||||
a: { type: "string", [X_MCP_HEADER_KEY]: "Not A Token" },
|
||||
},
|
||||
});
|
||||
expect(scan.valid).toBe(false);
|
||||
if (!scan.valid) expect(scan.reason).toContain("RFC 9110 token");
|
||||
});
|
||||
|
||||
it("rejects a non-primitive typed property", () => {
|
||||
const scan = scanXMcpHeaderDeclarations({
|
||||
type: "object",
|
||||
properties: {
|
||||
a: { type: "object", [X_MCP_HEADER_KEY]: "Obj" },
|
||||
},
|
||||
});
|
||||
expect(scan.valid).toBe(false);
|
||||
if (!scan.valid)
|
||||
expect(scan.reason).toContain("primitive-typed properties");
|
||||
});
|
||||
|
||||
it("rejects a property with a missing type", () => {
|
||||
const scan = scanXMcpHeaderDeclarations({
|
||||
type: "object",
|
||||
properties: { a: { [X_MCP_HEADER_KEY]: "NoType" } },
|
||||
});
|
||||
expect(scan.valid).toBe(false);
|
||||
if (!scan.valid) expect(scan.reason).toContain("<none>");
|
||||
});
|
||||
|
||||
it("rejects two headers that collide case-insensitively", () => {
|
||||
const scan = scanXMcpHeaderDeclarations({
|
||||
type: "object",
|
||||
properties: {
|
||||
a: { type: "string", [X_MCP_HEADER_KEY]: "Region" },
|
||||
b: { type: "string", [X_MCP_HEADER_KEY]: "region" },
|
||||
},
|
||||
});
|
||||
expect(scan.valid).toBe(false);
|
||||
if (!scan.valid)
|
||||
expect(scan.reason).toContain("not case-insensitively unique");
|
||||
});
|
||||
|
||||
it("rejects an annotation reachable only under items (array element)", () => {
|
||||
const scan = scanXMcpHeaderDeclarations({
|
||||
type: "object",
|
||||
properties: {
|
||||
list: {
|
||||
type: "array",
|
||||
items: {
|
||||
type: "object",
|
||||
properties: {
|
||||
x: { type: "string", [X_MCP_HEADER_KEY]: "X" },
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
});
|
||||
expect(scan.valid).toBe(false);
|
||||
if (!scan.valid) expect(scan.reason).toContain("statically reachable");
|
||||
});
|
||||
|
||||
it("rejects an annotation under a oneOf branch (array-valued keyword)", () => {
|
||||
const scan = scanXMcpHeaderDeclarations({
|
||||
type: "object",
|
||||
properties: {
|
||||
a: {
|
||||
oneOf: [{ type: "string", [X_MCP_HEADER_KEY]: "A" }],
|
||||
},
|
||||
},
|
||||
});
|
||||
expect(scan.valid).toBe(false);
|
||||
if (!scan.valid) expect(scan.reason).toContain("statically reachable");
|
||||
});
|
||||
|
||||
it("rejects an annotation under additionalProperties (single subschema)", () => {
|
||||
const scan = scanXMcpHeaderDeclarations({
|
||||
type: "object",
|
||||
additionalProperties: {
|
||||
type: "string",
|
||||
[X_MCP_HEADER_KEY]: "Extra",
|
||||
},
|
||||
});
|
||||
expect(scan.valid).toBe(false);
|
||||
if (!scan.valid) expect(scan.reason).toContain("statically reachable");
|
||||
});
|
||||
|
||||
it("rejects an annotation under $defs (object-valued keyword)", () => {
|
||||
const scan = scanXMcpHeaderDeclarations({
|
||||
type: "object",
|
||||
$defs: {
|
||||
Thing: { type: "string", [X_MCP_HEADER_KEY]: "Thing" },
|
||||
},
|
||||
});
|
||||
expect(scan.valid).toBe(false);
|
||||
if (!scan.valid) expect(scan.reason).toContain("statically reachable");
|
||||
});
|
||||
|
||||
it("ignores non-schema (null) branch values in subschema keywords", () => {
|
||||
const scan = scanXMcpHeaderDeclarations({
|
||||
type: "object",
|
||||
properties: {
|
||||
a: { type: "string", [X_MCP_HEADER_KEY]: "A" },
|
||||
},
|
||||
not: null,
|
||||
});
|
||||
expect(scan.valid).toBe(true);
|
||||
});
|
||||
});
|
||||
|
||||
describe("getMirroredHeaderParams", () => {
|
||||
it("maps valid declarations to Mcp-Param-{Name} headers", () => {
|
||||
const params = getMirroredHeaderParams(
|
||||
tool({
|
||||
type: "object",
|
||||
properties: {
|
||||
region: { type: "string", [X_MCP_HEADER_KEY]: "Region" },
|
||||
filter: {
|
||||
type: "object",
|
||||
properties: {
|
||||
city: { type: "string", [X_MCP_HEADER_KEY]: "City" },
|
||||
},
|
||||
},
|
||||
},
|
||||
}),
|
||||
);
|
||||
expect(params).toEqual([
|
||||
{
|
||||
path: "region",
|
||||
header: `${MCP_PARAM_HEADER_PREFIX}Region`,
|
||||
headerName: "Region",
|
||||
type: "string",
|
||||
},
|
||||
{
|
||||
path: "filter.city",
|
||||
header: `${MCP_PARAM_HEADER_PREFIX}City`,
|
||||
headerName: "City",
|
||||
type: "string",
|
||||
},
|
||||
]);
|
||||
});
|
||||
|
||||
it("returns [] for a tool without annotations", () => {
|
||||
expect(
|
||||
getMirroredHeaderParams(
|
||||
tool({ type: "object", properties: { a: { type: "string" } } }),
|
||||
),
|
||||
).toEqual([]);
|
||||
});
|
||||
|
||||
it("returns [] for a tool whose annotations are invalid", () => {
|
||||
expect(
|
||||
getMirroredHeaderParams(
|
||||
tool({
|
||||
type: "object",
|
||||
properties: { a: { type: "object", [X_MCP_HEADER_KEY]: "A" } },
|
||||
}),
|
||||
),
|
||||
).toEqual([]);
|
||||
});
|
||||
});
|
||||
Loading…
Reference in a new issue