feat: allow complex JSON values in request _meta

Closes #1910

`_meta` was typed `Record<string, string>` end to end in the Inspector —
on disk as a `{ key, value }[]` pair array, in the Server Settings form as
key/value rows, and in every request verb's per-call metadata parameter.
Nothing in the MCP spec restricts a `_meta` value to a string, and the SDK
models the field as a `z.looseObject`, so the restriction was ours alone.

Widen the whole path to `RequestMetadata` (`Record<string, JsonValue>`):

- Per-server default metadata is a JSON **object** on disk and in memory.
  The pre-#1910 pair array is still read (`normalizeStoredMetadata`) so an
  existing `mcp.json` keeps working; it is never written back, so a save
  migrates the entry.
- The Server Settings → Request Metadata section is a JSON editor
  (`JsonObjectInput`) instead of key/value rows — rows cannot express an
  object value. It keeps the typed text as the display source and emits
  only parsed JSON, the same draft split `SchemaJsonField` uses, so the box
  stays typeable; invalid text is flagged inline and not applied.
- The CLI stops flattening `--metadata` / `--tool-metadata` through
  `metaValueToString`. Those values were already JSON-parsed, so
  `trace={"id":"abc"}` used to reach the wire as the *string* `{"id":"abc"}`
  and now reaches it as an object.
- `servers/show` redaction replaces a sensitive key's whole value rather
  than a string, so a structured value cannot leak through its members.
- `progressTokenOf` narrows the reserved `progressToken` key back to
  `string | number` before it reaches the SDK; any other JSON still travels
  inside `_meta` but wires up no progress callback.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0177mPHAdECD18nLLCTwR5rh
Signed-off-by: cliffhall <cliff@futurescale.com>
This commit is contained in:
cliffhall 2026-08-23 12:23:40 -04:00
commit b33532c024
13 changed files with 1004 additions and 495 deletions

View file

@ -76,7 +76,7 @@ describe("runner client auth options", () => {
taskTtl: 60000,
maxFetchRequests: 10,
autoRefreshOnListChanged: false,
metadata: [],
metadata: {},
headers: [],
env: [],
roots: [],
@ -99,7 +99,7 @@ describe("runner client auth options", () => {
taskTtl: 60000,
maxFetchRequests: 10,
autoRefreshOnListChanged: false,
metadata: [],
metadata: {},
headers: [],
env: [],
roots: [],
@ -116,7 +116,7 @@ describe("runner client auth options", () => {
taskTtl: 60000,
maxFetchRequests: 10,
autoRefreshOnListChanged: false,
metadata: [],
metadata: {},
headers: [],
env: [],
roots: [],
@ -135,7 +135,7 @@ describe("runner client auth options", () => {
taskTtl: 60000,
maxFetchRequests: 10,
autoRefreshOnListChanged: false,
metadata: [],
metadata: {},
headers: [],
env: [],
roots: [],
@ -156,7 +156,7 @@ describe("runner client auth options", () => {
taskTtl: 60000,
maxFetchRequests: 10,
autoRefreshOnListChanged: false,
metadata: [],
metadata: {},
headers: [],
env: [],
roots: [],
@ -187,7 +187,7 @@ describe("runner client auth options", () => {
taskTtl: 60000,
maxFetchRequests: 10,
autoRefreshOnListChanged: false,
metadata: [],
metadata: {},
headers: [],
env: [],
roots: [],

View file

@ -854,7 +854,7 @@ describe("InspectorClient peer-handler timing (#1797)", () => {
serverSettings: {
headers: [],
env: [],
metadata: [],
metadata: {},
connectionTimeout: 0,
requestTimeout: 0,
taskTtl: 0,

View file

@ -30,7 +30,7 @@ describe("headersToServerSettings", () => {
expect(settings?.headers).toEqual([
{ key: "Authorization", value: "Bearer t" },
]);
expect(settings?.metadata).toEqual([]);
expect(settings?.metadata).toEqual({});
expect(settings?.roots).toEqual([]);
});
});

View file

@ -361,7 +361,7 @@ describe("RemoteClientTransport", () => {
const settings = {
headers: [{ key: "X-Tenant", value: "acme" }],
env: [],
metadata: [],
metadata: {},
connectionTimeout: 0,
requestTimeout: 0,
taskTtl: 0,

View file

@ -11,6 +11,7 @@ import {
mcpConfigToServerEntries,
mergeSecretsIntoStored,
normalizeServerType,
normalizeStoredMetadata,
oauthAuthorizationParamsFromSettings,
oauthEndpointOverridesFromSettings,
serverEntriesToMcpConfig,
@ -240,7 +241,7 @@ describe("serverEntriesToMcpConfig", () => {
});
it("round-trips a populated set of Inspector-extension fields (post-#1358 flat shape)", () => {
// Disk shape: top-level `headers` (Record), `metadata` (pair-array),
// Disk shape: top-level `headers` (Record), `metadata` (JSON object),
// numeric timeouts, nested `oauth`. Round-trip must preserve the on-
// disk shape byte-equivalent so a hand-edited file is stable.
const original: MCPConfig = {
@ -249,7 +250,7 @@ describe("serverEntriesToMcpConfig", () => {
type: "streamable-http",
url: "https://x.test/mcp",
headers: { Authorization: "Bearer xyz" },
metadata: [{ key: "tenant", value: "acme" }],
metadata: { tenant: "acme", limits: { rps: 10 } },
connectionTimeout: 30000,
requestTimeout: 60000,
oauth: {
@ -581,7 +582,7 @@ describe("serverEntriesToMcpConfig", () => {
headers: [{ key: "X-Tenant", value: "acme" }],
// Non-stdio server → empty env mirror in memory (for the form)
env: [],
metadata: [],
metadata: {},
connectionTimeout: 0,
requestTimeout: 0,
// Absent taskTtl on disk → product default in memory (for the form)
@ -663,7 +664,7 @@ describe("serverEntriesToMcpConfig", () => {
{ key: " ", value: "whitespace" },
],
env: [],
metadata: [],
metadata: {},
connectionTimeout: 0,
requestTimeout: 0,
taskTtl: 0,
@ -690,7 +691,7 @@ describe("serverEntriesToMcpConfig", () => {
settings: {
headers: [],
env: [],
metadata: [],
metadata: {},
connectionTimeout: 0,
requestTimeout: 0,
taskTtl: 0,
@ -719,7 +720,7 @@ describe("serverEntriesToMcpConfig", () => {
settings: {
headers: [],
env: [],
metadata: [],
metadata: {},
connectionTimeout: 0,
requestTimeout: 0,
taskTtl: 0,
@ -758,7 +759,7 @@ describe("serverEntriesToMcpConfig", () => {
settings: {
headers: [],
env: [],
metadata: [],
metadata: {},
connectionTimeout: 0,
requestTimeout: 0,
taskTtl: 0,
@ -785,7 +786,7 @@ describe("serverEntriesToMcpConfig", () => {
settings: {
headers: [],
env: [],
metadata: [],
metadata: {},
connectionTimeout: 0,
requestTimeout: 0,
taskTtl: 0,
@ -1163,7 +1164,7 @@ describe("enterpriseManaged oauth settings", () => {
const stored = inspectorSettingsToStoredFields({
headers: [],
env: [],
metadata: [],
metadata: {},
connectionTimeout: 0,
requestTimeout: 0,
taskTtl: 60000,
@ -1180,7 +1181,7 @@ describe("enterpriseManaged oauth settings", () => {
const stored = inspectorSettingsToStoredFields({
headers: [],
env: [],
metadata: [],
metadata: {},
connectionTimeout: 0,
requestTimeout: 0,
taskTtl: 60000,
@ -1196,7 +1197,7 @@ describe("oauthOnInsufficientScope (SEP-2350)", () => {
const baseSettings = {
headers: [],
env: [],
metadata: [],
metadata: {},
connectionTimeout: 0,
requestTimeout: 0,
taskTtl: 60000,
@ -1374,6 +1375,109 @@ describe("oauthOnInsufficientScope (SEP-2350)", () => {
});
});
describe("normalizeStoredMetadata (#1910)", () => {
let warn: ReturnType<typeof vi.spyOn>;
beforeEach(() => {
warn = vi.spyOn(console, "warn").mockImplementation(() => {});
});
afterEach(() => {
warn.mockRestore();
});
it("passes an object through, values of any JSON type intact", () => {
const meta = {
s: "a",
n: 1,
b: false,
z: null,
arr: [1, { k: 2 }],
o: { deep: true },
};
expect(normalizeStoredMetadata(meta)).toEqual(meta);
});
it("copies rather than aliasing the stored object", () => {
// The settings object is edited in place by the form; sharing the
// reference with the parsed catalog would mutate it behind the caller.
const meta = { a: 1 };
const out = normalizeStoredMetadata(meta);
out.b = 2;
expect(meta).toEqual({ a: 1 });
});
it("reads the pre-#1910 pair array so an existing mcp.json keeps working", () => {
expect(
normalizeStoredMetadata([
{ key: "tenant", value: "acme" },
{ key: "n", value: 3 },
]),
).toEqual({ tenant: "acme", n: 3 });
});
it("skips a blank-key legacy pair", () => {
expect(
normalizeStoredMetadata([
{ key: "", value: "orphan" },
{ key: " ", value: "orphan" },
{ key: "kept", value: "yes" },
]),
).toEqual({ kept: "yes" });
});
it("reads a legacy pair with no value as an empty string", () => {
expect(normalizeStoredMetadata([{ key: "k" }])).toEqual({ k: "" });
});
it("drops a malformed legacy entry with a warning, keeping its siblings", () => {
expect(
normalizeStoredMetadata([
"nope",
null,
{ value: "no key" },
{ key: "kept", value: 1 },
]),
).toEqual({ kept: 1 });
expect(warn).toHaveBeenCalledTimes(3);
});
it.each([
["undefined", undefined],
["null", null],
])("reads %s as the empty object without warning", (_label, input) => {
expect(normalizeStoredMetadata(input)).toEqual({});
expect(warn).not.toHaveBeenCalled();
});
it.each([
["a string", "oops"],
["a number", 7],
["a boolean", true],
])("drops %s with a warning", (_label, input) => {
expect(normalizeStoredMetadata(input)).toEqual({});
expect(warn).toHaveBeenCalledTimes(1);
});
it("migrates a legacy file to the object shape on the next write", () => {
// Read side accepts the pair array; write side emits only the object, so
// one round-trip is the migration.
const entries = mcpConfigToServerEntries({
mcpServers: {
legacy: {
type: "streamable-http",
url: "https://x.test/mcp",
metadata: [{ key: "tenant", value: "acme" }] as unknown as Record<
string,
never
>,
},
},
});
expect(entries[0]?.settings?.metadata).toEqual({ tenant: "acme" });
const round = serverEntriesToMcpConfig(entries);
expect(round.mcpServers.legacy?.metadata).toEqual({ tenant: "acme" });
});
});
describe("envRecordToPairs / envPairsToRecord", () => {
it("envRecordToPairs preserves key insertion order", () => {
expect(envRecordToPairs({ B: "2", A: "1" })).toEqual([
@ -1469,7 +1573,7 @@ describe("stdio env / cwd mirroring", () => {
headers: [],
env: [{ key: "API_KEY", value: "secret" }],
cwd: "/srv/app",
metadata: [],
metadata: {},
connectionTimeout: 0,
requestTimeout: 0,
taskTtl: 60000,

View file

@ -13,7 +13,7 @@ function prompt(name: string): Prompt {
const AUTO_REFRESH_SETTINGS: InspectorServerSettings = {
headers: [],
env: [],
metadata: [],
metadata: {},
connectionTimeout: 0,
requestTimeout: 0,
taskTtl: 60000,

View file

@ -13,7 +13,7 @@ function template(name: string): ResourceTemplate {
const AUTO_REFRESH_SETTINGS: InspectorServerSettings = {
headers: [],
env: [],
metadata: [],
metadata: {},
connectionTimeout: 0,
requestTimeout: 0,
taskTtl: 60000,

View file

@ -13,7 +13,7 @@ function resource(uri: string): Resource {
const AUTO_REFRESH_SETTINGS: InspectorServerSettings = {
headers: [],
env: [],
metadata: [],
metadata: {},
connectionTimeout: 0,
requestTimeout: 0,
taskTtl: 60000,

View file

@ -13,7 +13,7 @@ function tool(name: string): Tool {
const AUTO_REFRESH_SETTINGS: InspectorServerSettings = {
headers: [],
env: [],
metadata: [],
metadata: {},
connectionTimeout: 0,
requestTimeout: 0,
taskTtl: 60000,

View file

@ -11,7 +11,7 @@ function prompt(name: string): Prompt {
const PAGINATED_SETTINGS: InspectorServerSettings = {
headers: [],
env: [],
metadata: [],
metadata: {},
connectionTimeout: 0,
requestTimeout: 0,
taskTtl: 60000,

View file

@ -11,7 +11,7 @@ function resource(uri: string): Resource {
const PAGINATED_SETTINGS: InspectorServerSettings = {
headers: [],
env: [],
metadata: [],
metadata: {},
connectionTimeout: 0,
requestTimeout: 0,
taskTtl: 60000,

View file

@ -11,7 +11,7 @@ function tool(name: string): Tool {
const PAGINATED_SETTINGS: InspectorServerSettings = {
headers: [],
env: [],
metadata: [],
metadata: {},
connectionTimeout: 0,
requestTimeout: 0,
taskTtl: 60000,

View file

@ -412,7 +412,7 @@ describe("useServers", () => {
await result.current.updateServerSettings("alpha", {
headers: [{ key: "X-Tenant", value: "acme" }],
env: [],
metadata: [{ key: "trace", value: "abc" }],
metadata: { trace: "abc" },
connectionTimeout: 5000,
requestTimeout: 30000,
taskTtl: 30000,
@ -425,7 +425,7 @@ describe("useServers", () => {
expect(result.current.servers[0]?.settings).toEqual({
headers: [{ key: "X-Tenant", value: "acme" }],
env: [],
metadata: [{ key: "trace", value: "abc" }],
metadata: { trace: "abc" },
connectionTimeout: 5000,
requestTimeout: 30000,
taskTtl: 30000,
@ -444,7 +444,7 @@ describe("useServers", () => {
expect(stored.url).toBe("https://x.test/mcp");
expect(stored).not.toHaveProperty("settings");
expect(stored.headers).toEqual({ "X-Tenant": "acme" });
expect(stored.metadata).toEqual([{ key: "trace", value: "abc" }]);
expect(stored.metadata).toEqual({ trace: "abc" });
expect(stored.connectionTimeout).toBe(5000);
expect(stored.requestTimeout).toBe(30000);
expect(stored.taskTtl).toBe(30000);
@ -461,7 +461,7 @@ describe("useServers", () => {
await result.current.updateServerSettings("nonexistent", {
headers: [],
env: [],
metadata: [],
metadata: {},
connectionTimeout: 0,
requestTimeout: 0,
taskTtl: 0,
@ -511,7 +511,7 @@ describe("useServers", () => {
expect(result.current.servers[0]?.settings).toEqual({
headers: [{ key: "X-Keep", value: "yes" }],
env: [],
metadata: [],
metadata: {},
connectionTimeout: 0,
requestTimeout: 0,
// Absent taskTtl on disk reads back as the product default for the form.