Merge branch 'v2/main' into v2/fix/2067-proxy-undici

One conflict, in `clients/tui/__tests__/App.test.tsx`: both sides added an
`opts` capture to the test harness's `FakeClient` for different fields —
`defaultMetadata` on v2/main (#1910), `environment.fetch` here (#2067) — so the
resolution is the union of the two, keeping both rationales and both tests.

Everything else auto-merged. `npm run ci` passes on the result.

Signed-off-by: cliffhall <cliff@futurescale.com>
This commit is contained in:
cliffhall 2026-08-23 23:34:07 -04:00
commit 531cf84e60
11 changed files with 3739 additions and 691 deletions

View file

@ -116,15 +116,15 @@ Options that specify the MCP server (catalog/config file, ad-hoc command/URL, en
| `--prompt-name <name>` | Prompt name (for `prompts/get`). |
| `--prompt-args <key=value>` | Prompt arguments; repeat for multiple. |
| `--log-level <level>` | Logging level for `logging/setLevel` (e.g. `debug`, `info`). |
| `--metadata <key=value>` | General metadata (key=value); applied to all methods. |
| `--tool-metadata <key=value>` | Tool-specific metadata for `tools/call`. |
| `--metadata <key=value>` | General `_meta` entries (key=value); applied to all methods. The value is JSON-parsed when it parses, so `trace={"id":"abc"}` sends a real object and `n=3` a number; anything that is not valid JSON is sent as the literal string. |
| `--tool-metadata <key=value>` | Tool-specific `_meta` entries for `tools/call`. Same JSON-parsed value handling as `--metadata`. |
| `--connect-timeout <ms>` | Connection timeout in ms. Defaults to `15000` for ad-hoc `--server-url`/target runs (so a black-holed host fails fast) and to the file-level timeout for `--catalog`/`--config` runs. `0` disables the timeout. |
| `--app-info` | Probe a tool's MCP App UI metadata without invoking it. With `--method tools/call --tool-name <name>`: prints one JSON line (`hasApp`, `resourceUri`, `csp`, `permissions`, `domain`, …) and exits `0` if the tool has an app or `2` (`no_app`) if not. With `--method tools/list`: emits NDJSON — one app-info line per tool over a single connection. |
| `--format <text\|json>` | Output format. `text` (default) pretty-prints the result. `json` emits a single JSON object on stdout (`{ "result": … }`, plus `{ "appInfo": … }` as a sibling key for App tools) with no banners, so the whole output pipes cleanly into `jq`. |
| `--relogin` | Delete stored OAuth for this server URL from the shared store before connect; interactive login still only runs if the server requires auth. Requires an HTTP/SSE URL (rejected for stdio). Conflicts with `--stored-auth-only` / `--use-stored-auth` / `--wait-for-auth` / catalog short-circuits. |
| `--stored-auth-only` | **CI / non-interactive safe:** never start interactive OAuth / step-up (and never auto-open a browser); use the shared store if present, otherwise fail immediately with `auth_required`. Prefer this over a bare pipe/CI run that would otherwise attempt interactive login. |
`servers/show` redacts secret-bearing fields (`env` values, sensitive headers / `settings.metadata` keys, `requestInit` / `eventSourceInit` headers, `oauthClientSecret`). It does **not** scrub credentials embedded in a server `url` (userinfo or query tokens) or in stdio `args` — treat `detail` / raw URL fields as potentially sensitive before pasting into issues.
`servers/show` redacts secret-bearing fields (`env` values, sensitive headers, sensitive `settings.metadata` keys whose whole value is replaced whether or not it is structured, `requestInit` / `eventSourceInit` headers, `oauthClientSecret`). It does **not** scrub credentials embedded in a server `url` (userinfo or query tokens) or in stdio `args` — treat `detail` / raw URL fields as potentially sensitive before pasting into issues.
#### App probing (`--app-info`) and machine-readable output (`--format json`)

View file

@ -63,7 +63,7 @@ export function makeFakeServerSettings(
): InspectorServerSettings {
return {
headers: [],
metadata: [],
metadata: {},
env: [],
connectionTimeout: 0,
requestTimeout: 0,

View file

@ -373,16 +373,17 @@ describe("Metadata Tests", () => {
expectCliSuccess(result);
// Validate metadata values are sent as strings
// A JSON-parseable value goes out as that JSON type, not as its
// string spelling (#1910) — `_meta` takes any JSON.
const recordedRequests = server.getRecordedRequests();
const toolsListRequest = recordedRequests.find(
(r) => r.method === "tools/list",
);
expect(toolsListRequest).toBeDefined();
expect(toolsListRequest?.metadata).toEqual({
integer_value: "42",
decimal_value: "3.14159",
negative_value: "-10",
integer_value: 42,
decimal_value: 3.14159,
negative_value: -10,
});
} finally {
await server.stop();
@ -428,7 +429,7 @@ describe("Metadata Tests", () => {
}
});
it("JSON.stringifies object/array metadata (not String → [object Object])", async () => {
it("sends object/array/boolean metadata as real JSON, not stringified (#1910)", async () => {
const server = createTestServerHttp({
serverInfo: createTestServerInfo(),
tools: [createEchoTool()],
@ -456,9 +457,9 @@ describe("Metadata Tests", () => {
(r) => r.method === "tools/list",
);
expect(toolsListRequest?.metadata).toEqual({
nested: '{"key":"value"}',
list: "[1,2,3]",
flag: "true",
nested: { key: "value" },
list: [1, 2, 3],
flag: true,
});
} finally {
await server.stop();
@ -819,7 +820,7 @@ describe("Metadata Tests", () => {
);
expect(toolsListRequest).toBeDefined();
expect(toolsListRequest?.metadata).toEqual({
integration_test: "true",
integration_test: true,
test_phase: "all_methods",
});
} finally {
@ -866,8 +867,8 @@ describe("Metadata Tests", () => {
);
expect(toolCallRequest).toBeDefined();
expect(toolCallRequest?.metadata).toEqual({
session_id: "12345",
user_id: "67890",
session_id: 12345,
user_id: 67890,
timestamp: "2024-01-01T00:00:00Z",
request_id: "req-abc-123",
tool_session: "session-xyz-789",
@ -879,6 +880,65 @@ describe("Metadata Tests", () => {
}
});
it.each([
["an overflowing literal", "n=1e400"],
["a negative overflow", "n=-1e400"],
["one nested in an object", 'o={"a":1e400}'],
])("rejects %s rather than sending null", async (_label, pair) => {
// `JSON.parse` accepts these and yields ±Infinity, which
// `JSON.stringify` writes as `null` — so accepting the flag would
// transmit a value the user did not ask for.
const server = createTestServerHttp({
serverInfo: createTestServerInfo(),
tools: [createEchoTool()],
});
try {
await server.start();
const result = await runCli([
server.url,
"--cli",
"--method",
"tools/list",
"--metadata",
pair,
"--transport",
"http",
]);
expect(result.exitCode).not.toBe(0);
expect(`${result.stderr}${result.stdout}`).toMatch(/finite/i);
} finally {
await server.stop();
}
});
it("names the key but never the value when rejecting", async () => {
// The pair can carry a credential, and this message reaches stderr and
// CI logs.
const server = createTestServerHttp({
serverInfo: createTestServerInfo(),
tools: [createEchoTool()],
});
try {
await server.start();
const result = await runCli([
server.url,
"--cli",
"--method",
"tools/list",
"--metadata",
'credentials={"accessToken":"sk-live-nope","n":1e400}',
"--transport",
"http",
]);
const output = `${result.stderr}${result.stdout}`;
expect(result.exitCode).not.toBe(0);
expect(output).toContain("credentials");
expect(output).not.toContain("sk-live");
} finally {
await server.stop();
}
});
it("should handle metadata parsing validation", async () => {
const server = createTestServerHttp({
serverInfo: createTestServerInfo(),
@ -919,8 +979,8 @@ describe("Metadata Tests", () => {
expect(toolCallRequest).toBeDefined();
expect(toolCallRequest?.metadata).toEqual({
valid_key: "valid_value",
numeric_key: "123",
boolean_key: "true",
numeric_key: 123,
boolean_key: true,
json_key: '\'{"test":"value"}\'', // Single quotes are preserved
special_key: "!@#$%^&*()",
unicode_key: "🚀🎉✨",

View file

@ -1,7 +1,6 @@
import { describe, it, expect } from "vitest";
import {
isOneShotMethod,
metaValueToString,
ONE_SHOT_METHODS,
SESSION_RPC_METHODS,
} from "../src/handlers/method-types.js";
@ -26,11 +25,3 @@ describe("ONE_SHOT_METHODS", () => {
expect(ONE_SHOT_METHODS).not.toContain("logging/tail");
});
});
describe("metaValueToString", () => {
it("passes strings through and JSON-encodes structured values", () => {
expect(metaValueToString("plain")).toBe("plain");
expect(metaValueToString({ a: 1 })).toBe('{"a":1}');
expect(metaValueToString([1, 2])).toBe("[1,2]");
});
});

View file

@ -12,7 +12,7 @@ import {
describe("withConnectTimeout", () => {
const baseSettings: InspectorServerSettings = {
headers: [{ key: "X-Test", value: "1" }],
metadata: [],
metadata: {},
env: [],
connectionTimeout: 42,
requestTimeout: 0,

View file

@ -219,10 +219,23 @@ describe("showServerEntry / servers/show", () => {
{ key: "Authorization", value: "Bearer x" },
{ key: "X-Custom", value: "ok" },
],
metadata: [
{ key: "Authorization", value: "Bearer meta" },
{ key: "X-Custom", value: "ok" },
],
metadata: {
Authorization: "Bearer meta",
"X-Custom": "ok",
// A structured value under a sensitive key: the redaction must replace
// the whole value, not walk into it (#1910).
"X-Api-Key": { primary: "sk-live-1", fallback: "sk-live-2" },
nested: { keep: true },
// A secret buried under a non-sensitive key. A top-level-only check
// would print `accessToken` in full.
trace: {
id: "t-1",
accessToken: "sk-live-3",
deeper: { refresh_token: "sk-live-4", ok: 1 },
},
// Objects inside an array are reached too.
attempts: [{ password: "hunter2" }, { attempt: 2 }],
},
env: [
{ key: "TOKEN", value: "secret" },
{ key: "", value: "still-secret" },
@ -242,10 +255,20 @@ describe("showServerEntry / servers/show", () => {
{ key: "Authorization", value: "[redacted]" },
{ key: "X-Custom", value: "ok" },
]);
expect(sanitized.metadata).toEqual([
{ key: "Authorization", value: "[redacted]" },
{ key: "X-Custom", value: "ok" },
]);
expect(sanitized.metadata).toEqual({
Authorization: "[redacted]",
"X-Custom": "ok",
"X-Api-Key": "[redacted]",
// A structured value under a non-sensitive key survives intact...
nested: { keep: true },
// ...but a sensitive key nested inside one does not.
trace: {
id: "t-1",
accessToken: "[redacted]",
deeper: { refresh_token: "[redacted]", ok: 1 },
},
attempts: [{ password: "[redacted]" }, { attempt: 2 }],
});
expect(sanitized.env).toEqual([
{ key: "TOKEN", value: "[redacted]" },
{ key: "", value: "[redacted]" },

View file

@ -25,6 +25,8 @@ import {
parseHeaderPair,
} from "@inspector/core/mcp/node/index.js";
import type { JsonValue } from "@inspector/core/mcp/index.js";
import type { StrictJsonValue } from "@inspector/core/json/jsonUtils.js";
import { isSerializableJson } from "@inspector/core/json/jsonUtils.js";
import {
canonicalUrlHost,
isAllInterfacesHost,
@ -34,7 +36,6 @@ import { consumeMethodOutcome } from "./handlers/consume-outcome.js";
import { runMethod } from "./handlers/run-method.js";
import {
isOneShotMethod,
metaValueToString,
ONE_SHOT_METHODS,
type MethodArgs,
} from "./handlers/method-types.js";
@ -480,8 +481,8 @@ function buildHandoff(
function parseKeyValuePair(
value: string,
previous: Record<string, JsonValue> = {},
): Record<string, JsonValue> {
previous: Record<string, StrictJsonValue> = {},
): Record<string, StrictJsonValue> {
const parts = value.split("=");
const key = parts[0];
const val = parts.slice(1).join("=");
@ -492,13 +493,31 @@ function parseKeyValuePair(
);
}
let parsedValue: JsonValue;
// `StrictJsonValue`: `JSON.parse` cannot produce `undefined`, and these values
// become `_meta`, which must reach the wire exactly as written (#1910).
let parsedValue: StrictJsonValue;
try {
parsedValue = JSON.parse(val) as JsonValue;
parsedValue = JSON.parse(val) as StrictJsonValue;
} catch {
// Not JSON at all — a bare word or an unquoted string. Sent as a string,
// which is what the user plainly meant.
parsedValue = val;
}
// Valid JSON syntax is not the same as sendable JSON: `1e400` parses to
// `Infinity`, which `JSON.stringify` writes as `null`. Rejecting is better
// than accepting the flag and silently transmitting a different value —
// and better than falling back to the literal string, which would also not
// be what was asked for.
if (!isSerializableJson(parsedValue)) {
// Names the key, never the value: the pair can carry a credential
// (`credentials={"accessToken":"…","n":1e400}`) and this message lands in
// stderr and CI logs.
throw new Error(
`Invalid value for "${key}": numbers must be finite (a literal like 1e400 overflows to Infinity and cannot be sent).`,
);
}
return { ...previous, [key as string]: parsedValue };
}
@ -742,8 +761,8 @@ async function parseArgs(argv?: string[]): Promise<ParseResult> {
promptName?: string;
promptArgs?: Record<string, JsonValue>;
logLevel?: LoggingLevel;
metadata?: Record<string, JsonValue>;
toolMetadata?: Record<string, JsonValue>;
metadata?: Record<string, StrictJsonValue>;
toolMetadata?: Record<string, StrictJsonValue>;
cwd?: string;
transport?: "sse" | "http" | "stdio";
serverUrl?: string;
@ -1005,22 +1024,12 @@ async function parseArgs(argv?: string[]): Promise<ParseResult> {
promptName: options.promptName,
promptArgs: options.promptArgs,
logLevel: options.logLevel,
metadata: options.metadata
? Object.fromEntries(
Object.entries(options.metadata).map(([key, value]) => [
key,
metaValueToString(value),
]),
)
: undefined,
toolMeta: options.toolMetadata
? Object.fromEntries(
Object.entries(options.toolMetadata).map(([key, value]) => [
key,
metaValueToString(value),
]),
)
: undefined,
// `--metadata`/`--tool-metadata` values are parsed as JSON, and `_meta`
// takes any JSON — so they go through unflattened (#1910). They used to be
// squeezed through `metaValueToString`, which sent `{"a":1}` as the
// *string* `'{"a":1}'`.
metadata: options.metadata,
toolMeta: options.toolMetadata,
appInfo: options.appInfo === true,
format: options.format,
};

View file

@ -2,6 +2,7 @@ import { InspectorClient } from "@inspector/core/mcp/index.js";
import { extractAppInfo } from "@inspector/core/mcp/apps.js";
import type { AppInfo } from "@inspector/core/mcp/apps.js";
import type { CliAppInfo } from "./method-types.js";
import type { RequestMetadata } from "@inspector/core/mcp/types.js";
/**
* Build the CLI's app-info for a tool. Never throws — failures fold into
@ -10,7 +11,7 @@ import type { CliAppInfo } from "./method-types.js";
export async function collectAppInfo(
client: Pick<InspectorClient, "readResource">,
tool: Parameters<typeof extractAppInfo>[0],
metadata: Record<string, string> | undefined,
metadata: RequestMetadata | undefined,
): Promise<CliAppInfo> {
let base: AppInfo;
try {

View file

@ -22,7 +22,7 @@ export function withConnectTimeout(
if (settings) return { ...settings, connectionTimeout };
return {
headers: [],
metadata: [],
metadata: {},
env: [],
connectionTimeout,
requestTimeout: 0,

View file

@ -1,4 +1,5 @@
import type { JsonValue } from "@inspector/core/mcp/index.js";
import type { RequestMetadata } from "@inspector/core/mcp/types.js";
import type { AppInfo } from "@inspector/core/mcp/apps.js";
import type { LoggingLevel } from "@modelcontextprotocol/client";
import type { OutputFormat } from "./format-output.js";
@ -20,8 +21,8 @@ export type MethodArgs = {
logLevel?: LoggingLevel;
toolName?: string;
toolArg?: Record<string, JsonValue>;
toolMeta?: Record<string, string>;
metadata?: Record<string, string>;
toolMeta?: RequestMetadata;
metadata?: RequestMetadata;
appInfo?: boolean;
format?: OutputFormat;
/** Task id for tasks/get, tasks/cancel, tasks/result. */
@ -110,13 +111,3 @@ export type OneShotMethod = (typeof ONE_SHOT_METHODS)[number];
export function isOneShotMethod(method: string): method is OneShotMethod {
return (ONE_SHOT_METHODS as readonly string[]).includes(method);
}
/**
* Encode a metadata / tool-metadata value for MethodArgs (string map).
* Strings pass through; objects/arrays use JSON.stringify so structure is kept
* (avoids String(obj) → "[object Object]").
*/
export function metaValueToString(value: JsonValue): string {
if (typeof value === "string") return value;
return JSON.stringify(value);
}

View file

@ -157,10 +157,10 @@ export function sanitizeServerSettings(
key: h.key,
value: isSensitiveHeader(h.key) ? REDACTED : h.value,
})),
metadata: (settings.metadata ?? []).map((m) => ({
key: m.key,
value: isSensitiveHeader(m.key) ? REDACTED : m.value,
})),
// Metadata values may be any JSON (#1910), so the redaction has to descend:
// a top-level key that is not itself sensitive can hold a nested one that
// is. See `redactMetadataValue`.
metadata: redactMetadataValue(settings.metadata ?? {}),
env: (settings.env ?? []).map((e) => ({
key: e.key,
value: REDACTED,
@ -212,6 +212,39 @@ function sanitizeInitRecord(
return out;
}
/**
* Redact secret-bearing entries anywhere inside a `_meta` payload.
*
* The pre-#1910 version only had to check the top level, because a value was
* always a string — a secret could not hide below one. Now that a value may be
* an object or an array, `{ trace: { accessToken: "…" } }` would sail through a
* top-level-only check: `trace` is not sensitive, so the whole subtree,
* `accessToken` included, would print. `servers/show` output is meant to be
* safe to paste into an issue, so the walk has to reach every key.
*
* A key matching {@link isSensitiveHeader} replaces its **entire** value rather
* than being descended into, so a sensitive key holding an object cannot leak
* through its members either. Arrays are mapped elementwise: their indices are
* not names anyone can mark sensitive, but objects inside them can be.
*
* Recursion is bounded by the payload, which came from `JSON.parse` and so is a
* finite tree with no cycles.
*/
function redactMetadataValue(value: unknown): unknown {
if (Array.isArray(value)) {
return value.map(redactMetadataValue);
}
if (value !== null && typeof value === "object") {
return Object.fromEntries(
Object.entries(value).map(([key, member]) => [
key,
isSensitiveHeader(key) ? REDACTED : redactMetadataValue(member),
]),
);
}
return value;
}
function isSensitiveHeader(key: string): boolean {
const k = key.toLowerCase();
return (