@pi-harness/pi-harness 0.1.13 → 0.1.14

package/packages/core/dist/plugins/mcp-client.js

@@ -1,28 +1,470 @@
 import { spawn } from "node:child_process";
-import { basename } from "node:path";
 import z from "@deepseek-ai/schemastery";
 import { Type } from "@earendil-works/pi-ai";
 import { defineTool } from "@earendil-works/pi-coding-agent";
+import packageMetadata from "../../package.json" with { type: "json" };
+import { assertKnownConfigKeys } from "../config.js";
 export const Config = z.object({
     servers: z.array(z.object({ id: z.string(), command: z.array(z.string()), autoStart: z.boolean().default(false) })).default([]),
 });
 const shellCommands = new Set(["sh", "bash", "zsh", "fish", "cmd", "powershell", "pwsh"]);
 const maxCommandArgs = 32;
 const maxArgumentBytes = 4096;
+const maxToolArgumentsBytes = 64 * 1024;
+const maxToolArgumentDepth = 32;
+const maxResponseBytes = 1024 * 1024;
+const maxInventoryItems = 1000;
+const maxPaginationPages = 100;
+const maxManagedServers = 128;
+const maxStderrBytes = 8192;
 const requestTimeoutMs = 30_000;
+const maxPanelItems = 20;
+const clientVersion = packageMetadata.version;
+const disposedMessage = "MCP client plugin disposed";
+const connectionParameterNames = new Set(["command", "serverId"]);
+const callParameterNames = new Set(["command", "serverId", "name", "arguments"]);
+const stopParameterNames = new Set(["serverId"]);
+const readResourceParameterNames = new Set(["command", "serverId", "uri"]);
+const noParameterNames = new Set();
+const utf8Decoder = new TextDecoder("utf-8", { fatal: true });
+function decodeFrame(value) {
+    try {
+        return utf8Decoder.decode(value);
+    }
+    catch (error) {
+        throw new Error("MCP server response must contain valid UTF-8", { cause: error });
+    }
+}
+function inspectParameters(value, allowed) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        throw new Error("MCP parameters must be an object");
+    try {
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null)
+            throw new Error("MCP parameters must be a plain object");
+        const descriptors = Object.getOwnPropertyDescriptors(value);
+        if (Reflect.ownKeys(descriptors).some((key) => typeof key !== "string" || !allowed.has(key)))
+            throw new Error("MCP parameters contain an unknown property");
+        if (Object.values(descriptors).some((descriptor) => !("value" in descriptor)))
+            throw new Error("MCP parameters must use data properties");
+        return Object.fromEntries(Object.entries(descriptors).map(([key, descriptor]) => [key, descriptor.value]));
+    }
+    catch (error) {
+        if (error instanceof Error &&
+            /^(?:MCP parameters must be a plain object|MCP parameters contain an unknown property|MCP parameters must use data properties)$/u.test(error.message))
+            throw error;
+        throw new Error("MCP parameters must be an accessible plain object", { cause: error });
+    }
+}
+function optionalString(value, field) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "string")
+        throw new Error(`MCP ${field} must be a string`);
+    return value;
+}
+function requiredString(value, field) {
+    const result = optionalString(value, field);
+    if (result === undefined)
+        throw new Error(`MCP ${field} is required`);
+    return result;
+}
+function serverIdValue(value, required = false) {
+    const result = optionalString(value, "serverId");
+    if (result === undefined) {
+        if (required)
+            throw new Error("MCP serverId is required");
+        return undefined;
+    }
+    if (!/^[a-z0-9][a-z0-9_-]{0,63}$/iu.test(result))
+        throw new Error("MCP serverId must use 1-64 letters, numbers, _ or -");
+    return result;
+}
+function boundedInput(value, field, maximum) {
+    if (value.includes("\0"))
+        throw new Error(`MCP ${field} must not contain NUL characters`);
+    if (value.length === 0 || value.length > maximum)
+        throw new Error(`MCP ${field} must contain 1-${maximum} characters`);
+    return value;
+}
+function rejectAmbiguousTarget(command, serverId) {
+    if (command !== undefined && serverId !== undefined)
+        throw new Error("Provide either command or serverId, not both");
+}
+function optionalCommand(value) {
+    if (value === undefined)
+        return undefined;
+    if (!Array.isArray(value))
+        throw new Error("MCP command must be an array of strings");
+    const descriptors = Object.getOwnPropertyDescriptors(value);
+    const length = descriptors.length?.value;
+    if (typeof length !== "number" || !Number.isSafeInteger(length) || length < 0)
+        throw new Error("MCP command must be a dense array of string data properties");
+    const result = [];
+    for (let index = 0; index < length; index += 1) {
+        const descriptor = descriptors[String(index)];
+        if (descriptor === undefined || !("value" in descriptor) || typeof descriptor.value !== "string")
+            throw new Error("MCP command must be a dense array of string data properties");
+        result.push(descriptor.value);
+    }
+    if (Reflect.ownKeys(descriptors).some((key) => typeof key !== "string" || (key !== "length" && !/^(0|[1-9]\d*)$/u.test(key))))
+        throw new Error("MCP command contains an unknown property");
+    return result;
+}
+function jsonObject(value) {
+    if (value === undefined)
+        return {};
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        throw new Error("MCP arguments must be a JSON object");
+    const result = cloneJsonValue(value, new Set(), 0);
+    if (Buffer.byteLength(JSON.stringify(result), "utf8") > maxToolArgumentsBytes)
+        throw new Error("MCP arguments cannot exceed 64 KiB");
+    return result;
+}
+function promptArguments(value) {
+    const result = jsonObject(value);
+    if (Object.values(result).some((item) => typeof item !== "string"))
+        throw new Error("MCP prompt arguments must contain string values");
+    return result;
+}
+function cloneJsonValue(value, ancestors, depth) {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return value;
+    if (typeof value === "number") {
+        if (!Number.isFinite(value))
+            throw new Error("MCP arguments must contain finite JSON numbers");
+        return value;
+    }
+    if (typeof value !== "object")
+        throw new Error("MCP arguments must contain only JSON values");
+    if (depth > maxToolArgumentDepth)
+        throw new Error(`MCP arguments cannot exceed ${maxToolArgumentDepth} levels of nesting`);
+    if (ancestors.has(value))
+        throw new Error("MCP arguments must not contain circular references");
+    ancestors.add(value);
+    try {
+        const descriptors = Object.getOwnPropertyDescriptors(value);
+        if (Object.values(descriptors).some((descriptor) => !("value" in descriptor)))
+            throw new Error("MCP arguments must use data properties");
+        if (Reflect.ownKeys(descriptors).some((key) => typeof key !== "string"))
+            throw new Error("MCP arguments cannot contain symbol properties");
+        if (Array.isArray(value)) {
+            const length = descriptors.length?.value;
+            if (typeof length !== "number" || !Number.isSafeInteger(length) || length < 0)
+                throw new Error("MCP argument arrays must be dense");
+            const result = [];
+            for (let index = 0; index < length; index += 1) {
+                const descriptor = descriptors[String(index)];
+                if (descriptor === undefined || !("value" in descriptor))
+                    throw new Error("MCP argument arrays must be dense");
+                result.push(cloneJsonValue(descriptor.value, ancestors, depth + 1));
+            }
+            if (Object.keys(descriptors).some((key) => key !== "length" && !/^(0|[1-9]\d*)$/u.test(key)))
+                throw new Error("MCP argument arrays contain an unknown property");
+            return result;
+        }
+        const result = {};
+        for (const [key, descriptor] of Object.entries(descriptors)) {
+            if (descriptor.enumerable !== true)
+                continue;
+            result[key] = cloneJsonValue(descriptor.value, ancestors, depth + 1);
+        }
+        return result;
+    }
+    finally {
+        ancestors.delete(value);
+    }
+}
+function executionSignal(signal, lifecycle) {
+    return signal === undefined ? lifecycle : AbortSignal.any([signal, lifecycle]);
+}
+function clone(value) {
+    return structuredClone(value);
+}
+function appendByteTail(current, chunk, maximum) {
+    const combined = Buffer.concat([current, chunk]);
+    return combined.byteLength <= maximum ? combined : combined.subarray(combined.byteLength - maximum);
+}
+function toolInventory(value) {
+    if (!Array.isArray(value))
+        throw new Error("MCP server returned an invalid MCP tools inventory");
+    if (value.length > maxInventoryItems)
+        throw new Error(`MCP remote inventory cannot exceed ${maxInventoryItems} items`);
+    return value.map((item) => {
+        if (item === null || typeof item !== "object" || Array.isArray(item))
+            throw new Error("MCP server returned an invalid MCP tool descriptor");
+        const raw = item;
+        if (typeof raw.name !== "string" || raw.name.length === 0 || raw.name.length > 512 || raw.name.includes("\0"))
+            throw new Error("MCP server returned an invalid MCP tool descriptor");
+        if (raw.description !== undefined && (typeof raw.description !== "string" || raw.description.length > 8192))
+            throw new Error("MCP server returned an invalid MCP tool descriptor");
+        if (raw.inputSchema === null || typeof raw.inputSchema !== "object" || Array.isArray(raw.inputSchema))
+            throw new Error("MCP server returned an invalid MCP tool descriptor");
+        return {
+            name: raw.name,
+            ...(raw.description === undefined ? {} : { description: raw.description }),
+            inputSchema: clone(raw.inputSchema),
+        };
+    });
+}
+function resourceInventory(value) {
+    if (!Array.isArray(value))
+        throw new Error("MCP server returned an invalid MCP resources inventory");
+    if (value.length > maxInventoryItems)
+        throw new Error(`MCP remote inventory cannot exceed ${maxInventoryItems} items`);
+    return value.map((item) => {
+        if (item === null || typeof item !== "object" || Array.isArray(item))
+            throw new Error("MCP server returned an invalid MCP resource descriptor");
+        const raw = item;
+        if (typeof raw.uri !== "string" || raw.uri.length === 0 || raw.uri.length > 4096 || raw.uri.includes("\0"))
+            throw new Error("MCP server returned an invalid MCP resource descriptor");
+        if (typeof raw.name !== "string" || raw.name.length === 0 || raw.name.length > 512 || raw.name.includes("\0"))
+            throw new Error("MCP server returned an invalid MCP resource descriptor");
+        if (raw.description !== undefined && (typeof raw.description !== "string" || raw.description.length > 8192))
+            throw new Error("MCP server returned an invalid MCP resource descriptor");
+        if (raw.mimeType !== undefined && (typeof raw.mimeType !== "string" || raw.mimeType.length > 256))
+            throw new Error("MCP server returned an invalid MCP resource descriptor");
+        return {
+            uri: raw.uri,
+            name: raw.name,
+            ...(raw.description === undefined ? {} : { description: raw.description }),
+            ...(raw.mimeType === undefined ? {} : { mimeType: raw.mimeType }),
+        };
+    });
+}
+function promptInventory(value) {
+    if (!Array.isArray(value))
+        throw new Error("MCP server returned an invalid MCP prompts inventory");
+    if (value.length > maxInventoryItems)
+        throw new Error(`MCP remote inventory cannot exceed ${maxInventoryItems} items`);
+    return value.map((item) => {
+        if (item === null || typeof item !== "object" || Array.isArray(item))
+            throw new Error("MCP server returned an invalid MCP prompt descriptor");
+        const raw = item;
+        if (typeof raw.name !== "string" || raw.name.length === 0 || raw.name.length > 512 || raw.name.includes("\0"))
+            throw new Error("MCP server returned an invalid MCP prompt descriptor");
+        if (raw.description !== undefined && (typeof raw.description !== "string" || raw.description.length > 8192))
+            throw new Error("MCP server returned an invalid MCP prompt descriptor");
+        if (raw.arguments !== undefined && !Array.isArray(raw.arguments))
+            throw new Error("MCP server returned an invalid MCP prompt descriptor");
+        if (Array.isArray(raw.arguments) && raw.arguments.length > 128)
+            throw new Error("MCP server returned an invalid MCP prompt descriptor");
+        const argumentsValue = Array.isArray(raw.arguments)
+            ? raw.arguments.map((argument) => {
+                if (argument === null || typeof argument !== "object" || Array.isArray(argument))
+                    throw new Error("MCP server returned an invalid MCP prompt descriptor");
+                const candidate = argument;
+                if (typeof candidate.name !== "string" || candidate.name.length === 0 || candidate.name.length > 512)
+                    throw new Error("MCP server returned an invalid MCP prompt descriptor");
+                if (candidate.description !== undefined && (typeof candidate.description !== "string" || candidate.description.length > 8192))
+                    throw new Error("MCP server returned an invalid MCP prompt descriptor");
+                if (candidate.required !== undefined && typeof candidate.required !== "boolean")
+                    throw new Error("MCP server returned an invalid MCP prompt descriptor");
+                return {
+                    name: candidate.name,
+                    ...(candidate.description === undefined ? {} : { description: candidate.description }),
+                    ...(candidate.required === undefined ? {} : { required: candidate.required }),
+                };
+            })
+            : undefined;
+        return {
+            name: raw.name,
+            ...(raw.description === undefined ? {} : { description: raw.description }),
+            ...(argumentsValue === undefined ? {} : { arguments: argumentsValue }),
+        };
+    });
+}
+function paginationCursor(value) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "string" || value.length === 0 || value.length > 4096 || value.includes("\0"))
+        throw new Error("MCP server returned an invalid pagination cursor");
+    return value;
+}
+async function paginatedInventory(method, field, requestPage, validate) {
+    const result = [];
+    const seenCursors = new Set();
+    let cursor;
+    for (let page = 0; page < maxPaginationPages; page += 1) {
+        const response = await requestPage(cursor === undefined ? undefined : { cursor });
+        const pageItems = validate(response[field]);
+        if (result.length + pageItems.length > maxInventoryItems)
+            throw new Error(`MCP remote inventory cannot exceed ${maxInventoryItems} items`);
+        result.push(...pageItems);
+        const nextCursor = paginationCursor(response.nextCursor);
+        if (nextCursor === undefined)
+            return result;
+        if (seenCursors.has(nextCursor))
+            throw new Error(`MCP server repeated a pagination cursor for ${method}`);
+        seenCursors.add(nextCursor);
+        cursor = nextCursor;
+    }
+    throw new Error(`MCP ${method} pagination cannot exceed ${maxPaginationPages} pages`);
+}
+function requiredRemoteString(value, message, maximum = maxResponseBytes) {
+    if (typeof value !== "string" || value.length > maximum || value.includes("\0"))
+        throw new Error(message);
+    return value;
+}
+function base64RemoteString(value, message) {
+    const result = requiredRemoteString(value, message);
+    if (!/^(?:[A-Za-z\d+/]{4})*(?:[A-Za-z\d+/]{2}(?:==)?|[A-Za-z\d+/]{3}=?)?$/u.test(result))
+        throw new Error(message);
+    return result;
+}
+function toolResultContent(result) {
+    if (!Array.isArray(result.content) || result.content.length > maxInventoryItems)
+        throw new Error("MCP server returned invalid MCP tool result content");
+    if (result.isError !== undefined && typeof result.isError !== "boolean")
+        throw new Error("MCP server returned invalid MCP tool result content");
+    return result.content.map((item) => {
+        if (item === null || typeof item !== "object" || Array.isArray(item))
+            throw new Error("MCP server returned invalid MCP tool result content");
+        const raw = item;
+        if (raw.type === "text") {
+            return { type: "text", text: requiredRemoteString(raw.text, "MCP server returned invalid MCP tool result content") };
+        }
+        if (raw.type === "image") {
+            const data = base64RemoteString(raw.data, "MCP server returned invalid MCP tool result content");
+            const mimeType = requiredRemoteString(raw.mimeType, "MCP server returned invalid MCP tool result content", 256);
+            if (!mimeType.startsWith("image/"))
+                throw new Error("MCP server returned invalid MCP tool result content");
+            return { type: "image", data, mimeType };
+        }
+        if (raw.type === "audio") {
+            const mimeType = requiredRemoteString(raw.mimeType, "MCP server returned invalid MCP tool result content", 256);
+            base64RemoteString(raw.data, "MCP server returned invalid MCP tool result content");
+            return { type: "text", text: `[MCP audio content omitted: ${mimeType}]` };
+        }
+        if (raw.type === "resource") {
+            if (raw.resource === null || typeof raw.resource !== "object" || Array.isArray(raw.resource))
+                throw new Error("MCP server returned invalid MCP tool result content");
+            const resource = raw.resource;
+            const uri = requiredRemoteString(resource.uri, "MCP server returned invalid MCP tool result content", 4096);
+            if (typeof resource.text === "string")
+                return { type: "text", text: resource.text };
+            if (typeof resource.blob === "string") {
+                const blob = base64RemoteString(resource.blob, "MCP server returned invalid MCP tool result content");
+                const mimeType = resource.mimeType === undefined ? undefined : requiredRemoteString(resource.mimeType, "MCP server returned invalid MCP tool result content", 256);
+                return mimeType?.startsWith("image/") === true
+                    ? { type: "image", data: blob, mimeType }
+                    : { type: "text", text: `[MCP binary resource omitted: ${uri} (${mimeType ?? "unknown MIME type"})]` };
+            }
+            throw new Error("MCP server returned invalid MCP tool result content");
+        }
+        if (raw.type === "resource_link") {
+            const uri = requiredRemoteString(raw.uri, "MCP server returned invalid MCP tool result content", 4096);
+            const name = raw.name === undefined ? uri : requiredRemoteString(raw.name, "MCP server returned invalid MCP tool result content", 512);
+            return { type: "text", text: `[MCP resource: ${name} — ${uri}]` };
+        }
+        throw new Error("MCP server returned invalid MCP tool result content");
+    });
+}
+function validateInitializeResult(result) {
+    if (result.protocolVersion !== "2025-06-18" ||
+        result.capabilities === null ||
+        typeof result.capabilities !== "object" ||
+        Array.isArray(result.capabilities) ||
+        result.serverInfo === null ||
+        typeof result.serverInfo !== "object" ||
+        Array.isArray(result.serverInfo))
+        throw new Error("MCP server returned an invalid MCP initialize result");
+    const serverInfo = result.serverInfo;
+    if (typeof serverInfo.name !== "string" ||
+        serverInfo.name.length === 0 ||
+        serverInfo.name.length > 512 ||
+        typeof serverInfo.version !== "string" ||
+        serverInfo.version.length === 0 ||
+        serverInfo.version.length > 512 ||
+        (result.instructions !== undefined && (typeof result.instructions !== "string" || result.instructions.length > 65_536)))
+        throw new Error("MCP server returned an invalid MCP initialize result");
+}
+function resourceResultContent(result) {
+    if (!Array.isArray(result.contents) || result.contents.length > maxInventoryItems)
+        throw new Error("MCP server returned invalid MCP resource contents");
+    return result.contents.map((item) => {
+        if (item === null || typeof item !== "object" || Array.isArray(item))
+            throw new Error("MCP server returned invalid MCP resource contents");
+        const raw = item;
+        const uri = requiredRemoteString(raw.uri, "MCP server returned invalid MCP resource contents", 4096);
+        if (typeof raw.text === "string")
+            return { type: "text", text: raw.text };
+        if (typeof raw.blob === "string") {
+            const blob = base64RemoteString(raw.blob, "MCP server returned invalid MCP resource contents");
+            const mimeType = raw.mimeType === undefined ? undefined : requiredRemoteString(raw.mimeType, "MCP server returned invalid MCP resource contents", 256);
+            return mimeType?.startsWith("image/") === true
+                ? { type: "image", data: blob, mimeType }
+                : { type: "text", text: `[MCP binary resource omitted: ${uri} (${mimeType ?? "unknown MIME type"})]` };
+        }
+        throw new Error("MCP server returned invalid MCP resource contents");
+    });
+}
+function promptResultContent(result) {
+    if (result.description !== undefined && (typeof result.description !== "string" || result.description.length > 8192))
+        throw new Error("MCP server returned invalid MCP prompt messages");
+    if (!Array.isArray(result.messages) || result.messages.length > maxInventoryItems)
+        throw new Error("MCP server returned invalid MCP prompt messages");
+    return result.messages.flatMap((item) => {
+        if (item === null || typeof item !== "object" || Array.isArray(item))
+            throw new Error("MCP server returned invalid MCP prompt messages");
+        const raw = item;
+        const role = raw.role;
+        if (role !== "user" && role !== "assistant")
+            throw new Error("MCP server returned invalid MCP prompt messages");
+        const normalized = toolResultContent({ content: [raw.content] });
+        return normalized.flatMap((content) => content.type === "text" ? [{ type: "text", text: `[${role}]\n${content.text}` }] : [{ type: "text", text: `[${role}]` }, content]);
+    });
+}
 function validateCommand(command) {
     if (command.length === 0)
         throw new Error("MCP server command cannot be empty");
     if (command.length > maxCommandArgs)
         throw new Error(`MCP server command cannot exceed ${maxCommandArgs} arguments`);
+    if (command.some((part) => part.includes("\0")))
+        throw new Error("MCP server command arguments must not contain NUL characters");
     if (command.some((part) => part.length === 0 || Buffer.byteLength(part) > maxArgumentBytes))
         throw new Error("MCP server command contains an invalid argument");
-    if (shellCommands.has(basename(command[0] ?? "").toLowerCase()))
+    const executable = executableName(command)
+        .toLowerCase()
+        .replace(/\.(?:exe|cmd|bat|com)$/u, "");
+    if (shellCommands.has(executable))
         throw new Error("MCP shell wrappers are not allowed; pass an executable argv directly");
 }
+function executableName(command) {
+    return (command[0] ?? "").replaceAll("\\", "/").split("/").pop() ?? "";
+}
+function serverLabel(command) {
+    const count = Math.max(0, command.length - 1);
+    return `${executableName(command)}${count === 0 ? "" : ` (+${count} ${count === 1 ? "arg" : "args"})`}`;
+}
 function encodeMessage(message) {
-    const payload = Buffer.from(JSON.stringify(message), "utf8");
-    return Buffer.concat([Buffer.from(`Content-Length: ${payload.byteLength}\r\n\r\n`, "ascii"), payload]);
+    return Buffer.from(`${JSON.stringify(message)}\n`, "utf8");
+}
+function waitForChildClose(child, timeoutMs) {
+    if (child.exitCode !== null || child.signalCode !== null)
+        return Promise.resolve(true);
+    return new Promise((resolve) => {
+        const onClose = () => finish(true);
+        const timer = setTimeout(() => finish(false), timeoutMs);
+        timer.unref();
+        const finish = (closed) => {
+            clearTimeout(timer);
+            child.off("close", onClose);
+            resolve(closed);
+        };
+        child.once("close", onClose);
+    });
+}
+async function terminateChild(child) {
+    if (!child.stdin.destroyed && !child.stdin.writableEnded)
+        child.stdin.end();
+    if (child.exitCode !== null || child.signalCode !== null)
+        return;
+    child.kill("SIGTERM");
+    if (await waitForChildClose(child, 250))
+        return;
+    child.kill("SIGKILL");
+    await waitForChildClose(child, 500);
 }
 function parseFrames(buffer) {
     const messages = [];
@@ -37,10 +479,12 @@ function parseFrames(buffer) {
             if (match === null)
                 throw new Error("MCP server returned an invalid Content-Length header");
             const length = Number(match[1]);
+            if (!Number.isSafeInteger(length) || length > maxResponseBytes)
+                throw new Error("MCP server response exceeded the 1 MiB limit");
             const bodyStart = separator + 4;
             if (rest.length < bodyStart + length)
                 break;
-            const body = rest.subarray(bodyStart, bodyStart + length).toString("utf8");
+            const body = decodeFrame(rest.subarray(bodyStart, bodyStart + length));
             const message = JSON.parse(body);
             if (typeof message === "object" && message !== null)
                 messages.push(message);
@@ -50,7 +494,7 @@ function parseFrames(buffer) {
         const newline = rest.indexOf(10);
         if (newline < 0)
             break;
-        const line = rest.subarray(0, newline).toString("utf8").trim();
+        const line = decodeFrame(rest.subarray(0, newline)).trim();
         rest = rest.subarray(newline + 1);
         if (line === "")
             continue;
@@ -65,81 +509,201 @@ function parseFrames(buffer) {
     }
     return { messages, rest };
 }
-async function request(child, id, method, params) {
+function cancellationError(method, reason) {
+    if (reason instanceof Error && reason.message === disposedMessage)
+        return reason;
+    return new Error(`MCP request was cancelled: ${method}${reason instanceof Error ? ` (${reason.message})` : ""}`, { cause: reason });
+}
+function withCancellation(operation, signal, method) {
+    if (signal === undefined)
+        return operation;
+    if (signal.aborted)
+        return Promise.reject(cancellationError(method, signal.reason));
     return new Promise((resolve, reject) => {
-        let buffer = Buffer.alloc(0);
-        const timer = setTimeout(() => {
-            cleanup();
-            reject(new Error(`MCP request timed out: ${method}`));
-        }, requestTimeoutMs);
-        const onData = (chunk) => {
-            buffer = Buffer.concat([buffer, chunk]);
-            let parsed;
+        const onAbort = () => {
+            signal.removeEventListener("abort", onAbort);
+            reject(cancellationError(method, signal.reason));
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+        void operation.then((value) => {
+            signal.removeEventListener("abort", onAbort);
+            resolve(value);
+        }, (error) => {
+            signal.removeEventListener("abort", onAbort);
+            reject(error instanceof Error ? error : new Error("MCP operation failed", { cause: error }));
+        });
+    });
+}
+const stdioRouters = new WeakMap();
+function responseResult(message) {
+    const hasError = Object.hasOwn(message, "error");
+    const hasResult = Object.hasOwn(message, "result");
+    if (message.jsonrpc !== "2.0" || hasError === hasResult)
+        throw new Error("MCP server returned an invalid JSON-RPC response");
+    if (hasError) {
+        if (typeof message.error !== "object" || message.error === null || Array.isArray(message.error))
+            throw new Error("MCP server returned an invalid JSON-RPC response");
+        const errorMessage = message.error.message;
+        const errorCode = message.error.code;
+        if (typeof errorMessage !== "string" || typeof errorCode !== "number" || !Number.isInteger(errorCode))
+            throw new Error("MCP server returned an invalid JSON-RPC response");
+        throw new Error(errorMessage);
+    }
+    if (typeof message.result !== "object" || message.result === null || Array.isArray(message.result))
+        throw new Error("MCP server returned an invalid response");
+    return message.result;
+}
+function stdioRouter(child) {
+    const existing = stdioRouters.get(child);
+    if (existing !== undefined)
+        return existing;
+    const router = { buffer: Buffer.alloc(0), pending: new Map() };
+    const fail = (error) => {
+        if (router.terminalError !== undefined)
+            return;
+        router.terminalError = error;
+        router.buffer = Buffer.alloc(0);
+        child.stdout.off("data", onData);
+        child.off("error", onError);
+        child.off("close", onClose);
+        for (const request of [...router.pending.values()])
+            request.reject(error);
+    };
+    const onData = (chunk) => {
+        for (const request of [...router.pending.values()]) {
+            request.receivedBytes += chunk.byteLength;
+            if (request.receivedBytes > maxResponseBytes)
+                request.reject(new Error("MCP server response exceeded the 1 MiB limit"));
+        }
+        if (router.buffer.byteLength + chunk.byteLength > maxResponseBytes) {
+            fail(new Error("MCP server response exceeded the 1 MiB limit"));
+            return;
+        }
+        const buffer = router.buffer.byteLength === 0 ? chunk : Buffer.concat([router.buffer, chunk]);
+        let parsed;
+        try {
+            parsed = parseFrames(buffer);
+        }
+        catch (error) {
+            fail(error instanceof Error ? error : new Error("Failed to parse MCP response", { cause: error }));
+            return;
+        }
+        router.buffer = parsed.rest.byteLength === 0 ? Buffer.alloc(0) : Buffer.from(parsed.rest);
+        for (const message of parsed.messages) {
+            if (typeof message.id !== "number")
+                continue;
+            const request = router.pending.get(message.id);
+            if (request === undefined)
+                continue;
             try {
-                parsed = parseFrames(buffer);
+                request.resolve(responseResult(message));
             }
             catch (error) {
-                cleanup();
-                reject(error instanceof Error ? error : new Error("Failed to parse MCP response", { cause: error }));
-                return;
+                request.reject(error instanceof Error ? error : new Error("Failed to validate MCP response", { cause: error }));
             }
-            buffer = parsed.rest;
-            for (const message of parsed.messages) {
-                if (message.id !== id)
-                    continue;
-                cleanup();
-                if (typeof message.error === "object" && message.error !== null) {
-                    const errorMessage = message.error.message;
-                    reject(new Error(typeof errorMessage === "string" ? errorMessage : "MCP request failed"));
-                }
-                else if (typeof message.result === "object" && message.result !== null)
-                    resolve(message.result);
-                else
-                    reject(new Error("MCP server returned an invalid response"));
+        }
+    };
+    const onError = (error) => fail(error);
+    const onClose = (code) => fail(new Error(`MCP server exited before responding${code === null ? "" : ` (code ${code})`}`));
+    child.stdout.on("data", onData);
+    child.once("error", onError);
+    child.once("close", onClose);
+    stdioRouters.set(child, router);
+    return router;
+}
+async function request(child, id, method, params, signal) {
+    if (signal?.aborted === true)
+        throw cancellationError(method, signal.reason);
+    return new Promise((resolve, reject) => {
+        const router = stdioRouter(child);
+        if (router.terminalError !== undefined) {
+            reject(router.terminalError);
+            return;
+        }
+        if (router.pending.has(id)) {
+            reject(new Error(`MCP request id is already pending: ${id}`));
+            return;
+        }
+        let settled = false;
+        let sent = false;
+        const sendCancellation = (reason) => {
+            if (!sent || method === "initialize" || child.stdin.destroyed || child.stdin.writableEnded)
                 return;
+            try {
+                child.stdin.write(encodeMessage({ jsonrpc: "2.0", method: "notifications/cancelled", params: { requestId: id, reason } }), () => undefined);
+            }
+            catch {
+                // The original timeout or cancellation remains the actionable error.
             }
         };
-        const onError = (error) => {
-            cleanup();
-            reject(error);
-        };
-        const onClose = (code) => {
-            cleanup();
-            reject(new Error(`MCP server exited before responding${code === null ? "" : ` (code ${code})`}`));
+        const timer = setTimeout(() => {
+            sendCancellation(`MCP request timed out: ${method}`);
+            rejectRequest(new Error(`MCP request timed out: ${method}`));
+        }, requestTimeoutMs);
+        timer.unref();
+        const onAbort = () => {
+            sendCancellation(signal?.reason instanceof Error ? signal.reason.message : "MCP client request cancelled");
+            rejectRequest(cancellationError(method, signal?.reason));
         };
         const cleanup = () => {
             clearTimeout(timer);
-            child.stdout.off("data", onData);
-            child.off("error", onError);
-            child.off("close", onClose);
+            router.pending.delete(id);
+            signal?.removeEventListener("abort", onAbort);
         };
-        child.stdout.on("data", onData);
-        child.once("error", onError);
-        child.once("close", onClose);
-        child.stdin.write(encodeMessage({ jsonrpc: "2.0", id, method, ...(params === undefined ? {} : { params }) }));
+        const resolveRequest = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            resolve(value);
+        };
+        const rejectRequest = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            reject(error);
+        };
+        router.pending.set(id, { receivedBytes: 0, resolve: resolveRequest, reject: rejectRequest });
+        signal?.addEventListener("abort", onAbort, { once: true });
+        try {
+            child.stdin.write(encodeMessage({ jsonrpc: "2.0", id, method, ...(params === undefined ? {} : { params }) }), (error) => {
+                if (error === null || error === undefined)
+                    return;
+                rejectRequest(error);
+            });
+            sent = true;
+        }
+        catch (error) {
+            rejectRequest(error instanceof Error ? error : new Error("Failed to write MCP request", { cause: error }));
+        }
     });
 }
-async function withServer(command, cwd, callback) {
+async function withServer(command, cwd, callback, signal) {
     validateCommand(command);
+    if (signal?.aborted === true)
+        throw cancellationError("initialize", signal.reason);
     const child = spawn(command[0], command.slice(1), { cwd, shell: false, stdio: ["pipe", "pipe", "pipe"] });
-    let stderr = "";
-    child.stderr.setEncoding("utf8");
+    let stderr = Buffer.alloc(0);
     child.stderr.on("data", (chunk) => {
-        stderr = `${stderr}${chunk}`.slice(-8_000);
+        stderr = appendByteTail(stderr, chunk, maxStderrBytes);
     });
     try {
-        await request(child, 1, "initialize", { protocolVersion: "2025-06-18", capabilities: {}, clientInfo: { name: "pi-harness", version: "0.1.2" } });
+        const initializeResult = await request(child, 1, "initialize", { protocolVersion: "2025-06-18", capabilities: {}, clientInfo: { name: "pi-harness", version: clientVersion } }, signal);
+        validateInitializeResult(initializeResult);
         child.stdin.write(encodeMessage({ jsonrpc: "2.0", method: "notifications/initialized" }));
         return await callback(child);
     }
     catch (error) {
-        if (error instanceof Error && stderr.trim() !== "")
-            throw new Error(`${error.message}: ${stderr.trim()}`, { cause: error });
+        if (error instanceof Error && error.message === disposedMessage)
+            throw error;
+        const stderrText = stderr.toString("utf8").trim();
+        if (error instanceof Error && stderrText !== "")
+            throw new Error(`${error.message}: ${stderrText}`, { cause: error });
         throw error;
     }
     finally {
-        child.stdin.end();
-        child.kill();
+        await terminateChild(child);
     }
 }
 export default {
@@ -147,28 +711,70 @@ export default {
     inject: ["piHarnessLaunch", "piPluginUi", "piTools"],
     Config,
     async apply(context, config) {
+        assertKnownConfigKeys("pi-mcp-client", config, ["servers"]);
+        const lifecycle = new AbortController();
         let latest;
+        let latestKey;
+        const previousFor = (key) => (latestKey === key ? latest : undefined);
+        const publishLatest = (key, value) => {
+            latestKey = key;
+            latest = clone(value);
+            return clone(value);
+        };
         const servers = new Map();
+        const startingServers = new Set();
+        const unregisters = [];
+        const registerTool = (definition) => {
+            try {
+                const unregister = context.piTools.register(definition);
+                unregisters.push(unregister);
+                return unregister;
+            }
+            catch (error) {
+                for (const unregister of unregisters.splice(0).reverse())
+                    unregister();
+                lifecycle.abort(new Error("MCP client plugin activation failed", { cause: error }));
+                throw error;
+            }
+        };
         const configured = new Map();
-        for (const definition of config.servers ?? []) {
-            if (definition.id.trim() === "")
-                throw new Error("Configured MCP server id cannot be empty");
-            if (configured.has(definition.id))
-                throw new Error(`Configured MCP server id is duplicated: ${definition.id}`);
+        const definitions = config.servers ?? [];
+        if (definitions.length > maxManagedServers)
+            throw new Error(`MCP configured inventory cannot exceed ${maxManagedServers} servers`);
+        for (const definition of definitions) {
+            const id = serverIdValue(definition.id, true);
+            if (configured.has(id))
+                throw new Error(`Configured MCP server id is duplicated: ${id}`);
             validateCommand(definition.command);
-            configured.set(definition.id, { id: definition.id, command: [...definition.command], autoStart: definition.autoStart === true });
+            configured.set(id, { id, command: [...definition.command], autoStart: definition.autoStart === true });
         }
         let nextServerId = 1;
-        const startServer = async (command, requestedId) => {
+        const startServer = async (command, requestedId, signal) => {
             validateCommand(command);
-            const id = requestedId ?? `mcp-${nextServerId++}`;
+            let id = requestedId;
+            if (id === undefined) {
+                do
+                    id = `mcp-${nextServerId++}`;
+                while (configured.has(id) || servers.has(id) || startingServers.has(id));
+            }
             if (servers.has(id))
                 throw new Error(`MCP server is already running: ${id}`);
-            const child = spawn(command[0], command.slice(1), { cwd: context.piHarnessLaunch.cwd, shell: false, stdio: ["pipe", "pipe", "pipe"] });
-            let stderr = "";
-            child.stderr.setEncoding("utf8");
+            if (startingServers.has(id))
+                throw new Error(`MCP server is already starting: ${id}`);
+            if (servers.size + startingServers.size >= maxManagedServers)
+                throw new Error(`MCP client cannot manage more than ${maxManagedServers} running servers`);
+            startingServers.add(id);
+            let child;
+            try {
+                child = spawn(command[0], command.slice(1), { cwd: context.piHarnessLaunch.cwd, shell: false, stdio: ["pipe", "pipe", "pipe"] });
+            }
+            catch (error) {
+                startingServers.delete(id);
+                throw error;
+            }
+            let stderr = Buffer.alloc(0);
             child.stderr.on("data", (chunk) => {
-                stderr = `${stderr}${chunk}`.slice(-8_000);
+                stderr = appendByteTail(stderr, chunk, maxStderrBytes);
             });
             const server = {
                 id,
@@ -178,42 +784,57 @@ export default {
                 nextRequestId: 2,
                 queue: Promise.resolve(),
                 startedAt: Date.now(),
+                lifecycle: new AbortController(),
             };
             child.once("close", () => {
                 server.status = "stopping";
+                server.lifecycle.abort(new Error(`MCP server exited: ${server.id}`));
                 servers.delete(server.id);
             });
             try {
-                await request(child, 1, "initialize", { protocolVersion: "2025-06-18", capabilities: {}, clientInfo: { name: "pi-harness", version: "0.1.2" } });
-                child.stdin.write(encodeMessage({ jsonrpc: "2.0", method: "notifications/initialized" }));
+                const initializeResult = await request(child, 1, "initialize", { protocolVersion: "2025-06-18", capabilities: {}, clientInfo: { name: "pi-harness", version: clientVersion } }, signal);
+                validateInitializeResult(initializeResult);
+                if (child.exitCode !== null || child.signalCode !== null)
+                    throw new Error(`MCP server exited during initialization: ${id}`);
                 servers.set(server.id, server);
+                child.stdin.write(encodeMessage({ jsonrpc: "2.0", method: "notifications/initialized" }));
                 return server;
             }
             catch (error) {
-                child.stdin.end();
-                child.kill();
-                if (error instanceof Error && stderr.trim() !== "")
-                    throw new Error(`${error.message}: ${stderr.trim()}`, { cause: error });
+                servers.delete(server.id);
+                await terminateChild(child);
+                if (error instanceof Error && error.message === disposedMessage)
+                    throw error;
+                const stderrText = stderr.toString("utf8").trim();
+                if (error instanceof Error && stderrText !== "")
+                    throw new Error(`${error.message}: ${stderrText}`, { cause: error });
                 throw error;
             }
+            finally {
+                startingServers.delete(id);
+            }
         };
-        const stopServer = async (serverId) => {
+        const stopServer = (serverId, signal) => {
             const server = servers.get(serverId);
             if (server === undefined)
                 throw new Error(`MCP server is not running: ${serverId}`);
             server.status = "stopping";
-            await server.queue;
-            servers.delete(server.id);
-            server.child.stdin.end();
-            server.child.kill();
-            return true;
+            server.lifecycle.abort(new Error(`MCP server stopped: ${server.id}`));
+            const operation = (async () => {
+                await server.queue;
+                servers.delete(server.id);
+                await terminateChild(server.child);
+                return true;
+            })();
+            return withCancellation(operation, signal, "server/stop");
         };
-        const requestManaged = (server, method, params) => {
+        const requestManaged = (server, method, params, signal) => {
             if (server.status !== "running")
                 throw new Error(`MCP server is not running: ${server.id}`);
-            const task = server.queue.then(() => request(server.child, server.nextRequestId++, method, params));
+            const requestSignal = signal === undefined ? server.lifecycle.signal : AbortSignal.any([signal, server.lifecycle.signal]);
+            const task = server.queue.then(() => request(server.child, server.nextRequestId++, method, params, requestSignal));
             server.queue = task.then(() => undefined, () => undefined);
-            return task;
+            return withCancellation(task, requestSignal, method);
         };
         const getServer = (serverId) => {
             const server = servers.get(serverId);
@@ -227,99 +848,165 @@ export default {
                 throw new Error(`Configured MCP server is not found: ${serverId}`);
             return [...definition.command];
         };
-        const list = async (command, serverId) => {
+        const statusSnapshot = () => {
+            const running = [...servers.values()].map((server) => ({
+                id: server.id,
+                executable: executableName(server.command),
+                argumentCount: Math.max(0, server.command.length - 1),
+                status: server.status,
+                startedAt: server.startedAt,
+            }));
+            const active = new Set(running.map((server) => server.id));
+            return [
+                ...running,
+                ...[...configured.values()]
+                    .filter((definition) => !active.has(definition.id))
+                    .map((definition) => ({
+                    id: definition.id,
+                    executable: executableName(definition.command),
+                    argumentCount: Math.max(0, definition.command.length - 1),
+                    status: "stopped",
+                    startedAt: 0,
+                })),
+            ];
+        };
+        const list = async (command, serverId, signal) => {
+            rejectAmbiguousTarget(command, serverId);
             if (serverId !== undefined) {
                 const managed = getServer(serverId);
-                const result = await requestManaged(managed, "tools/list");
-                const tools = Array.isArray(result.tools)
-                    ? result.tools.filter((tool) => typeof tool === "object" && tool !== null && typeof tool.name === "string")
-                    : [];
-                latest = { server: managed.command.join(" "), tools, resources: latest?.resources ?? [], prompts: latest?.prompts ?? [] };
-                return latest;
+                const tools = await paginatedInventory("tools/list", "tools", (params) => requestManaged(managed, "tools/list", params, signal), toolInventory);
+                const key = `managed:${managed.id}`;
+                const server = serverLabel(managed.command);
+                const previous = previousFor(key);
+                const next = { server, tools, resources: previous?.resources ?? [], prompts: previous?.prompts ?? [] };
+                return publishLatest(key, next);
             }
             if (command === undefined)
                 throw new Error("Provide command or serverId to list MCP tools");
             return withServer(command, context.piHarnessLaunch.cwd, async (child) => {
-                const result = await request(child, 2, "tools/list");
-                const tools = Array.isArray(result.tools)
-                    ? result.tools.filter((tool) => typeof tool === "object" && tool !== null && typeof tool.name === "string")
-                    : [];
-                latest = { server: command.join(" "), tools, resources: latest?.resources ?? [], prompts: latest?.prompts ?? [] };
-                return latest;
-            });
+                let requestId = 2;
+                const tools = await paginatedInventory("tools/list", "tools", (params) => request(child, requestId++, "tools/list", params, signal), toolInventory);
+                const key = `command:${JSON.stringify(command)}`;
+                const server = serverLabel(command);
+                const previous = previousFor(key);
+                const next = { server, tools, resources: previous?.resources ?? [], prompts: previous?.prompts ?? [] };
+                return publishLatest(key, next);
+            }, signal);
         };
-        const call = async (command, serverId, name, args) => {
+        const call = async (command, serverId, name, args, signal) => {
+            rejectAmbiguousTarget(command, serverId);
+            boundedInput(name, "tool name", 512);
             if (serverId !== undefined) {
                 const managed = getServer(serverId);
-                const result = (await requestManaged(managed, "tools/call", { name, arguments: args }));
-                latest = {
-                    server: managed.command.join(" "),
-                    tools: latest?.tools ?? [],
-                    resources: latest?.resources ?? [],
-                    prompts: latest?.prompts ?? [],
+                const result = (await requestManaged(managed, "tools/call", { name, arguments: args }, signal));
+                toolResultContent(result);
+                const key = `managed:${managed.id}`;
+                const server = serverLabel(managed.command);
+                const previous = previousFor(key);
+                publishLatest(key, {
+                    server,
+                    tools: previous?.tools ?? [],
+                    resources: previous?.resources ?? [],
+                    prompts: previous?.prompts ?? [],
                     lastCall: name,
-                };
+                });
                 return result;
             }
             if (command === undefined)
                 throw new Error("Provide command or serverId to call an MCP tool");
             return withServer(command, context.piHarnessLaunch.cwd, async (child) => {
-                const result = (await request(child, 2, "tools/call", { name, arguments: args }));
-                latest = { server: command.join(" "), tools: latest?.tools ?? [], resources: latest?.resources ?? [], prompts: latest?.prompts ?? [], lastCall: name };
+                const result = (await request(child, 2, "tools/call", { name, arguments: args }, signal));
+                toolResultContent(result);
+                const key = `command:${JSON.stringify(command)}`;
+                const server = serverLabel(command);
+                const previous = previousFor(key);
+                publishLatest(key, {
+                    server,
+                    tools: previous?.tools ?? [],
+                    resources: previous?.resources ?? [],
+                    prompts: previous?.prompts ?? [],
+                    lastCall: name,
+                });
                 return result;
-            });
+            }, signal);
         };
-        const requestOneShot = async (command, method, params) => withServer(command, context.piHarnessLaunch.cwd, async (child) => request(child, 2, method, params));
+        const requestOneShot = async (command, method, params, signal) => withServer(command, context.piHarnessLaunch.cwd, async (child) => request(child, 2, method, params, signal), signal);
         const requireCommand = (command, message) => {
             if (command === undefined)
                 throw new Error(message);
             return command;
         };
-        const resources = async (command, serverId) => {
-            const result = serverId === undefined
-                ? await requestOneShot(requireCommand(command, "Provide command or serverId to list MCP resources"), "resources/list")
-                : await requestManaged(getServer(serverId), "resources/list");
-            const items = Array.isArray(result.resources)
-                ? result.resources.filter((item) => typeof item === "object" && item !== null && typeof item.uri === "string")
-                : [];
-            latest = {
-                server: serverId === undefined ? (command ?? []).join(" ") : getServer(serverId).command.join(" "),
-                tools: latest?.tools ?? [],
+        const resources = async (command, serverId, signal) => {
+            rejectAmbiguousTarget(command, serverId);
+            let items;
+            let selectedCommand;
+            if (serverId === undefined) {
+                selectedCommand = requireCommand(command, "Provide command or serverId to list MCP resources");
+                items = await withServer(selectedCommand, context.piHarnessLaunch.cwd, async (child) => {
+                    let requestId = 2;
+                    return paginatedInventory("resources/list", "resources", (params) => request(child, requestId++, "resources/list", params, signal), resourceInventory);
+                }, signal);
+            }
+            else {
+                const managed = getServer(serverId);
+                selectedCommand = managed.command;
+                items = await paginatedInventory("resources/list", "resources", (params) => requestManaged(managed, "resources/list", params, signal), resourceInventory);
+            }
+            const key = serverId === undefined ? `command:${JSON.stringify(selectedCommand)}` : `managed:${serverId}`;
+            const server = serverLabel(selectedCommand);
+            const previous = previousFor(key);
+            const next = {
+                server,
+                tools: previous?.tools ?? [],
                 resources: items,
-                prompts: latest?.prompts ?? [],
+                prompts: previous?.prompts ?? [],
             };
-            return items;
+            publishLatest(key, next);
+            return clone(items);
         };
-        const readResource = async (command, serverId, uri) => {
-            if (uri.length === 0 || uri.length > 4096)
-                throw new Error("MCP resource URI must be between 1 and 4096 characters");
+        const readResource = async (command, serverId, uri, signal) => {
+            rejectAmbiguousTarget(command, serverId);
+            boundedInput(uri, "resource URI", 4096);
             return serverId === undefined
-                ? requestOneShot(requireCommand(command, "Provide command or serverId to read an MCP resource"), "resources/read", { uri })
-                : requestManaged(getServer(serverId), "resources/read", { uri });
+                ? requestOneShot(requireCommand(command, "Provide command or serverId to read an MCP resource"), "resources/read", { uri }, signal)
+                : requestManaged(getServer(serverId), "resources/read", { uri }, signal);
         };
-        const prompts = async (command, serverId) => {
-            const result = serverId === undefined
-                ? await requestOneShot(requireCommand(command, "Provide command or serverId to list MCP prompts"), "prompts/list")
-                : await requestManaged(getServer(serverId), "prompts/list");
-            const items = Array.isArray(result.prompts)
-                ? result.prompts.filter((item) => typeof item === "object" && item !== null && typeof item.name === "string")
-                : [];
-            latest = {
-                server: serverId === undefined ? (command ?? []).join(" ") : getServer(serverId).command.join(" "),
-                tools: latest?.tools ?? [],
-                resources: latest?.resources ?? [],
+        const prompts = async (command, serverId, signal) => {
+            rejectAmbiguousTarget(command, serverId);
+            let items;
+            let selectedCommand;
+            if (serverId === undefined) {
+                selectedCommand = requireCommand(command, "Provide command or serverId to list MCP prompts");
+                items = await withServer(selectedCommand, context.piHarnessLaunch.cwd, async (child) => {
+                    let requestId = 2;
+                    return paginatedInventory("prompts/list", "prompts", (params) => request(child, requestId++, "prompts/list", params, signal), promptInventory);
+                }, signal);
+            }
+            else {
+                const managed = getServer(serverId);
+                selectedCommand = managed.command;
+                items = await paginatedInventory("prompts/list", "prompts", (params) => requestManaged(managed, "prompts/list", params, signal), promptInventory);
+            }
+            const key = serverId === undefined ? `command:${JSON.stringify(selectedCommand)}` : `managed:${serverId}`;
+            const server = serverLabel(selectedCommand);
+            const previous = previousFor(key);
+            const next = {
+                server,
+                tools: previous?.tools ?? [],
+                resources: previous?.resources ?? [],
                 prompts: items,
             };
-            return items;
+            publishLatest(key, next);
+            return clone(items);
         };
-        const getPrompt = async (command, serverId, name, args) => {
-            if (name.length === 0 || name.length > 512)
-                throw new Error("MCP prompt name must be between 1 and 512 characters");
+        const getPrompt = async (command, serverId, name, args, signal) => {
+            rejectAmbiguousTarget(command, serverId);
+            boundedInput(name, "prompt name", 512);
             return serverId === undefined
-                ? requestOneShot(requireCommand(command, "Provide command or serverId to get an MCP prompt"), "prompts/get", { name, arguments: args })
-                : requestManaged(getServer(serverId), "prompts/get", { name, arguments: args });
+                ? requestOneShot(requireCommand(command, "Provide command or serverId to get an MCP prompt"), "prompts/get", { name, arguments: args }, signal)
+                : requestManaged(getServer(serverId), "prompts/get", { name, arguments: args }, signal);
         };
-        const unregisterList = context.piTools.register(defineTool({
+        const unregisterList = registerTool(defineTool({
             name: "mcp_list_tools",
             label: "MCP list tools",
             description: "Start an MCP stdio server and list its available tools.",
@@ -327,9 +1014,13 @@ export default {
             parameters: Type.Object({
                 command: Type.Optional(Type.Array(Type.String(), { description: "MCP server executable and arguments; shell wrappers are rejected" })),
                 serverId: Type.Optional(Type.String({ description: "A configured or running MCP server id" })),
-            }),
-            async execute(_toolCallId, params) {
-                const result = await list(params.command, params.serverId);
+            }, { additionalProperties: false }),
+            executionMode: "sequential",
+            async execute(_toolCallId, params, signal) {
+                const operationSignal = executionSignal(signal, lifecycle.signal);
+                operationSignal.throwIfAborted();
+                const raw = inspectParameters(params, connectionParameterNames);
+                const result = await list(optionalCommand(raw.command), serverIdValue(raw.serverId), operationSignal);
                 return {
                     content: [
                         { type: "text", text: result.tools.map((tool) => `${tool.name}: ${tool.description ?? ""}`).join("\n") || "MCP server returned no tools." },
@@ -338,7 +1029,7 @@ export default {
                 };
             },
         }));
-        const unregisterCall = context.piTools.register(defineTool({
+        const unregisterCall = registerTool(defineTool({
             name: "mcp_call",
             label: "MCP call tool",
             description: "Call a named tool on an MCP stdio server with a JSON object of arguments.",
@@ -348,14 +1039,17 @@ export default {
                 serverId: Type.Optional(Type.String()),
                 name: Type.String(),
                 arguments: Type.Optional(Type.Record(Type.String(), Type.Any())),
-            }),
-            async execute(_toolCallId, params) {
-                const result = await call(params.command, params.serverId, params.name, params.arguments ?? {});
-                const content = Array.isArray(result.content) ? result.content : [{ type: "text", text: JSON.stringify(result) }];
-                return { content: content, details: result };
+            }, { additionalProperties: false }),
+            executionMode: "sequential",
+            async execute(_toolCallId, params, signal) {
+                const operationSignal = executionSignal(signal, lifecycle.signal);
+                operationSignal.throwIfAborted();
+                const raw = inspectParameters(params, callParameterNames);
+                const result = await call(optionalCommand(raw.command), serverIdValue(raw.serverId), requiredString(raw.name, "tool name"), jsonObject(raw.arguments), operationSignal);
+                return { content: toolResultContent(result), details: clone(result) };
             },
         }));
-        const unregisterStart = context.piTools.register(defineTool({
+        const unregisterStart = registerTool(defineTool({
             name: "mcp_server_start",
             label: "MCP server start",
             description: "Start and initialize a persistent MCP stdio server managed by Pi Harness.",
@@ -363,103 +1057,120 @@ export default {
             parameters: Type.Object({
                 command: Type.Optional(Type.Array(Type.String(), { description: "MCP server executable and arguments; shell wrappers are rejected" })),
                 serverId: Type.Optional(Type.String({ description: "Configured server id or a running server id" })),
-            }),
-            async execute(_toolCallId, params) {
-                const command = params.command ?? (params.serverId === undefined ? undefined : configuredCommand(params.serverId));
+            }, { additionalProperties: false }),
+            executionMode: "sequential",
+            async execute(_toolCallId, params, signal) {
+                const operationSignal = executionSignal(signal, lifecycle.signal);
+                operationSignal.throwIfAborted();
+                const raw = inspectParameters(params, connectionParameterNames);
+                const serverId = serverIdValue(raw.serverId);
+                const command = optionalCommand(raw.command) ?? (serverId === undefined ? undefined : configuredCommand(serverId));
                 if (command === undefined)
                     throw new Error("Provide command or configured serverId to start an MCP server");
-                const server = await startServer(command, params.serverId);
+                const server = await startServer(command, serverId, operationSignal);
                 return {
                     content: [{ type: "text", text: `MCP server ${server.id} is running.` }],
-                    details: { serverId: server.id, command: server.command, status: server.status },
+                    details: { serverId: server.id, command: [...server.command], status: server.status },
                 };
             },
         }));
-        const unregisterStatus = context.piTools.register(defineTool({
+        const unregisterStatus = registerTool(defineTool({
             name: "mcp_server_status",
             label: "MCP server status",
             description: "List persistent MCP stdio servers managed by Pi Harness.",
             promptSnippet: "inspect running MCP server status",
-            parameters: Type.Object({}),
-            execute() {
-                const running = [...servers.values()].map((server) => ({
-                    id: server.id,
-                    command: server.command,
-                    status: server.status,
-                    startedAt: server.startedAt,
-                }));
-                const active = new Set(running.map((server) => server.id));
-                const snapshot = [
-                    ...running,
-                    ...[...configured.values()]
-                        .filter((definition) => !active.has(definition.id))
-                        .map((definition) => ({ id: definition.id, command: definition.command, status: "stopped", startedAt: 0 })),
-                ];
-                return Promise.resolve({
-                    content: [
-                        {
-                            type: "text",
-                            text: snapshot.length === 0
-                                ? "No MCP servers are running."
-                                : snapshot.map((server) => `${server.id}: ${server.status} (${server.command.join(" ")})`).join("\n"),
-                        },
-                    ],
-                    details: { servers: snapshot },
+            parameters: Type.Object({}, { additionalProperties: false }),
+            executionMode: "sequential",
+            execute(_toolCallId, params, signal) {
+                return Promise.resolve().then(() => {
+                    const operationSignal = executionSignal(signal, lifecycle.signal);
+                    operationSignal.throwIfAborted();
+                    inspectParameters(params, noParameterNames);
+                    const snapshot = statusSnapshot();
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: snapshot.length === 0
+                                    ? "No MCP servers are running."
+                                    : snapshot
+                                        .map((server) => `${server.id}: ${server.status} (${server.executable}, ${server.argumentCount} argument${server.argumentCount === 1 ? "" : "s"})`)
+                                        .join("\n"),
+                            },
+                        ],
+                        details: { servers: snapshot },
+                    };
                 });
             },
         }));
-        const unregisterStop = context.piTools.register(defineTool({
+        const unregisterStop = registerTool(defineTool({
             name: "mcp_server_stop",
             label: "MCP server stop",
             description: "Stop a persistent MCP stdio server and remove it from the managed set.",
             promptSnippet: "stop a persistent MCP stdio server",
-            parameters: Type.Object({ serverId: Type.String() }),
-            async execute(_toolCallId, params) {
-                const stopped = await stopServer(params.serverId);
-                return { content: [{ type: "text", text: `MCP server ${params.serverId} stopped.` }], details: { serverId: params.serverId, stopped } };
+            parameters: Type.Object({ serverId: Type.String() }, { additionalProperties: false }),
+            executionMode: "sequential",
+            async execute(_toolCallId, params, signal) {
+                const operationSignal = executionSignal(signal, lifecycle.signal);
+                operationSignal.throwIfAborted();
+                const raw = inspectParameters(params, stopParameterNames);
+                const serverId = serverIdValue(raw.serverId, true);
+                const stopped = await stopServer(serverId, operationSignal);
+                return { content: [{ type: "text", text: `MCP server ${serverId} stopped.` }], details: { serverId, stopped } };
             },
         }));
-        const unregisterListResources = context.piTools.register(defineTool({
+        const unregisterListResources = registerTool(defineTool({
             name: "mcp_list_resources",
             label: "MCP list resources",
             description: "List resources exposed by an MCP server.",
             promptSnippet: "list resources exposed by an MCP server",
-            parameters: Type.Object({ command: Type.Optional(Type.Array(Type.String())), serverId: Type.Optional(Type.String()) }),
-            async execute(_toolCallId, params) {
-                const items = await resources(params.command, params.serverId);
+            parameters: Type.Object({ command: Type.Optional(Type.Array(Type.String())), serverId: Type.Optional(Type.String()) }, { additionalProperties: false }),
+            executionMode: "sequential",
+            async execute(_toolCallId, params, signal) {
+                const operationSignal = executionSignal(signal, lifecycle.signal);
+                operationSignal.throwIfAborted();
+                const raw = inspectParameters(params, connectionParameterNames);
+                const items = await resources(optionalCommand(raw.command), serverIdValue(raw.serverId), operationSignal);
                 return {
                     content: [{ type: "text", text: items.map((item) => `${item.uri} ${item.name ?? ""}`).join("\n") || "MCP server returned no resources." }],
                     details: { resources: items },
                 };
             },
         }));
-        const unregisterReadResource = context.piTools.register(defineTool({
+        const unregisterReadResource = registerTool(defineTool({
             name: "mcp_read_resource",
             label: "MCP read resource",
             description: "Read one resource exposed by an MCP server.",
             promptSnippet: "read a resource exposed by an MCP server",
-            parameters: Type.Object({ command: Type.Optional(Type.Array(Type.String())), serverId: Type.Optional(Type.String()), uri: Type.String() }),
-            async execute(_toolCallId, params) {
-                const result = await readResource(params.command, params.serverId, params.uri);
-                const contents = Array.isArray(result.contents) ? result.contents : [{ type: "text", text: JSON.stringify(result) }];
-                return { content: contents, details: result };
+            parameters: Type.Object({ command: Type.Optional(Type.Array(Type.String())), serverId: Type.Optional(Type.String()), uri: Type.String() }, { additionalProperties: false }),
+            executionMode: "sequential",
+            async execute(_toolCallId, params, signal) {
+                const operationSignal = executionSignal(signal, lifecycle.signal);
+                operationSignal.throwIfAborted();
+                const raw = inspectParameters(params, readResourceParameterNames);
+                const result = await readResource(optionalCommand(raw.command), serverIdValue(raw.serverId), requiredString(raw.uri, "resource URI"), operationSignal);
+                return { content: resourceResultContent(result), details: clone(result) };
             },
         }));
-        const unregisterListPrompts = context.piTools.register(defineTool({
+        const unregisterListPrompts = registerTool(defineTool({
             name: "mcp_list_prompts",
             label: "MCP list prompts",
             description: "List prompt templates exposed by an MCP server.",
             promptSnippet: "list prompt templates exposed by an MCP server",
-            parameters: Type.Object({ command: Type.Optional(Type.Array(Type.String())), serverId: Type.Optional(Type.String()) }),
-            async execute(_toolCallId, params) {
-                const items = await prompts(params.command, params.serverId);
+            parameters: Type.Object({ command: Type.Optional(Type.Array(Type.String())), serverId: Type.Optional(Type.String()) }, { additionalProperties: false }),
+            executionMode: "sequential",
+            async execute(_toolCallId, params, signal) {
+                const operationSignal = executionSignal(signal, lifecycle.signal);
+                operationSignal.throwIfAborted();
+                const raw = inspectParameters(params, connectionParameterNames);
+                const items = await prompts(optionalCommand(raw.command), serverIdValue(raw.serverId), operationSignal);
                 return {
                     content: [{ type: "text", text: items.map((item) => `${item.name}: ${item.description ?? ""}`).join("\n") || "MCP server returned no prompts." }],
                     details: { prompts: items },
                 };
             },
         }));
-        const unregisterGetPrompt = context.piTools.register(defineTool({
+        const unregisterGetPrompt = registerTool(defineTool({
             name: "mcp_get_prompt",
             label: "MCP get prompt",
             description: "Render a prompt template exposed by an MCP server.",
@@ -468,18 +1179,21 @@ export default {
                 command: Type.Optional(Type.Array(Type.String())),
                 serverId: Type.Optional(Type.String()),
                 name: Type.String(),
-                arguments: Type.Optional(Type.Record(Type.String(), Type.Any())),
-            }),
-            async execute(_toolCallId, params) {
-                const result = await getPrompt(params.command, params.serverId, params.name, params.arguments ?? {});
-                const content = Array.isArray(result.messages) ? result.messages : [{ type: "text", text: JSON.stringify(result) }];
-                return { content: content, details: result };
+                arguments: Type.Optional(Type.Record(Type.String(), Type.String())),
+            }, { additionalProperties: false }),
+            executionMode: "sequential",
+            async execute(_toolCallId, params, signal) {
+                const operationSignal = executionSignal(signal, lifecycle.signal);
+                operationSignal.throwIfAborted();
+                const raw = inspectParameters(params, callParameterNames);
+                const result = await getPrompt(optionalCommand(raw.command), serverIdValue(raw.serverId), requiredString(raw.name, "prompt name"), promptArguments(raw.arguments), operationSignal);
+                return { content: promptResultContent(result), details: clone(result) };
             },
         }));
         const serverSnapshot = () => {
             const running = [...servers.values()].map((server) => ({
                 id: server.id,
-                command: [...server.command],
+                command: [executableName(server.command)],
                 status: server.status,
                 startedAt: server.startedAt,
             }));
@@ -488,26 +1202,65 @@ export default {
                 ...running,
                 ...[...configured.values()]
                     .filter((definition) => !active.has(definition.id))
-                    .map((definition) => ({ id: definition.id, command: [...definition.command], status: "stopped", startedAt: 0 })),
+                    .map((definition) => ({ id: definition.id, command: [executableName(definition.command)], status: "stopped", startedAt: 0 })),
             ];
         };
         context.provide("piMcp", { snapshot: () => ({ servers: serverSnapshot() }) });
-        const disposePanel = context.piPluginUi.register({
-            id: "mcp-client-panel",
-            pluginId: "@pi-harness/core/plugins/mcp-client",
-            title: "MCP Client",
-            description: "通过 stdio JSON-RPC 连接外部 MCP 工具服务器。",
-            icon: "⌘",
-            read: () => ({
-                server: latest?.server ?? null,
-                tools: latest?.tools ?? [],
-                resources: latest?.resources ?? [],
-                prompts: latest?.prompts ?? [],
-                lastCall: latest?.lastCall ?? null,
-                servers: serverSnapshot(),
-            }),
-        });
-        context.effect(() => () => {
+        let disposePanel;
+        try {
+            disposePanel = context.piPluginUi.register({
+                id: "mcp-client-panel",
+                pluginId: "@pi-harness/core/plugins/mcp-client",
+                title: "MCP Client",
+                description: "通过 stdio JSON-RPC 连接外部 MCP 工具服务器。",
+                icon: "⌘",
+                read: () => {
+                    const tools = latest?.tools ?? [];
+                    const resources = latest?.resources ?? [];
+                    const prompts = latest?.prompts ?? [];
+                    const serverStatuses = statusSnapshot();
+                    return clone({
+                        server: latest?.server ?? null,
+                        tools: tools.slice(0, maxPanelItems),
+                        resources: resources.slice(0, maxPanelItems),
+                        prompts: prompts.slice(0, maxPanelItems),
+                        lastCall: latest?.lastCall ?? null,
+                        servers: serverStatuses.slice(0, maxPanelItems),
+                        inventory: {
+                            tools: { total: tools.length, shown: Math.min(tools.length, maxPanelItems), truncated: tools.length > maxPanelItems },
+                            resources: { total: resources.length, shown: Math.min(resources.length, maxPanelItems), truncated: resources.length > maxPanelItems },
+                            prompts: { total: prompts.length, shown: Math.min(prompts.length, maxPanelItems), truncated: prompts.length > maxPanelItems },
+                            servers: {
+                                total: serverStatuses.length,
+                                shown: Math.min(serverStatuses.length, maxPanelItems),
+                                truncated: serverStatuses.length > maxPanelItems,
+                            },
+                        },
+                        limits: {
+                            responseBytes: maxResponseBytes,
+                            commandArgs: maxCommandArgs,
+                            argumentBytes: maxArgumentBytes,
+                            toolArgumentsBytes: maxToolArgumentsBytes,
+                            toolArgumentDepth: maxToolArgumentDepth,
+                            requestTimeoutMs,
+                            panelItems: maxPanelItems,
+                            inventoryItems: maxInventoryItems,
+                            paginationPages: maxPaginationPages,
+                            stderrBytes: maxStderrBytes,
+                            managedServers: maxManagedServers,
+                        },
+                    });
+                },
+            });
+        }
+        catch (error) {
+            for (const unregister of unregisters.splice(0).reverse())
+                unregister();
+            lifecycle.abort(new Error("MCP client plugin activation failed", { cause: error }));
+            throw error;
+        }
+        context.effect(() => async () => {
+            lifecycle.abort(new Error(disposedMessage));
             unregisterList();
             unregisterCall();
             unregisterStart();
@@ -517,17 +1270,18 @@ export default {
             unregisterReadResource();
             unregisterListPrompts();
             unregisterGetPrompt();
-            for (const server of servers.values()) {
+            const running = [...servers.values()];
+            for (const server of running) {
                 server.status = "stopping";
-                server.child.stdin.end();
-                server.child.kill();
+                server.lifecycle.abort(new Error(disposedMessage));
             }
             servers.clear();
             disposePanel();
+            await Promise.all(running.map(async (server) => terminateChild(server.child)));
         });
         for (const definition of configured.values()) {
             if (definition.autoStart === true)
-                await startServer(definition.command, definition.id);
+                await startServer(definition.command, definition.id, lifecycle.signal);
         }
     },
 };