@ikuma.cloud/pix-mcp 0.0.1 → 0.0.2

package/README.md

@@ -59,30 +59,94 @@ contact remote services. Configuration trust is not an OS sandbox.
       "url": "https://mcp.example.com/mcp",
       "headers": { "Authorization": "Bearer ${SERVICE_TOKEN}" },
       "description": "Issue tracking tools",
-      "timeoutMs": 30000,
+      "timeout": 960000,
+      "startupTimeoutMs": 30000,
+      "catalogTimeoutMs": 30000,
       "approve": true
     }
   }
 }
 ```
 
-Supported fields:
+### Supported configuration
+
+MCP standardizes the protocol, not a universal configuration file. This adapter
+supports a [Claude Code-style](https://code.claude.com/docs/en/mcp) connection
+subset, not every client-specific field or transport. OpenCode configuration,
+Cursor's `${env:VAR}` syntax, and other clients' approval policies are not imported
+or translated.
+
+The published [JSON Schema](mcp.schema.json) provides editor validation. An
+optional root `$schema` string can reference your installed copy; the adapter
+never fetches that URL. Runtime validation additionally checks expanded strings,
+URLs, and HTTP headers.
 
 | Field | Behavior |
 | --- | --- |
-| `type` | `stdio` or `http`; inferred from `command` or `url` when omitted |
-| `command`, `args`, `env`, `cwd` | Stdio only; executable and argument array, not a shell command |
-| `url`, `headers` | Streamable HTTP only; no SSE fallback or redirect following |
-| `description` | Optional short capability summary for discovery |
-| `timeoutMs` | Request/discovery timeout, default 30000; allowed range 100–120000 |
-| `approve` | Require confirmation for every invocation, default `true` |
-| `disabled` | Skip this server when `true` |
-
-Only `env` and `headers` values expand `${VARIABLE}` references. Missing
-variables fail without echoing their values. Stdio inherits the SDK's minimal
-platform environment plus explicit `env`, not the entire Pi environment.
-Credentials in HTTP URLs are rejected; use headers instead. Unknown fields fail
-rather than silently accepting unsupported configuration.
+| `type` | `stdio`, `http`, or `streamable-http` (alias of `http`); only stdio is inferred, when `command` is present |
+| `command`, `args`, `env` | Stdio only; executable and argument array, not a shell command |
+| `url`, `headers` | Streamable HTTP only; explicit `type` required; no legacy SSE fallback or redirect following |
+| `timeout` | Hard deadline for each tool invocation, in milliseconds; default 30000 |
+| `cwd` | Stdio extension: working directory relative to the config directory |
+| `description` | Discovery extension: optional summary, truncated to 500 characters |
+| `startupTimeoutMs` | pix extension: complete connection/initialization handshake deadline; default 30000 |
+| `catalogTimeoutMs` | pix extension: complete catalog snapshot deadline, including all pages; default 30000 |
+| `approve` | pix policy: require confirmation for every invocation, default `true` |
+| `disabled` | Skip the server's value validation and environment expansion when `true`; unknown fields are still errors |
+
+`command`, `args`, `cwd`, `env` values, `url`, and `headers` values expand `${VAR}`
+and `${VAR:-default}`. A default applies only when the variable is unset, not when
+it is an empty string. Expansion is single-pass against Pi's environment; `env`
+entries do not define variables for other entries. Missing variables and invalid
+expanded values fail without echoing credentials. Stdio inherits the SDK's
+minimal platform environment plus explicit `env`, not the entire Pi environment.
+Credentials and fragments in HTTP URLs are rejected; use headers for credentials.
+Unknown fields invalidate their server entry rather than being silently ignored.
+
+### Configuration errors
+
+An invalid server entry is skipped without hiding healthy servers. Discovery's
+`servers` list includes a safe diagnostic for each skipped entry; a valid server
+name can still be used with `mcp({ action: "list", server: "name" })` to inspect
+its status. Invalid names are replaced with their one-based entry positions.
+Diagnostics identify supported fields or migration steps without echoing URLs,
+commands, headers, argument values, or environment-variable names.
+
+Malformed JSON, invalid root structure, unknown root fields, and the file/server
+count limits remain fatal for the whole file. An invalid-only configuration
+reports that no valid servers remain. Disabled entries are omitted, not reported
+as failed connections. Correct the file and reload Pi to retry.
+
+Configuration trust still applies before any valid server is started or its
+metadata exposed. Per-call approval remains independent of configuration errors.
+
+### Deadlines and migration
+
+All three deadline fields accept integers from 1 through 2,147,483,647 milliseconds
+(Node's timer-safe maximum). Each defaults independently to 30 seconds. Setting
+`"timeout": 960000` permits a 16-minute tool call without lengthening startup or
+discovery. The call clock starts after invocation approval and connection startup;
+progress does not reset it. Catalog deadlines cover all pages of one snapshot;
+a subsequent list-change refresh starts a new deadline.
+
+HTTP deadlines cover response headers and bodies, including JSON and SSE. MCP
+requests borrow the host's HTTP/proxy routing but override its header/body idle
+limits per request; Pi's global settings and unrelated requests are unchanged.
+Notification GET streams have a bounded header wait but no body-idle deadline.
+Upstream proxies and servers may still impose their own limits.
+
+**Breaking changes from 0.0.1:**
+
+- Replace `timeoutMs` with `timeout` for tool calls. Set `startupTimeoutMs` and
+  `catalogTimeoutMs` separately if their defaults are unsuitable. The removed
+  field produces a migration diagnostic; it is not an alias.
+- Add `"type": "http"` to remote entries that previously specified only `url`.
+- Connection strings now expand environment references beyond `env` and `headers`.
+
+The 120-second call ceiling is removed. This is a configuration migration, not a
+promise to finish a remote operation within its deadline.
+
+### Invocation approval
 
 Tool invocation requires confirmation independently of config trust. In headless
 mode, calls fail closed unless the reviewed configuration explicitly sets
@@ -94,7 +158,8 @@ server separately in a trusted environment.
 ## Discovery and execution
 
 At session startup, the adapter connects to trusted servers and fetches their
-paginated tool catalogs. One failure does not hide tools from other servers.
+paginated tool catalogs. A server's configuration, connection, or discovery
+failure does not hide tools from other servers.
 Full schemas stay out of model context until selected. **Schema exposure is lazy;
 initial connections and metadata discovery are not.**
 
@@ -156,12 +221,13 @@ Schemas are syntax-checked before compilation. Only the default MCP dialect,
 JSON Schema 2020-12, is supported; explicit legacy dialects (including embedded
 resources) are rejected rather than interpreted with incorrect reference
 semantics. External schema references are unsupported, but literal `$ref` fields
-inside instance data are allowed. Requests and the entire initialization
-handshake use fixed deadlines, not progress-extended timeouts.
+inside instance data are allowed.
 
 The adapter never automatically retries `tools/call`: a timeout or lost response
-may occur after a mutating operation took effect. Successful output is validated
-against the schema captured when the call began; MCP error results are exempt
+may occur after a mutating operation took effect. Cancellation or expiration
+aborts only the affected HTTP request and sends a best-effort MCP cancellation
+notification; concurrent sibling calls remain usable. Successful output is
+validated against the schema captured when the call began; MCP error results are exempt
 from that success schema. Cancellation is best-effort at the server and does not
 roll back effects.
 

package/mcp.schema.json

@@ -0,0 +1,126 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "pix-mcp configuration",
+  "description": "A Claude-style connection subset with pix-specific approval and lifecycle options. Environment expansion and HTTP URL/header validation also occur at runtime.",
+  "type": "object",
+  "required": ["mcpServers"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "$ref": "#/$defs/text",
+      "description": "Editor hint only; never fetched by pix-mcp."
+    },
+    "mcpServers": {
+      "type": "object",
+      "maxProperties": 32,
+      "propertyNames": { "pattern": "^[A-Za-z0-9_-]{1,48}$" },
+      "additionalProperties": { "$ref": "#/$defs/server" }
+    }
+  },
+  "$defs": {
+    "text": { "type": "string", "minLength": 1, "pattern": "^[^\u0000]*$" },
+    "string": { "type": "string", "pattern": "^[^\u0000]*$" },
+    "timeout": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 2147483647,
+      "default": 30000,
+      "description": "Fixed deadline in milliseconds; progress does not extend it."
+    },
+    "common": {
+      "type": "object",
+      "properties": {
+        "description": { "$ref": "#/$defs/text" },
+        "timeout": {
+          "$ref": "#/$defs/timeout",
+          "description": "Hard deadline for one tool invocation."
+        },
+        "startupTimeoutMs": {
+          "$ref": "#/$defs/timeout",
+          "description": "pix extension: complete transport connection and initialization handshake."
+        },
+        "catalogTimeoutMs": {
+          "$ref": "#/$defs/timeout",
+          "description": "pix extension: one complete catalog snapshot, including all pages."
+        },
+        "approve": {
+          "type": "boolean",
+          "default": true,
+          "description": "pix extension: require confirmation for every tool invocation."
+        },
+        "disabled": { "const": false }
+      }
+    },
+    "stdio": {
+      "allOf": [{ "$ref": "#/$defs/common" }],
+      "type": "object",
+      "required": ["command"],
+      "properties": {
+        "type": { "const": "stdio" },
+        "command": { "$ref": "#/$defs/text" },
+        "args": { "type": "array", "items": { "$ref": "#/$defs/string" } },
+        "cwd": {
+          "$ref": "#/$defs/text",
+          "description": "Resolved relative to the configuration directory."
+        },
+        "env": {
+          "type": "object",
+          "propertyNames": { "pattern": "^[A-Za-z_][A-Za-z0-9_-]*$" },
+          "additionalProperties": { "$ref": "#/$defs/string" }
+        }
+      },
+      "not": { "anyOf": [{ "required": ["url"] }, { "required": ["headers"] }] }
+    },
+    "http": {
+      "allOf": [{ "$ref": "#/$defs/common" }],
+      "type": "object",
+      "required": ["type", "url"],
+      "properties": {
+        "type": { "enum": ["http", "streamable-http"] },
+        "url": { "$ref": "#/$defs/text" },
+        "headers": {
+          "type": "object",
+          "propertyNames": { "pattern": "^[!#$%&'*+.^_`|~0-9A-Za-z-]+$" },
+          "additionalProperties": { "$ref": "#/$defs/string" }
+        }
+      },
+      "not": {
+        "anyOf": [
+          { "required": ["command"] },
+          { "required": ["args"] },
+          { "required": ["env"] },
+          { "required": ["cwd"] }
+        ]
+      }
+    },
+    "server": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "type": true,
+        "command": true,
+        "args": true,
+        "env": true,
+        "cwd": true,
+        "url": true,
+        "headers": true,
+        "description": true,
+        "timeout": true,
+        "startupTimeoutMs": true,
+        "catalogTimeoutMs": true,
+        "approve": true,
+        "disabled": { "type": "boolean" }
+      },
+      "if": {
+        "required": ["disabled"],
+        "properties": { "disabled": { "const": true } }
+      },
+      "then": {
+        "description": "Disabled entries skip value validation and environment expansion, but unknown fields remain errors."
+      },
+      "else": {
+        "oneOf": [{ "$ref": "#/$defs/stdio" }, { "$ref": "#/$defs/http" }]
+      }
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ikuma.cloud/pix-mcp",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "publishConfig": {
     "access": "public"
   },
@@ -11,6 +11,7 @@
   ],
   "files": [
     "src",
+    "mcp.schema.json",
     "!src/**/*.test.ts",
     "!src/fixtures"
   ],
@@ -21,7 +22,8 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.30.0",
-    "ajv": "8.20.0"
+    "ajv": "8.20.0",
+    "undici": "8.10.2"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "*",

package/src/client.ts

@@ -1,3 +1,5 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { fetch as undiciFetch, getGlobalDispatcher } from "undici";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
@@ -40,6 +42,7 @@ export class Connection {
   #stopped = false;
   #changed: (tools: Tool[]) => void;
   #outputValidators = new Map<string, ReturnType<typeof compileSchema>>();
+  #operation = new AsyncLocalStorage<AbortSignal>();
 
   constructor(config: ServerConfig, changed: (tools: Tool[]) => void) {
     this.config = config;
@@ -96,44 +99,98 @@ export class Connection {
     void this.client.close().catch(() => {});
   }
 
+  async #deadline<T>(
+    timeout: number,
+    signal: AbortSignal | undefined,
+    action: (signal: AbortSignal) => Promise<T>,
+  ): Promise<T> {
+    const outer = signal
+      ? AbortSignal.any([signal, this.#lifetime.signal])
+      : this.#lifetime.signal;
+    outer.throwIfAborted();
+    const deadline = new AbortController();
+    const transport = new AbortController();
+    const abort = () => deadline.abort(outer.reason);
+    outer.addEventListener("abort", abort, { once: true });
+    const timer = setTimeout(
+      () => deadline.abort(new Error("MCP operation timed out.")),
+      timeout,
+    );
+    try {
+      // SDK 1.30 does not forward request signals to HTTP fetch. Async context
+      // keeps concurrent requests isolated without relying on private SDK IDs.
+      return await this.#operation.run(
+        AbortSignal.any([deadline.signal, transport.signal]),
+        () => action(deadline.signal),
+      );
+    } finally {
+      clearTimeout(timer);
+      outer.removeEventListener("abort", abort);
+      // Use a separate signal: aborting the SDK signal after success would send
+      // a spurious cancellation for an already-completed request in SDK 1.30.
+      transport.abort();
+    }
+  }
+
   async #fetch(
     url: Parameters<typeof fetch>[0],
     init: Parameters<typeof fetch>[1],
   ) {
-    // Teardown must still send DELETE after the connection lifetime is aborted.
-    if (init?.method === "DELETE")
-      return globalThis.fetch(url, {
+    // Borrow the host's routing/proxy dispatcher, but override idle limits only
+    // for this request. Our AbortSignals bound headers AND bodies. Use the same
+    // Undici implementation as the dispatcher to preserve decompression behavior.
+    const dispatcher = getGlobalDispatcher().compose(
+      (dispatch) => (options, handler) =>
+        dispatch({ ...options, headersTimeout: 0, bodyTimeout: 0 }, handler),
+    );
+    const fetch = (signal: AbortSignal) => {
+      const request = {
         ...init,
-        redirect: "error",
-        signal: AbortSignal.timeout(2000),
-      });
+        redirect: "error" as const,
+        signal,
+        dispatcher,
+      };
+      // SDK/global fetch and npm Undici expose different DOM type declarations;
+      // the SDK sends a URL and a serialized JSON body, compatible with both.
+      return undiciFetch(
+        url as Parameters<typeof undiciFetch>[0],
+        request as Parameters<typeof undiciFetch>[1],
+      ) as unknown as Promise<Response>;
+    };
+    // Teardown must still send DELETE after the connection lifetime is aborted.
+    if (init?.method === "DELETE") return fetch(AbortSignal.timeout(2000));
     const signals = [
       this.#lifetime.signal,
       ...(init?.signal ? [init.signal] : []),
     ];
     if (init?.method !== "GET") {
-      return globalThis.fetch(url, {
-        ...init,
-        redirect: "error",
-        signal: AbortSignal.any([
-          ...signals,
-          AbortSignal.timeout(this.config.timeoutMs),
-        ]),
-      });
+      // This body is generated by the SDK. Only our requests and the initialized
+      // handshake notification belong to an operation. Incoming stream callbacks
+      // retain their creator's async context: replies to server pings must not
+      // inherit the already-finished handshake's abort signal. Cancellation and
+      // other control messages also need their own short, lifetime-bound budget.
+      const message =
+        typeof init?.body === "string" ? JSON.parse(init.body) : undefined;
+      const scoped =
+        message &&
+        (("method" in message && "id" in message) ||
+          message.method === "notifications/initialized");
+      const operation = scoped ? this.#operation.getStore() : undefined;
+      return fetch(
+        AbortSignal.any([...signals, operation ?? AbortSignal.timeout(2000)]),
+      );
     }
     // GET is optional (405 is valid), but an established notification stream
     // cannot disappear silently: with retries disabled its catalog is stale.
     const headersDeadline = new AbortController();
     const timer = setTimeout(
       () => headersDeadline.abort(),
-      this.config.timeoutMs,
+      this.config.startupTimeoutMs,
     );
     try {
-      const response = await globalThis.fetch(url, {
-        ...init,
-        redirect: "error",
-        signal: AbortSignal.any([...signals, headersDeadline.signal]),
-      });
+      const response = await fetch(
+        AbortSignal.any([...signals, headersDeadline.signal]),
+      );
       if (response.status === 405) return response;
       if (
         !response.ok ||
@@ -177,13 +234,18 @@ export class Connection {
       // send. Bound the whole handshake and close the transport to release it.
       const handshakeTimer = setTimeout(
         () => this.#disconnect(),
-        this.config.timeoutMs,
+        this.config.startupTimeoutMs,
       );
       try {
-        await this.client.connect(this.#transport as Transport, {
-          signal: this.#lifetime.signal,
-          timeout: this.config.timeoutMs,
-        });
+        await this.#deadline(
+          this.config.startupTimeoutMs,
+          undefined,
+          (signal) =>
+            this.client.connect(this.#transport as Transport, {
+              signal,
+              timeout: this.config.startupTimeoutMs,
+            }),
+        );
       } finally {
         clearTimeout(handshakeTimer);
       }
@@ -220,55 +282,66 @@ export class Connection {
         const names = new Set<string>();
         let cursor: string | undefined;
         let bytes = 0;
-        const signal = AbortSignal.any([
-          this.#lifetime.signal,
-          AbortSignal.timeout(this.config.timeoutMs),
-        ]);
-        if (this.client.getServerCapabilities()?.tools) {
-          do {
-            const page = await this.client.request(
-              {
-                method: "tools/list",
-                params: cursor === undefined ? {} : { cursor },
-              },
-              catalogResultSchema,
-              {
-                signal,
-                timeout: this.config.timeoutMs,
-              },
-            );
-            bytes += Buffer.byteLength(JSON.stringify(page));
-            if (
-              bytes > 2 * 1024 * 1024 ||
-              tools.length + page.tools.length > 1000
-            )
-              throw new Error("Catalog limit");
-            for (const tool of page.tools) {
-              if (names.has(tool.name)) throw new Error("Duplicate tool name");
-              names.add(tool.name);
-              tools.push(tool);
+        await this.#deadline(
+          this.config.catalogTimeoutMs,
+          undefined,
+          async (signal) => {
+            if (this.client.getServerCapabilities()?.tools) {
+              do {
+                const page = await this.#deadline(
+                  this.config.catalogTimeoutMs,
+                  signal,
+                  (requestSignal) =>
+                    this.client.request(
+                      {
+                        method: "tools/list",
+                        params: cursor === undefined ? {} : { cursor },
+                      },
+                      catalogResultSchema,
+                      {
+                        signal: requestSignal,
+                        timeout: this.config.catalogTimeoutMs,
+                      },
+                    ),
+                );
+                bytes += Buffer.byteLength(JSON.stringify(page));
+                if (
+                  bytes > 2 * 1024 * 1024 ||
+                  tools.length + page.tools.length > 1000
+                )
+                  throw new Error("Catalog limit");
+                for (const tool of page.tools) {
+                  if (names.has(tool.name))
+                    throw new Error("Duplicate tool name");
+                  names.add(tool.name);
+                  tools.push(tool);
+                }
+                cursor = page.nextCursor;
+                if (cursor !== undefined) {
+                  if (cursors.has(cursor) || cursors.size >= 100)
+                    throw new Error("Invalid pagination");
+                  cursors.add(cursor);
+                }
+              } while (cursor !== undefined);
             }
-            cursor = page.nextCursor;
-            if (cursor !== undefined) {
-              if (cursors.has(cursor) || cursors.size >= 100)
-                throw new Error("Invalid pagination");
-              cursors.add(cursor);
+            // Keep a complete, atomic validator snapshot rather than the SDK's
+            // per-page mutable cache, including when a catalog changes during a call.
+            const validators = new Map<
+              string,
+              ReturnType<typeof compileSchema>
+            >();
+            for (const tool of tools) {
+              if (tool.outputSchema)
+                validators.set(tool.name, compileSchema(tool.outputSchema));
             }
-          } while (cursor !== undefined);
-        }
-        // Keep a complete, atomic validator snapshot rather than the SDK's
-        // per-page mutable cache, including when a catalog changes during a call.
-        const validators = new Map<string, ReturnType<typeof compileSchema>>();
-        for (const tool of tools) {
-          if (tool.outputSchema)
-            validators.set(tool.name, compileSchema(tool.outputSchema));
-        }
-        signal.throwIfAborted();
-        if (!this.#stopped) {
-          this.#outputValidators = validators;
-          this.status = "Connected";
-          this.#changed(tools);
-        }
+            signal.throwIfAborted();
+            if (!this.#stopped) {
+              this.#outputValidators = validators;
+              this.status = "Connected";
+              this.#changed(tools);
+            }
+          },
+        );
       }
     } catch {
       if (!this.#stopped) {
@@ -295,14 +368,19 @@ export class Connection {
       // validates error payloads against success schemas. Use one typed request,
       // then our captured validator; task-only tools are excluded during discovery.
       // Never retry: a lost response does not prove the operation did not run.
-      const result = await this.client.request(
-        { method: "tools/call", params: { name, arguments: args } },
-        CallToolResultSchema,
-        {
-          signal: combined,
-          timeout: this.config.timeoutMs,
-          resetTimeoutOnProgress: false,
-        },
+      const result = await this.#deadline(
+        this.config.timeout,
+        combined,
+        (requestSignal) =>
+          this.client.request(
+            { method: "tools/call", params: { name, arguments: args } },
+            CallToolResultSchema,
+            {
+              signal: requestSignal,
+              timeout: this.config.timeout,
+              resetTimeoutOnProgress: false,
+            },
+          ),
       );
       const parsed = CallToolResultSchema.parse(result);
       if (

package/src/config.ts

@@ -1,10 +1,14 @@
 import { readFile } from "node:fs/promises";
 import { dirname, resolve } from "node:path";
 
+export const MAX_TIMEOUT_MS = 2_147_483_647;
+
 export interface CommonServer {
   name: string;
   description: string;
-  timeoutMs: number;
+  timeout: number;
+  startupTimeoutMs: number;
+  catalogTimeoutMs: number;
   approve: boolean;
 }
 export type ServerConfig = CommonServer &
@@ -18,51 +22,217 @@ export type ServerConfig = CommonServer &
       }
     | { type: "http"; url: string; headers: Record<string, string> }
   );
+export interface ConfigIssue {
+  name: string;
+  field?: string;
+  message: string;
+}
 export interface Config {
   path: string;
   servers: ServerConfig[];
+  issues: ConfigIssue[];
 }
 
-function invalid(): never {
-  // Never echo config values: URLs, headers, arguments, and even parse errors can contain secrets.
-  throw new Error(
-    "Invalid MCP configuration. See the pix-mcp README for supported fields.",
-  );
+class ConfigError extends Error {
+  readonly field: string | undefined;
+  constructor(message: string, field?: string) {
+    // Only fixed messages and known field names belong here, never input values.
+    super(`Invalid MCP configuration. ${field ? `${field}: ` : ""}${message}`);
+    this.field = field;
+  }
+}
+function invalid(
+  field?: string,
+  message = "See the pix-mcp README for supported fields.",
+): never {
+  throw new ConfigError(message, field);
 }
-function object(value: unknown): Record<string, unknown> {
-  if (!value || typeof value !== "object" || Array.isArray(value)) invalid();
+function object(value: unknown, field?: string): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    invalid(field, "Expected an object.");
   return value as Record<string, unknown>;
 }
-function text(value: unknown): string {
-  if (typeof value !== "string" || value.length === 0 || value.includes("\0"))
-    invalid();
+function text(value: unknown, field: string, empty = false): string {
+  if (
+    typeof value !== "string" ||
+    (!empty && value.length === 0) ||
+    value.includes("\0")
+  )
+    invalid(field, "Expected a valid string.");
   return value;
 }
+function expand(
+  value: unknown,
+  env: NodeJS.ProcessEnv,
+  field: string,
+  empty = false,
+): string {
+  const expanded = text(value, field, empty).replace(
+    /\$\{([^}]*)\}|\$\{/g,
+    (_match, expression: string | undefined) => {
+      const match = expression?.match(
+        /^([A-Za-z_][A-Za-z0-9_]*)(?::-([\s\S]*))?$/,
+      );
+      if (!match?.[1])
+        invalid(
+          field,
+          `Use \${VAR} or \${VAR:-default} environment references.`,
+        );
+      const replacement =
+        (Object.hasOwn(env, match[1]) ? env[match[1]] : undefined) ?? match[2];
+      if (replacement === undefined)
+        invalid(field, "References an unset environment variable.");
+      return replacement;
+    },
+  );
+  return text(expanded, field, empty);
+}
 function strings(
   value: unknown,
   env: NodeJS.ProcessEnv,
-  kind: "env" | "headers" = "env",
+  field: "env" | "headers",
 ): Record<string, string> {
   const result: Record<string, string> = Object.create(null);
-  for (const [key, entry] of Object.entries(object(value))) {
-    // HTTP field names use token grammar, not environment-variable grammar;
-    // the Headers constructor below validates them without leaking their values.
-    if (kind === "env" && !/^[A-Za-z_][A-Za-z0-9_-]*$/.test(key)) invalid();
-    if (typeof entry !== "string" || entry.includes("\0")) invalid();
-    result[key] = entry.replace(
-      /\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g,
-      (_match, name: string) => {
-        const replacement = env[name];
-        if (replacement === undefined)
-          throw new Error(
-            "MCP configuration references an unset environment variable.",
-          );
-        return replacement;
-      },
-    );
+  for (const [key, entry] of Object.entries(object(value, field))) {
+    if (field === "env" && !/^[A-Za-z_][A-Za-z0-9_-]*$/.test(key))
+      invalid(field, "Invalid environment variable name.");
+    result[key] = expand(entry, env, field, true);
   }
   return result;
 }
+function timeout(value: unknown, field: string): number {
+  if (value === undefined) return 30_000;
+  // Node timers overflow above this bound and can fire almost immediately.
+  if (
+    typeof value !== "number" ||
+    !Number.isInteger(value) ||
+    value < 1 ||
+    value > MAX_TIMEOUT_MS
+  )
+    invalid(
+      field,
+      `Expected an integer from 1 through ${MAX_TIMEOUT_MS} milliseconds.`,
+    );
+  return value;
+}
+
+function parseServer(
+  name: string,
+  raw: unknown,
+  path: string,
+  env: NodeJS.ProcessEnv,
+): ServerConfig | undefined {
+  if (!/^[A-Za-z0-9_-]{1,48}$/.test(name))
+    invalid(
+      undefined,
+      "Server names must contain 1–48 ASCII letters, digits, underscores, or hyphens.",
+    );
+  const server = object(raw);
+  if (Object.hasOwn(server, "timeoutMs"))
+    invalid(
+      "timeoutMs",
+      "Removed; use timeout for tool calls, startupTimeoutMs for initialization, and catalogTimeoutMs for discovery (milliseconds).",
+    );
+  const allowed = new Set([
+    "type",
+    "command",
+    "args",
+    "env",
+    "cwd",
+    "url",
+    "headers",
+    "description",
+    "timeout",
+    "startupTimeoutMs",
+    "catalogTimeoutMs",
+    "approve",
+    "disabled",
+  ]);
+  if (Object.keys(server).some((key) => !allowed.has(key)))
+    invalid(
+      undefined,
+      "Unsupported server field. See the pix-mcp README for supported fields.",
+    );
+  if (server.disabled !== undefined && typeof server.disabled !== "boolean")
+    invalid("disabled", "Expected a boolean.");
+  if (server.disabled === true) return undefined;
+  if (server.approve !== undefined && typeof server.approve !== "boolean")
+    invalid("approve", "Expected a boolean.");
+  const common: CommonServer = {
+    name,
+    description:
+      server.description === undefined
+        ? ""
+        : text(server.description, "description").slice(0, 500),
+    timeout: timeout(server.timeout, "timeout"),
+    startupTimeoutMs: timeout(server.startupTimeoutMs, "startupTimeoutMs"),
+    catalogTimeoutMs: timeout(server.catalogTimeoutMs, "catalogTimeoutMs"),
+    approve: server.approve !== false,
+  };
+  const type =
+    server.type === undefined && server.command !== undefined
+      ? "stdio"
+      : server.type;
+  if (type === "stdio") {
+    if (server.url !== undefined || server.headers !== undefined)
+      invalid("type", "Stdio servers cannot use url or headers.");
+    const args = server.args === undefined ? [] : server.args;
+    if (!Array.isArray(args)) invalid("args", "Expected an array of strings.");
+    return {
+      ...common,
+      type,
+      command: expand(server.command, env, "command"),
+      args: args.map((arg) => expand(arg, env, "args", true)),
+      env: strings(server.env === undefined ? {} : server.env, env, "env"),
+      cwd:
+        server.cwd === undefined
+          ? dirname(path)
+          : resolve(dirname(path), expand(server.cwd, env, "cwd")),
+    };
+  }
+  if (type !== "http" && type !== "streamable-http")
+    invalid(
+      "type",
+      "Use stdio, http, or streamable-http. Remote servers require an explicit type.",
+    );
+  if (
+    [server.command, server.args, server.env, server.cwd].some(
+      (value) => value !== undefined,
+    )
+  )
+    invalid("type", "HTTP servers cannot use command, args, env, or cwd.");
+  const url = expand(server.url, env, "url");
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    invalid(
+      "url",
+      "Expected an HTTP(S) URL without credentials or a fragment.",
+    );
+  }
+  if (
+    !["http:", "https:"].includes(parsed.protocol) ||
+    parsed.username ||
+    parsed.password ||
+    parsed.hash
+  )
+    invalid(
+      "url",
+      "Expected an HTTP(S) URL without credentials or a fragment.",
+    );
+  const headers = strings(
+    server.headers === undefined ? {} : server.headers,
+    env,
+    "headers",
+  );
+  try {
+    new Headers(headers);
+  } catch {
+    invalid("headers", "Invalid HTTP header name or value.");
+  }
+  return { ...common, type: "http", url, headers };
+}
 
 export async function readConfig(
   path: string,
@@ -75,107 +245,49 @@ export async function readConfig(
     if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
     throw new Error("Cannot read MCP configuration.");
   }
-  if (Buffer.byteLength(source) > 256 * 1024) invalid();
+  if (Buffer.byteLength(source) > 256 * 1024)
+    invalid(undefined, "Configuration exceeds 256 KiB.");
   let value: unknown;
   try {
     value = JSON.parse(source);
   } catch {
-    invalid();
+    invalid(undefined, "Malformed JSON.");
   }
   const root = object(value);
-  if (Object.keys(root).some((key) => key !== "mcpServers")) invalid();
-  const entries = Object.entries(object(root.mcpServers));
-  if (entries.length > 32) invalid();
+  if (
+    Object.keys(root).some((key) => key !== "mcpServers" && key !== "$schema")
+  )
+    invalid(
+      undefined,
+      "Unsupported root field; use mcpServers and optional $schema.",
+    );
+  // Editor metadata only: never fetch a configuration-provided schema URL.
+  if (root.$schema !== undefined) text(root.$schema, "$schema");
+  const entries = Object.entries(object(root.mcpServers, "mcpServers"));
+  if (entries.length > 32)
+    invalid("mcpServers", "At most 32 servers are supported.");
   const servers: ServerConfig[] = [];
-  for (const [name, raw] of entries) {
-    if (!/^[A-Za-z0-9_-]{1,48}$/.test(name)) invalid();
-    const server = object(raw);
-    const allowed = new Set([
-      "type",
-      "command",
-      "args",
-      "env",
-      "cwd",
-      "url",
-      "headers",
-      "description",
-      "timeoutMs",
-      "approve",
-      "disabled",
-    ]);
-    if (Object.keys(server).some((key) => !allowed.has(key))) invalid();
-    if (server.disabled !== undefined && typeof server.disabled !== "boolean")
-      invalid();
-    if (server.disabled === true) continue;
-    const type =
-      server.type ?? (server.command !== undefined ? "stdio" : "http");
-    const timeoutMs = server.timeoutMs ?? 30_000;
-    if (
-      !Number.isInteger(timeoutMs) ||
-      typeof timeoutMs !== "number" ||
-      timeoutMs < 100 ||
-      timeoutMs > 120_000
-    )
-      invalid();
-    if (server.approve !== undefined && typeof server.approve !== "boolean")
-      invalid();
-    const common: CommonServer = {
-      name,
-      description:
-        server.description === undefined
-          ? ""
-          : text(server.description).slice(0, 500),
-      timeoutMs,
-      approve: server.approve !== false,
-    };
-    if (type === "stdio") {
-      if (server.url !== undefined || server.headers !== undefined) invalid();
-      const args = server.args ?? [];
-      if (
-        !Array.isArray(args) ||
-        args.some((arg) => typeof arg !== "string" || arg.includes("\0"))
-      )
-        invalid();
-      servers.push({
-        ...common,
-        type,
-        command: text(server.command),
-        args,
-        env: strings(server.env ?? {}, env),
-        cwd:
-          server.cwd === undefined
-            ? dirname(path)
-            : resolve(dirname(path), text(server.cwd)),
+  const issues: ConfigIssue[] = [];
+  for (const [index, [name, raw]] of entries.entries()) {
+    try {
+      const server = parseServer(name, raw, path, env);
+      if (server) servers.push(server);
+    } catch (error) {
+      // Invalid names and unknown keys can themselves contain credentials. Only
+      // validated names and our fixed validation messages reach discovery.
+      issues.push({
+        name: /^[A-Za-z0-9_-]{1,48}$/.test(name)
+          ? name
+          : `Invalid server #${index + 1}`,
+        ...(error instanceof ConfigError && error.field
+          ? { field: error.field }
+          : {}),
+        message:
+          error instanceof ConfigError
+            ? error.message
+            : "Invalid MCP configuration. Server could not be validated.",
       });
-    } else if (type === "http") {
-      if (
-        [server.command, server.args, server.env, server.cwd].some(
-          (value) => value !== undefined,
-        )
-      )
-        invalid();
-      const url = text(server.url);
-      let parsed: URL;
-      try {
-        parsed = new URL(url);
-      } catch {
-        invalid();
-      }
-      if (
-        !["http:", "https:"].includes(parsed.protocol) ||
-        parsed.username ||
-        parsed.password ||
-        parsed.hash
-      )
-        invalid();
-      const headers = strings(server.headers ?? {}, env, "headers");
-      try {
-        new Headers(headers);
-      } catch {
-        invalid();
-      }
-      servers.push({ ...common, type, url, headers });
-    } else invalid();
+    }
   }
-  return { path, servers };
+  return { path, servers, issues };
 }

package/src/index.ts

@@ -7,7 +7,7 @@ import type {
 import type { Tool } from "@modelcontextprotocol/sdk/types.js";
 import { compact, entry, search, summary, type Entry } from "./catalog.ts";
 import { Connection } from "./client.ts";
-import { readConfig, type ServerConfig } from "./config.ts";
+import { readConfig, type ConfigIssue, type ServerConfig } from "./config.ts";
 import { formatResult } from "./output.ts";
 import { compileSchema } from "./schema.ts";
 
@@ -18,6 +18,7 @@ interface State {
   loaded: Map<string, string>;
   connections: Map<string, Connection>;
   rejected: Map<string, number>;
+  configIssues: ConfigIssue[];
 }
 
 const discoveryParameters = Type.Object(
@@ -81,6 +82,8 @@ export default function mcp(pi: ExtensionAPI) {
   function catalog(owner: State | undefined): string {
     if (!owner) return "Catalog is initialized when the Pi session starts.";
     const lines = [owner.status];
+    for (const issue of owner.configIssues)
+      lines.push(`${issue.name}: ${issue.message}`);
     for (const connection of owner.connections.values()) {
       const config = connection.config;
       const tools = [...owner.entries.values()].filter(
@@ -124,7 +127,11 @@ export default function mcp(pi: ExtensionAPI) {
         if (!owner) throw new Error("MCP session has not started.");
         current(owner);
         deactivate(hiddenTools());
-        if (args.server && !owner.connections.has(args.server))
+        if (
+          args.server &&
+          !owner.connections.has(args.server) &&
+          !owner.configIssues.some((issue) => issue.name === args.server)
+        )
           throw new Error("Unknown MCP server.");
         const all = [...owner.entries.values()].sort((a, b) =>
           a.name.localeCompare(b.name, "en"),
@@ -178,11 +185,18 @@ export default function mcp(pi: ExtensionAPI) {
         }
         const data = {
           status: owner.status,
-          servers: [...owner.connections.values()].map((connection) => ({
-            name: connection.config.name,
-            status: connection.status,
-            unsupportedTools: owner.rejected.get(connection.config.name) ?? 0,
-          })),
+          servers: [
+            ...owner.configIssues.map((issue) => ({
+              name: issue.name,
+              status: issue.message,
+              unsupportedTools: 0,
+            })),
+            ...[...owner.connections.values()].map((connection) => ({
+              name: connection.config.name,
+              status: connection.status,
+              unsupportedTools: owner.rejected.get(connection.config.name) ?? 0,
+            })),
+          ],
           items: selected.map((item) => ({
             ...summary(item),
             active: active.has(item.name),
@@ -335,6 +349,7 @@ export default function mcp(pi: ExtensionAPI) {
       loaded: new Map(),
       connections: new Map(),
       rejected: new Map(),
+      configIssues: [],
     };
     state = owner;
     try {
@@ -363,7 +378,15 @@ export default function mcp(pi: ExtensionAPI) {
           "MCP configuration not trusted. Review it, then restart with --mcp-trust-config or --mcp-config <path>.";
         return;
       }
-      owner.status = "Use list/search/load to discover and activate tools.";
+      owner.configIssues = config.issues;
+      owner.status =
+        config.issues.length > 0
+          ? config.servers.length > 0
+            ? "Some MCP servers have invalid configuration; valid servers remain available. Use list/search/load to discover and activate tools."
+            : "No valid MCP servers configured. Correct configuration errors and reload Pi."
+          : config.servers.length > 0
+            ? "Use list/search/load to discover and activate tools."
+            : "No enabled MCP servers configured.";
       for (const server of config.servers) {
         owner.connections.set(
           server.name,