codex-plugin-doctor 1.62.0 → 1.64.0

package/README.md

@@ -81,35 +81,62 @@ Runtime MCP validation with `--runtime`:
 - optional runtime approval gating with a precomputed `doctor runtime-plan` digest
 - optional Docker isolation for local Node.js stdio servers with `--sandbox docker`
 
-### MCP Protocol Discovery
-
-Inspect an HTTP MCP endpoint's advertised protocol versions using a bounded MCP
-2026-07-28 `server/discover` request:
-
-```bash
-codex-plugin-doctor doctor discover https://mcp.example.com/mcp --allow-network
-codex-plugin-doctor doctor discover https://mcp.example.com/mcp --allow-network --json
-```
-
-This is an opt-in discovery-only check. A successful result validates the discovery
-response, not full protocol conformance, tool behavior, or compatibility with a
-particular client. Existing `check --runtime` remains on its 2025-11-25 baseline.
-See [MCP Discovery](docs/guides/mcp-discovery.md) for consent, scope, and exit codes.
-
-### HTTP MCP Tool Catalog
-
-Inspect a modern HTTP MCP server's tool definitions without invoking them:
-
-```bash
-codex-plugin-doctor doctor tools https://mcp.example.com/mcp --allow-network --json
-```
-
-This opt-in command performs discovery and bounded `tools/list` pagination. It
-reports tool-definition and root-schema shape findings, explicit completion state,
-and partial inspection limits. It does not claim full schema validation, tool
-execution, or client compatibility. Existing `doctor discover` behavior is unchanged.
-See [HTTP MCP Tool Catalog](docs/guides/mcp-tool-catalog.md).
-
+### MCP Protocol Discovery
+
+Inspect an HTTP MCP endpoint's advertised protocol versions using a bounded MCP
+2026-07-28 `server/discover` request:
+
+```bash
+codex-plugin-doctor doctor discover https://mcp.example.com/mcp --allow-network
+codex-plugin-doctor doctor discover https://mcp.example.com/mcp --allow-network --json
+```
+
+This is an opt-in discovery-only check. A successful result validates the discovery
+response, not full protocol conformance, tool behavior, or compatibility with a
+particular client. Existing `check --runtime` remains on its 2025-11-25 baseline.
+See [MCP Discovery](docs/guides/mcp-discovery.md) for consent, scope, and exit codes.
+
+### Offline MCP Tool Definitions
+
+Inspect a saved MCP 2026-07-28 `tools/list` response without contacting a server:
+
+```bash
+codex-plugin-doctor doctor tools-file ./tools-list.json --json
+```
+
+This checks the supplied tool definitions and root-schema shapes within fixed file,
+tool, and finding limits. It does not establish server inventory completeness or
+execute tools. See [Offline MCP Tool Definitions](docs/guides/offline-tool-definitions.md)
+for the accepted input format, coverage, and exit codes.
+
+### Offline MCP Tool Diff
+
+Compare two saved tool-list responses before updating a server or client:
+
+```bash
+codex-plugin-doctor doctor tools-diff --before ./tools-old.json --after ./tools-new.json --json
+```
+
+This reports added, removed, and structurally changed definitions using numeric
+locations. Incomplete inputs, invalid definitions, or duplicate names prevent a
+comparison. It does not determine whether a schema change breaks compatibility.
+See [Offline MCP Tool Diff](docs/guides/offline-tool-diff.md) for matching rules,
+privacy, limits, and exit codes.
+
+### HTTP MCP Tool Catalog
+
+Inspect a modern HTTP MCP server's tool definitions without invoking them:
+
+```bash
+codex-plugin-doctor doctor tools https://mcp.example.com/mcp --allow-network --json
+```
+
+This opt-in command performs discovery and bounded `tools/list` pagination. It
+reports tool-definition and root-schema shape findings, explicit completion state,
+and partial inspection limits. It does not claim full schema validation, tool
+execution, or client compatibility. Existing `doctor discover` behavior is unchanged.
+See [HTTP MCP Tool Catalog](docs/guides/mcp-tool-catalog.md).
+
 ### Remote MCP Readiness
 
 Remote MCP runtime probing is disabled until you explicitly pass `--runtime --allow-network`. Loopback endpoints also require `--allow-local-network`:
@@ -528,9 +555,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
-      - uses: Esquetta/CodexPluginDoctor@v1.62.0
+      - uses: Esquetta/CodexPluginDoctor@v1.64.0
         with:
-          version: "1.62.0"
+          version: "1.64.0"
           path: .
           runtime: "true"
           policy: codex-publish

package/dist/core/mcp-tool-diff.d.ts

@@ -0,0 +1,32 @@
+import { type McpToolFileReport } from "./mcp-tool-file.js";
+type DiffField = "inputSchema" | "outputSchema" | "description" | "title" | "annotations" | "other";
+export interface McpToolDiffReport {
+    schemaVersion: 1;
+    scope: "tool-definitions-diff";
+    status: "pass" | "warn" | "incomplete" | "blocked";
+    before: McpToolFileReport;
+    after: McpToolFileReport;
+    comparison: {
+        complete: boolean;
+        reason: "input-blocked" | "input-incomplete" | "invalid-definitions" | "ambiguous-names" | null;
+        added: number | null;
+        removed: number | null;
+        changed: number | null;
+        unchanged: number | null;
+    };
+    coverage: {
+        comparison: "structural-only";
+        schema: "root-shape-only";
+        compatibility: "not-tested";
+        serverCatalog: "not-tested";
+        toolExecution: "not-tested";
+    };
+    changes: Array<{
+        kind: "added" | "removed" | "changed";
+        beforeToolIndex: number | null;
+        afterToolIndex: number | null;
+        fields: DiffField[];
+    }>;
+}
+export declare function compareMcpToolFiles(beforePath: string, afterPath: string): Promise<McpToolDiffReport>;
+export {};

package/dist/core/mcp-tool-diff.js

@@ -0,0 +1,150 @@
+import { loadMcpToolFileSnapshot } from "./mcp-tool-file.js";
+const FIXED_FIELDS = [
+    "inputSchema",
+    "outputSchema",
+    "description",
+    "title",
+    "annotations"
+];
+const EXCLUDED_OTHER_FIELDS = new Set(["name", ...FIXED_FIELDS]);
+function isJsonObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function structurallyEqual(left, right) {
+    const pending = [[left, right]];
+    while (pending.length > 0) {
+        const [currentLeft, currentRight] = pending.pop();
+        if (Object.is(currentLeft, currentRight))
+            continue;
+        if (Array.isArray(currentLeft) || Array.isArray(currentRight)) {
+            if (!Array.isArray(currentLeft) || !Array.isArray(currentRight) || currentLeft.length !== currentRight.length)
+                return false;
+            for (let index = 0; index < currentLeft.length; index += 1)
+                pending.push([currentLeft[index], currentRight[index]]);
+            continue;
+        }
+        if (!isJsonObject(currentLeft) || !isJsonObject(currentRight))
+            return false;
+        const leftKeys = Object.keys(currentLeft);
+        const rightKeys = Object.keys(currentRight);
+        if (leftKeys.length !== rightKeys.length)
+            return false;
+        for (const key of leftKeys) {
+            if (!Object.hasOwn(currentRight, key))
+                return false;
+            pending.push([currentLeft[key], currentRight[key]]);
+        }
+    }
+    return true;
+}
+function filteredOther(definition) {
+    const other = Object.create(null);
+    for (const key of Object.keys(definition)) {
+        if (!EXCLUDED_OTHER_FIELDS.has(key))
+            other[key] = definition[key];
+    }
+    return other;
+}
+function changedFields(before, after) {
+    const fields = [];
+    for (const field of FIXED_FIELDS) {
+        if (!structurallyEqual(before[field], after[field]))
+            fields.push(field);
+    }
+    if (!structurallyEqual(filteredOther(before), filteredOther(after)))
+        fields.push("other");
+    return fields;
+}
+function toolDefinitions(tools) {
+    const definitions = new Map();
+    for (let offset = 0; offset < tools.length; offset += 1) {
+        const value = tools[offset];
+        if (!isJsonObject(value) || typeof value.name !== "string" || definitions.has(value.name))
+            return null;
+        definitions.set(value.name, { index: offset + 1, value });
+    }
+    return definitions;
+}
+function incompleteReport(before, after, status, reason) {
+    return {
+        schemaVersion: 1,
+        scope: "tool-definitions-diff",
+        status,
+        before,
+        after,
+        comparison: { complete: false, reason, added: null, removed: null, changed: null, unchanged: null },
+        coverage: {
+            comparison: "structural-only",
+            schema: "root-shape-only",
+            compatibility: "not-tested",
+            serverCatalog: "not-tested",
+            toolExecution: "not-tested"
+        },
+        changes: []
+    };
+}
+export async function compareMcpToolFiles(beforePath, afterPath) {
+    const [beforeSnapshot, afterSnapshot] = await Promise.all([
+        loadMcpToolFileSnapshot(beforePath),
+        loadMcpToolFileSnapshot(afterPath)
+    ]);
+    const { report: before } = beforeSnapshot;
+    const { report: after } = afterSnapshot;
+    if (before.status === "blocked" || after.status === "blocked") {
+        return incompleteReport(before, after, "blocked", "input-blocked");
+    }
+    if (!before.inspection.complete || !after.inspection.complete) {
+        return incompleteReport(before, after, "incomplete", "input-incomplete");
+    }
+    if (before.status === "fail" || after.status === "fail" || beforeSnapshot.tools === null || afterSnapshot.tools === null) {
+        return incompleteReport(before, after, "incomplete", "invalid-definitions");
+    }
+    const beforeDefinitions = toolDefinitions(beforeSnapshot.tools);
+    const afterDefinitions = toolDefinitions(afterSnapshot.tools);
+    if (beforeDefinitions === null || afterDefinitions === null) {
+        return incompleteReport(before, after, "incomplete", "ambiguous-names");
+    }
+    const changes = [];
+    let added = 0;
+    let removed = 0;
+    let changed = 0;
+    let unchanged = 0;
+    for (const [name, beforeDefinition] of beforeDefinitions) {
+        const afterDefinition = afterDefinitions.get(name);
+        if (afterDefinition === undefined) {
+            removed += 1;
+            changes.push({ kind: "removed", beforeToolIndex: beforeDefinition.index, afterToolIndex: null, fields: [] });
+            continue;
+        }
+        const fields = changedFields(beforeDefinition.value, afterDefinition.value);
+        if (fields.length === 0) {
+            unchanged += 1;
+        }
+        else {
+            changed += 1;
+            changes.push({ kind: "changed", beforeToolIndex: beforeDefinition.index, afterToolIndex: afterDefinition.index, fields });
+        }
+    }
+    for (const [name, afterDefinition] of afterDefinitions) {
+        if (!beforeDefinitions.has(name)) {
+            added += 1;
+            changes.push({ kind: "added", beforeToolIndex: null, afterToolIndex: afterDefinition.index, fields: [] });
+        }
+    }
+    return {
+        schemaVersion: 1,
+        scope: "tool-definitions-diff",
+        status: changes.length === 0 && before.status === "pass" && after.status === "pass" ? "pass" : "warn",
+        before,
+        after,
+        comparison: { complete: true, reason: null, added, removed, changed, unchanged },
+        coverage: {
+            comparison: "structural-only",
+            schema: "root-shape-only",
+            compatibility: "not-tested",
+            serverCatalog: "not-tested",
+            toolExecution: "not-tested"
+        },
+        changes
+    };
+}

package/dist/core/mcp-tool-file.d.ts

@@ -0,0 +1,32 @@
+import type { CatalogFinding } from "./mcp-tool-definition.js";
+export interface McpToolFileReport {
+    schemaVersion: 1;
+    scope: "tool-definitions-file";
+    status: "pass" | "warn" | "fail" | "incomplete" | "blocked";
+    source: {
+        kind: "file";
+        format: "mcp-tools-list-response";
+        bytesRead: number;
+    };
+    inspection: {
+        complete: boolean;
+        toolsChecked: number;
+        hasNextCursor: boolean | null;
+        reason: string | null;
+    };
+    coverage: {
+        schema: "root-shape-only";
+        discovery: "not-tested";
+        serverCatalog: "not-tested";
+        toolExecution: "not-tested";
+        fullConformance: "not-tested";
+        customHeaderAnnotations: "not-tested";
+    };
+    findings: CatalogFinding[];
+}
+export interface McpToolFileSnapshot {
+    report: McpToolFileReport;
+    tools: unknown[] | null;
+}
+export declare function loadMcpToolFileSnapshot(filePath: string): Promise<McpToolFileSnapshot>;
+export declare function inspectMcpToolFile(filePath: string): Promise<McpToolFileReport>;

package/dist/core/mcp-tool-file.js

@@ -0,0 +1,247 @@
+import { constants } from "node:fs";
+import { lstat, open } from "node:fs/promises";
+import { inspectMcpToolDefinition } from "./mcp-tool-definition.js";
+const MAX_FILE_BYTES = 1024 * 1024;
+const MAX_TOOLS = 500;
+const MAX_FINDINGS = 100;
+function snapshot(report, tools = null) {
+    return { report, tools };
+}
+function isJsonObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function hasOwn(object, key) {
+    return Object.hasOwn(object, key);
+}
+function sameFile(left, right) {
+    return left.dev === right.dev && left.ino === right.ino;
+}
+function sameSnapshot(left, right) {
+    return sameFile(left, right)
+        && left.size === right.size
+        && left.mtimeMs === right.mtimeMs
+        && left.ctimeMs === right.ctimeMs;
+}
+function isBlockedOfflinePath(filePath) {
+    return /^[A-Za-z][A-Za-z0-9+.-]+:/u.test(filePath)
+        || /^[A-Za-z]:\/\//u.test(filePath)
+        || /^[\\/]{2}/u.test(filePath);
+}
+function baseReport(bytesRead) {
+    return {
+        schemaVersion: 1,
+        scope: "tool-definitions-file",
+        source: { kind: "file", format: "mcp-tools-list-response", bytesRead },
+        coverage: {
+            schema: "root-shape-only",
+            discovery: "not-tested",
+            serverCatalog: "not-tested",
+            toolExecution: "not-tested",
+            fullConformance: "not-tested",
+            customHeaderAnnotations: "not-tested"
+        }
+    };
+}
+function report(bytesRead, status, inspection, findings) {
+    return { ...baseReport(bytesRead), status, inspection, findings };
+}
+function fileFinding(id, severity, message, impact, suggestedFix) {
+    return { id, severity, message, impact, suggestedFix };
+}
+function incompleteFileReport(bytesRead, reason, finding) {
+    return report(bytesRead, "incomplete", {
+        complete: false,
+        toolsChecked: 0,
+        hasNextCursor: null,
+        reason
+    }, [finding]);
+}
+function blockedFileReport(reason, finding) {
+    return report(0, "blocked", {
+        complete: false,
+        toolsChecked: 0,
+        hasNextCursor: null,
+        reason
+    }, [finding]);
+}
+function finalStatus(findings) {
+    if (findings.some((finding) => finding.severity === "fail"))
+        return "fail";
+    return findings.some((finding) => finding.severity === "warn") ? "warn" : "pass";
+}
+function parseToolsResult(value) {
+    if (!isJsonObject(value)
+        || value.jsonrpc !== "2.0"
+        || !hasOwn(value, "id")
+        || !(typeof value.id === "string" || (typeof value.id === "number" && Number.isFinite(value.id)))
+        || !hasOwn(value, "result")
+        || hasOwn(value, "error")
+        || !isJsonObject(value.result)
+        || value.result.resultType !== "complete"
+        || !Array.isArray(value.result.tools)
+        || typeof value.result.ttlMs !== "number"
+        || !Number.isFinite(value.result.ttlMs)
+        || value.result.ttlMs < 0
+        || (value.result.cacheScope !== "public" && value.result.cacheScope !== "private")) {
+        return null;
+    }
+    const hasNextCursor = hasOwn(value.result, "nextCursor");
+    if (hasNextCursor && typeof value.result.nextCursor !== "string")
+        return null;
+    return { tools: value.result.tools, hasNextCursor };
+}
+async function readBoundedRegularFile(filePath) {
+    let initial;
+    try {
+        initial = await lstat(filePath);
+    }
+    catch {
+        return { kind: "unavailable", bytesRead: 0 };
+    }
+    if (initial.isSymbolicLink())
+        return { kind: "symlink", bytesRead: 0 };
+    if (!initial.isFile())
+        return { kind: "not-regular", bytesRead: 0 };
+    if (!Number.isSafeInteger(initial.size) || initial.size < 0 || initial.size > MAX_FILE_BYTES) {
+        return { kind: "too-large", bytesRead: 0 };
+    }
+    const flags = process.platform === "win32"
+        ? constants.O_RDONLY
+        : constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK;
+    let fileHandle = null;
+    let bytesRead = 0;
+    try {
+        fileHandle = await open(filePath, flags);
+        const opened = await fileHandle.stat();
+        const current = await lstat(filePath);
+        if (!opened.isFile() || current.isSymbolicLink() || !current.isFile() || !sameSnapshot(initial, opened) || !sameSnapshot(opened, current)) {
+            return { kind: "changed", bytesRead };
+        }
+        if (!Number.isSafeInteger(opened.size) || opened.size < 0 || opened.size > MAX_FILE_BYTES) {
+            return { kind: "too-large", bytesRead };
+        }
+        const content = Buffer.alloc(opened.size);
+        while (bytesRead < content.length) {
+            const read = await fileHandle.read(content, bytesRead, content.length - bytesRead, bytesRead);
+            if (read.bytesRead === 0)
+                return { kind: "changed", bytesRead };
+            bytesRead += read.bytesRead;
+        }
+        const probe = Buffer.alloc(1);
+        const extra = await fileHandle.read(probe, 0, 1, bytesRead);
+        bytesRead += extra.bytesRead;
+        if (extra.bytesRead !== 0)
+            return { kind: "changed", bytesRead };
+        const completed = await fileHandle.stat();
+        const final = await lstat(filePath);
+        if (!final.isFile() || final.isSymbolicLink() || !sameSnapshot(opened, completed) || !sameSnapshot(completed, final)) {
+            return { kind: "changed", bytesRead };
+        }
+        return { kind: "content", content, bytesRead };
+    }
+    catch {
+        return { kind: "unavailable", bytesRead };
+    }
+    finally {
+        await fileHandle?.close().catch(() => undefined);
+    }
+}
+export async function loadMcpToolFileSnapshot(filePath) {
+    if (isBlockedOfflinePath(filePath)) {
+        return snapshot(blockedFileReport("offline-path-blocked", fileFinding("plugin.tools_file.path.blocked", "fail", "The local tool definition path is not permitted for offline inspection.", "The offline tool definition inspection does not access remote or device paths.", "Provide a local regular file path.")));
+    }
+    const file = await readBoundedRegularFile(filePath);
+    if (file.kind === "unavailable") {
+        return snapshot(incompleteFileReport(file.bytesRead, "file-unavailable", fileFinding("plugin.tools_file.file.unavailable", "fail", "The local tool definition file could not be read.", "The offline tool definition inspection could not start.", "Provide a readable local regular file.")));
+    }
+    if (file.kind === "too-large") {
+        return snapshot(incompleteFileReport(file.bytesRead, "file-size-limit", fileFinding("plugin.tools_file.file.too_large", "fail", "The local tool definition file exceeds the one MiB inspection limit.", "The offline tool definition inspection cannot safely read this file within its byte limit.", "Provide a tool definition file no larger than one MiB.")));
+    }
+    if (file.kind === "changed") {
+        return snapshot(incompleteFileReport(file.bytesRead, "file-changed", fileFinding("plugin.tools_file.file.changed", "fail", "The local tool definition file changed during inspection.", "The offline tool definition inspection cannot rely on an inconsistent file snapshot.", "Retry after the file is stable.")));
+    }
+    if (file.kind === "symlink") {
+        return snapshot(blockedFileReport("final-symlink", fileFinding("plugin.tools_file.file.symlink", "fail", "The local tool definition target is a symbolic link.", "The offline tool definition inspection does not follow final symbolic links.", "Provide a regular file directly.")));
+    }
+    if (file.kind === "not-regular") {
+        return snapshot(blockedFileReport("non-regular-file", fileFinding("plugin.tools_file.file.not_regular", "fail", "The local tool definition target is not a regular file.", "The offline tool definition inspection reads only bounded regular files.", "Provide a regular file directly.")));
+    }
+    let decoded;
+    try {
+        decoded = new TextDecoder("utf-8", { fatal: true }).decode(file.content);
+    }
+    catch {
+        return snapshot(incompleteFileReport(file.bytesRead, "invalid-utf8", fileFinding("plugin.tools_file.encoding.invalid", "fail", "The local tool definition file is not valid UTF-8.", "The offline tool definition inspection cannot parse the file safely.", "Save the tools/list response as UTF-8 JSON.")));
+    }
+    let value;
+    try {
+        value = JSON.parse(decoded);
+    }
+    catch {
+        return snapshot(incompleteFileReport(file.bytesRead, "invalid-json", fileFinding("plugin.tools_file.json.invalid", "fail", "The local tool definition file is not valid JSON.", "The offline tool definition inspection cannot parse the file safely.", "Provide one UTF-8 JSON-RPC tools/list response.")));
+    }
+    const parsed = parseToolsResult(value);
+    if (parsed === null) {
+        return snapshot(incompleteFileReport(file.bytesRead, "response-invalid", fileFinding("plugin.tools_file.response.invalid", "fail", "The local JSON value is not a supported complete tools/list response.", "The offline tool definition inspection cannot identify a valid tool list.", "Provide one JSON-RPC 2.0 complete tools/list result with valid cache metadata.")));
+    }
+    const findings = [];
+    const names = new Map();
+    let reason = null;
+    let toolsChecked = 0;
+    const addFindings = (items) => {
+        const remaining = MAX_FINDINGS - findings.length;
+        if (items.length > remaining) {
+            findings.push(...items.slice(0, remaining));
+            reason = "finding-limit";
+            return false;
+        }
+        findings.push(...items);
+        return true;
+    };
+    for (const tool of parsed.tools) {
+        if (toolsChecked >= MAX_TOOLS) {
+            reason = "tool-limit";
+            break;
+        }
+        toolsChecked += 1;
+        const location = { page: 1, toolIndex: toolsChecked };
+        if (!addFindings(inspectMcpToolDefinition(tool, location)))
+            break;
+        if (isJsonObject(tool) && typeof tool.name === "string") {
+            const previous = names.get(tool.name);
+            if (previous !== undefined && !addFindings([fileFinding("plugin.catalog.tool.name.duplicate", "warn", "Two enumerated tools use the same name.", "Duplicate tool names can make client selection ambiguous.", "Use a unique MCP tool name for each definition.")])) {
+                break;
+            }
+            if (previous !== undefined) {
+                findings[findings.length - 1] = {
+                    ...findings[findings.length - 1],
+                    location: { ...location, relatedToolIndex: previous }
+                };
+            }
+            else {
+                names.set(tool.name, toolsChecked);
+            }
+        }
+    }
+    if (reason === null && parsed.tools.length > MAX_TOOLS)
+        reason = "tool-limit";
+    if (reason === null && parsed.hasNextCursor)
+        reason = "more-pages-present";
+    if (reason !== null) {
+        return snapshot(report(file.bytesRead, "incomplete", {
+            complete: false,
+            toolsChecked,
+            hasNextCursor: parsed.hasNextCursor,
+            reason
+        }, findings), parsed.tools);
+    }
+    return snapshot(report(file.bytesRead, finalStatus(findings), {
+        complete: true,
+        toolsChecked,
+        hasNextCursor: false,
+        reason: null
+    }, findings), parsed.tools);
+}
+export async function inspectMcpToolFile(filePath) {
+    return (await loadMcpToolFileSnapshot(filePath)).report;
+}

package/dist/core/output-contract.js

@@ -714,8 +714,109 @@ const publicSchemaDefinitions = [
                 }
             }
         }
+    },
+    {
+        id: "doctor.tools.file.json",
+        command: "codex-plugin-doctor doctor tools-file <path> --json",
+        required: ["schemaVersion", "scope", "status", "source", "inspection", "coverage", "findings"],
+        properties: {
+            schemaVersion: { const: 1 },
+            scope: { const: "tool-definitions-file" },
+            status: { enum: ["pass", "warn", "fail", "incomplete", "blocked"] },
+            source: {
+                type: "object", required: ["kind", "format", "bytesRead"],
+                properties: {
+                    kind: { const: "file" }, format: { const: "mcp-tools-list-response" },
+                    bytesRead: { type: "integer", minimum: 0, maximum: 1048577 }
+                }, additionalProperties: false
+            },
+            inspection: {
+                type: "object", required: ["complete", "toolsChecked", "hasNextCursor", "reason"],
+                properties: {
+                    complete: { type: "boolean" }, toolsChecked: { type: "integer", minimum: 0, maximum: 500 },
+                    hasNextCursor: { type: ["boolean", "null"] }, reason: { type: ["string", "null"] }
+                }, additionalProperties: false
+            },
+            coverage: {
+                type: "object", required: ["schema", "discovery", "serverCatalog", "toolExecution", "fullConformance", "customHeaderAnnotations"],
+                properties: {
+                    schema: { const: "root-shape-only" }, discovery: { const: "not-tested" },
+                    serverCatalog: { const: "not-tested" }, toolExecution: { const: "not-tested" },
+                    fullConformance: { const: "not-tested" }, customHeaderAnnotations: { const: "not-tested" }
+                }, additionalProperties: false
+            },
+            findings: {
+                type: "array", maxItems: 100,
+                items: {
+                    type: "object", required: ["id", "severity", "message", "impact", "suggestedFix"],
+                    properties: {
+                        id: { type: "string", pattern: "^plugin\\.(tools_file|catalog)\\." },
+                        severity: { enum: ["warn", "fail"] },
+                        message: { type: "string" }, impact: { type: "string" }, suggestedFix: { type: "string" },
+                        location: {
+                            type: "object", required: ["page", "toolIndex"],
+                            properties: {
+                                page: { const: 1 }, toolIndex: { type: "integer", minimum: 1, maximum: 500 },
+                                schema: { enum: ["inputSchema", "outputSchema"] },
+                                relatedToolIndex: { type: "integer", minimum: 1, maximum: 500 }
+                            }, additionalProperties: false
+                        }
+                    }, additionalProperties: false
+                }
+            }
+        }
     }
 ];
+const toolFileReportDefinition = publicSchemaDefinitions.find((definition) => definition.id === "doctor.tools.file.json");
+const embeddedToolFileReportSchema = {
+    type: "object",
+    required: toolFileReportDefinition.required,
+    properties: toolFileReportDefinition.properties,
+    additionalProperties: true
+};
+publicSchemaDefinitions.push({
+    id: "doctor.tools.diff.json",
+    command: "codex-plugin-doctor doctor tools-diff --before <path> --after <path> --json",
+    required: ["schemaVersion", "scope", "status", "before", "after", "comparison", "coverage", "changes"],
+    properties: {
+        schemaVersion: { const: 1 },
+        scope: { const: "tool-definitions-diff" },
+        status: { enum: ["pass", "warn", "incomplete", "blocked"] },
+        before: embeddedToolFileReportSchema,
+        after: embeddedToolFileReportSchema,
+        comparison: {
+            type: "object", required: ["complete", "reason", "added", "removed", "changed", "unchanged"],
+            properties: {
+                complete: { type: "boolean" },
+                reason: { enum: [null, "input-blocked", "input-incomplete", "invalid-definitions", "ambiguous-names"] },
+                added: { type: ["integer", "null"], minimum: 0, maximum: 500 },
+                removed: { type: ["integer", "null"], minimum: 0, maximum: 500 },
+                changed: { type: ["integer", "null"], minimum: 0, maximum: 500 },
+                unchanged: { type: ["integer", "null"], minimum: 0, maximum: 500 }
+            }, additionalProperties: false
+        },
+        coverage: {
+            type: "object", required: ["comparison", "schema", "compatibility", "serverCatalog", "toolExecution"],
+            properties: {
+                comparison: { const: "structural-only" }, schema: { const: "root-shape-only" },
+                compatibility: { const: "not-tested" }, serverCatalog: { const: "not-tested" },
+                toolExecution: { const: "not-tested" }
+            }, additionalProperties: false
+        },
+        changes: {
+            type: "array", maxItems: 1000,
+            items: {
+                type: "object", required: ["kind", "beforeToolIndex", "afterToolIndex", "fields"],
+                properties: {
+                    kind: { enum: ["added", "removed", "changed"] },
+                    beforeToolIndex: { type: ["integer", "null"], minimum: 1, maximum: 500 },
+                    afterToolIndex: { type: ["integer", "null"], minimum: 1, maximum: 500 },
+                    fields: { type: "array", maxItems: 6, uniqueItems: true, items: { enum: ["inputSchema", "outputSchema", "description", "title", "annotations", "other"] } }
+                }, additionalProperties: false
+            }
+        }
+    }
+});
 function sha256(value) {
     return `sha256:${createHash("sha256").update(value).digest("hex")}`;
 }

package/dist/reporting/render-mcp-tool-diff-report.d.ts

@@ -0,0 +1,2 @@
+import type { McpToolDiffReport } from "../core/mcp-tool-diff.js";
+export declare function renderMcpToolDiffReport(report: McpToolDiffReport): string;

package/dist/reporting/render-mcp-tool-diff-report.js

@@ -0,0 +1,41 @@
+export function renderMcpToolDiffReport(report) {
+    const comparison = report.comparison;
+    return [
+        "Offline MCP Tool Diff",
+        "=====================",
+        `Status: ${report.status}`,
+        `Scope: ${report.scope}`,
+        `Comparison complete: ${comparison.complete}`,
+        ...(comparison.reason === null ? [] : [`Reason: ${comparison.reason}`]),
+        `Added: ${comparison.added ?? "not compared"}`,
+        `Removed: ${comparison.removed ?? "not compared"}`,
+        `Changed: ${comparison.changed ?? "not compared"}`,
+        `Unchanged: ${comparison.unchanged ?? "not compared"}`,
+        `Comparison coverage: ${report.coverage.comparison}`,
+        `Schema coverage: ${report.coverage.schema}`,
+        `Compatibility: ${report.coverage.compatibility}`,
+        `Server catalog: ${report.coverage.serverCatalog}`,
+        `Tool execution: ${report.coverage.toolExecution}`,
+        "Only the supplied responses are compared. A change does not establish incompatibility; an unchanged result does not establish compatibility.",
+        ...["before", "after"].flatMap((side) => {
+            const source = report[side];
+            const label = side === "before" ? "Before" : "After";
+            return [
+                `${label} input: ${source.status}; tools checked: ${source.inspection.toolsChecked}; bytes read: ${source.source.bytesRead}`,
+                ...(source.inspection.reason === null ? [] : [`${label} reason: ${source.inspection.reason}`]),
+                ...source.findings.map((finding) => {
+                    const location = finding.location;
+                    const locator = location ? ` [${side} tool ${location.toolIndex}${location.schema ? `, ${location.schema}` : ""}${location.relatedToolIndex ? `, related tool ${location.relatedToolIndex}` : ""}]` : "";
+                    return `${label} ${finding.severity.toUpperCase()} ${finding.id}${locator}: ${finding.message}\n  ${finding.suggestedFix}`;
+                })
+            ];
+        }),
+        ...report.changes.map((change) => {
+            const locations = [
+                ...(change.beforeToolIndex === null ? [] : [`before tool ${change.beforeToolIndex}`]),
+                ...(change.afterToolIndex === null ? [] : [`after tool ${change.afterToolIndex}`])
+            ];
+            return `${change.kind.toUpperCase()} [${locations.join(" -> ")}]${change.fields.length ? `: ${change.fields.join(", ")}` : ""}`;
+        })
+    ].join("\n");
+}

package/dist/reporting/render-mcp-tool-file-report.d.ts

@@ -0,0 +1,2 @@
+import type { McpToolFileReport } from "../core/mcp-tool-file.js";
+export declare function renderMcpToolFileReport(report: McpToolFileReport): string;

package/dist/reporting/render-mcp-tool-file-report.js

@@ -0,0 +1,26 @@
+export function renderMcpToolFileReport(report) {
+    return [
+        "Offline MCP Tool Definitions",
+        "============================",
+        `Status: ${report.status}`,
+        `Scope: ${report.scope}`,
+        `Source: ${report.source.kind} (${report.source.format})`,
+        `Bytes read: ${report.source.bytesRead}`,
+        `Inspection complete: ${report.inspection.complete}`,
+        `Tools checked: ${report.inspection.toolsChecked}`,
+        `More pages advertised: ${report.inspection.hasNextCursor ?? "unknown"}`,
+        ...(report.inspection.reason === null ? [] : [`Reason: ${report.inspection.reason}`]),
+        `Schema coverage: ${report.coverage.schema}`,
+        `Discovery: ${report.coverage.discovery}`,
+        `Server catalog: ${report.coverage.serverCatalog}`,
+        `Tool execution: ${report.coverage.toolExecution}`,
+        `Full conformance: ${report.coverage.fullConformance}`,
+        `Custom header annotations: ${report.coverage.customHeaderAnnotations}`,
+        "Only the supplied file was inspected. Its provenance and server completeness are not established.",
+        ...report.findings.map((finding) => {
+            const location = finding.location;
+            const locator = location ? ` [tool ${location.toolIndex}${location.schema ? `, ${location.schema}` : ""}${location.relatedToolIndex ? `, related tool ${location.relatedToolIndex}` : ""}]` : "";
+            return `${finding.severity.toUpperCase()} ${finding.id}${locator}: ${finding.message}\n  ${finding.suggestedFix}`;
+        })
+    ].join("\n");
+}

package/dist/run-cli.d.ts

@@ -1,5 +1,7 @@
 import { discoverMcpServer } from "./core/mcp-discovery.js";
 import { inspectMcpToolCatalog } from "./core/mcp-tool-catalog.js";
+import { inspectMcpToolFile } from "./core/mcp-tool-file.js";
+import { compareMcpToolFiles } from "./core/mcp-tool-diff.js";
 import { buildCorpusQualityMetricsDiffReport, buildCorpusQualityMetricsReport } from "./core/corpus-quality-metrics.js";
 import { runCheck } from "./index.js";
 import { writeRawDoctorConfig } from "./index.js";
@@ -15,6 +17,8 @@ export interface CliTerminalContext {
     platform?: NodeJS.Platform;
 }
 export interface RunCliOptions {
+    compareMcpToolFilesImpl?: typeof compareMcpToolFiles;
+    inspectMcpToolFileImpl?: typeof inspectMcpToolFile;
     inspectMcpToolCatalogImpl?: typeof inspectMcpToolCatalog;
     discoverMcpServerImpl?: typeof discoverMcpServer;
     terminalContext?: CliTerminalContext;

package/dist/run-cli.js

@@ -23,6 +23,10 @@ import { buildSubmissionArchivePreflight, submissionArchiveExitCode } from "./co
 import { buildSubmissionPreflight } from "./core/submission-preflight.js";
 import { discoverMcpServer } from "./core/mcp-discovery.js";
 import { inspectMcpToolCatalog } from "./core/mcp-tool-catalog.js";
+import { inspectMcpToolFile } from "./core/mcp-tool-file.js";
+import { compareMcpToolFiles } from "./core/mcp-tool-diff.js";
+import { renderMcpToolDiffReport } from "./reporting/render-mcp-tool-diff-report.js";
+import { renderMcpToolFileReport } from "./reporting/render-mcp-tool-file-report.js";
 import { renderMcpToolCatalogReport } from "./reporting/render-mcp-tool-catalog-report.js";
 import { renderMcpDiscoveryReport } from "./reporting/render-mcp-discovery-report.js";
 import { buildDoctorValidationCorpusReport, renderDoctorValidationCorpusJson, renderDoctorValidationCorpusReport } from "./core/validation-corpus.js";
@@ -103,6 +107,8 @@ function writeExactStdout(io, message) {
 }
 class CliUsageError extends Error {
 }
+const toolsDiffUsage = "Usage: codex-plugin-doctor doctor tools-diff --before <path> --after <path> [--json]";
+const toolsFileUsage = "Usage: codex-plugin-doctor doctor tools-file <path> [--json]";
 const toolsUsage = "Usage: codex-plugin-doctor doctor tools <url> --allow-network [--allow-local-network] [--json]";
 const discoveryUsage = "Usage: codex-plugin-doctor doctor discover <url> --allow-network [--allow-local-network] [--json]";
 function parseRuntimeSandbox(flags, options = { requireRuntime: true }) {
@@ -189,6 +195,8 @@ function printUsage(io) {
     io.writeStderr("Usage: codex-plugin-doctor check <path|--installed> [filter] [--policy codex-publish|mcp-strict|security] [--compat] [--json|--markdown|--badge-json|--badge-markdown] [--output <path>] [--history <path>] [--runtime [--allow-network [--allow-local-network]]] [--sandbox docker] [--require-runtime-approval --runtime-approval-digest <digest>] [--verbose-runtime] [--explain] [--no-animations] [--ascii] [--changed-since <ref>] [--fail-on <rule-id>]\n       codex-plugin-doctor audit --installed [filter] [--policy codex-publish|mcp-strict|security] [--security] [--compat] [--json] [--output <path>] [--cache] [--changed]\n       codex-plugin-doctor audit deps <path> [--policy codex-publish|mcp-strict|security] [--recommend] [--json|--sarif] [--output <path>]\n       codex-plugin-doctor mcp <path> [--runtime [--allow-network [--allow-local-network]]] [--json] [--output <path>]\n       codex-plugin-doctor security <path> [--policy security] [--json|--scorecard]\n       codex-plugin-doctor compat <path> [--all|--client <client>] [--json] [--scorecard] [--output <path>] [--install-preview|--apply --backup]\n       codex-plugin-doctor suppress add <path> [--fingerprint <sha256> --reason <text> --expires-at YYYY-MM-DD] [--config <path>] [--json]\n       codex-plugin-doctor suppress list <path> [--config <path>] [--json]\n       codex-plugin-doctor suppress remove <path> [--fingerprint <sha256>|--index <n>] [--config <path>] [--json]\n       codex-plugin-doctor fix <path> (--dry-run|--interactive --backup|--apply --backup)\n       codex-plugin-doctor history <history.jsonl> [--json] [--fail-on-regression]\n       codex-plugin-doctor watch <path> [--runtime] [--json] [--output <path>] [--debounce-ms <ms>] [--max-iterations <n>] [--fail-fast] [--accumulate-json <path>]\n       codex-plugin-doctor doctor [npm <package>|contract|corpus [--manifest <corpus.json>] [--json] [--output <path>]|corpus metrics --manifest <corpus.json> [--json|--markdown] [--output <path>] [--min-precision <0..1>] [--min-recall <0..1>] [--max-false-positive-rate <0..1>]|runtime-plan <path> [--sandbox docker] [--json|--markdown] [--output <path>]|runtime-policy <path> [--sandbox docker] [--json] [--output <path>]|review-bundle <path> --output <dir> --sign-key-env NAME [--json] [--allow-dirty] [--allow-untagged]|review-bundle verify <bundle-dir> --target <path> --sign-key-env NAME [--json] [--output <path>] [--failures-only]|review-bundle diff --before <dir> --after <dir> [--json]|attest <path> [--sign-key-env NAME]|attest verify <attestation.json> --target <path> --sign-key-env NAME|release-evidence <path> --sign-key-env NAME [--runtime [--allow-network [--allow-local-network]]] [--sandbox docker] [--allow-dirty] [--allow-untagged] [--require-runtime-approval --runtime-approval-digest <digest>]|release-evidence verify <evidence.json> --target <path> --sign-key-env NAME|release-evidence asset <path> --tag <tag> --output <evidence.json> --sign-key-env NAME [--runtime [--allow-network [--allow-local-network]]] [--sandbox docker] [--allow-dirty] [--allow-untagged] [--require-runtime-approval --runtime-approval-digest <digest>] [--upload]|mcp <path> [--runtime [--allow-network [--allow-local-network]]]|inspector <path>|diff --before <path> --after <path>|recommend <path>|trust <path>|perf <path> [--max-total-ms <ms>] [--max-stage-ms stage=ms]|export --bundle <path>|snapshot|clients|--json|--update-check]\n       codex-plugin-doctor init [path] [--template skill-only|mcp-stdio|mcp-http|full-runtime]\n       codex-plugin-doctor init-ci [path]\n       codex-plugin-doctor init-git-hooks [path] [--force] [--json]\n       codex-plugin-doctor init-git-hooks [path] --remove [--json]\n       codex-plugin-doctor completion bash|zsh|fish\n       codex-plugin-doctor config validate <path> [--json]\n       codex-plugin-doctor release check <path> [--json] [--runtime [--allow-network [--allow-local-network]]] [--sandbox docker]\n       codex-plugin-doctor self-test\n       codex-plugin-doctor list --installed\n       codex-plugin-doctor explain <finding-id>\n       codex-plugin-doctor --version\n\nFirst run:\n       codex-plugin-doctor doctor\n       codex-plugin-doctor self-test\n       codex-plugin-doctor init my-plugin\n       codex-plugin-doctor check . --runtime --explain");
     io.writeStderr(discoveryUsage);
     io.writeStderr(toolsUsage);
+    io.writeStderr(toolsFileUsage);
+    io.writeStderr(toolsDiffUsage);
     io.writeStderr("Registry readiness: codex-plugin-doctor registry check <server.json|directory> [--json] [--output <path>] [--require-registry-readiness]\n"
         + "       codex-plugin-doctor registry inspect <server-name> --allow-network [--json] [--output <path>] [--require-registry-readiness]\n"
         + "Registry publication preflight: codex-plugin-doctor registry preflight <server.json|directory> [--allow-network] [--json] [--output <path>] [--require-publish-ready]");
@@ -1199,6 +1207,62 @@ export async function runCli(args, io = defaultIo, options = {}) {
         return 0;
     }
     if (command === "doctor") {
+        if (maybePath === "tools-diff") {
+            if (remainingArgs.length === 1 && remainingArgs[0] === "--help") {
+                io.writeStdout(`${toolsDiffUsage}\nCompares two saved MCP tools/list responses offline. Structural changes only; compatibility is not tested.`);
+                return 0;
+            }
+            let beforePath;
+            let afterPath;
+            let json = false;
+            let invalid = false;
+            for (let index = 0; index < remainingArgs.length; index += 1) {
+                const flag = remainingArgs[index];
+                if (flag === "--json" && !json) {
+                    json = true;
+                }
+                else if ((flag === "--before" && beforePath === undefined) || (flag === "--after" && afterPath === undefined)) {
+                    const value = remainingArgs[index + 1];
+                    if (!value || value.startsWith("-")) {
+                        invalid = true;
+                        break;
+                    }
+                    if (flag === "--before")
+                        beforePath = value;
+                    else
+                        afterPath = value;
+                    index += 1;
+                }
+                else {
+                    invalid = true;
+                    break;
+                }
+            }
+            if (invalid || !beforePath || !afterPath) {
+                io.writeStderr(`Invalid comparison arguments. ${toolsDiffUsage}`);
+                return 2;
+            }
+            const report = await (options.compareMcpToolFilesImpl ?? compareMcpToolFiles)(beforePath, afterPath);
+            io.writeStdout(json ? JSON.stringify(report, null, 2) : renderMcpToolDiffReport(report));
+            return report.status === "pass" ? 0 : report.status === "warn" ? 1 : 2;
+        }
+        if (maybePath === "tools-file") {
+            if (remainingArgs.length === 1 && remainingArgs[0] === "--help") {
+                io.writeStdout(`${toolsFileUsage}\nInspects one saved UTF-8 MCP tools/list response. No server connection or tool execution.`);
+                return 0;
+            }
+            const [filePath, ...flags] = remainingArgs;
+            if (!filePath || filePath.startsWith("-") || flags.some((flag) => flag !== "--json") || flags.length > 1) {
+                io.writeStderr(`Invalid file inspection arguments. ${toolsFileUsage}`);
+                return 2;
+            }
+            const report = await (options.inspectMcpToolFileImpl ?? inspectMcpToolFile)(filePath);
+            io.writeStdout(flags.includes("--json")
+                ? JSON.stringify(report, null, 2)
+                : renderMcpToolFileReport(report));
+            return report.status === "pass" ? 0
+                : report.status === "warn" || report.status === "fail" ? 1 : 2;
+        }
         if (maybePath === "tools") {
             if (remainingArgs.length === 1 && remainingArgs[0] === "--help") {
                 io.writeStdout(`${toolsUsage}\nHTTP tool catalog structure only; tools are not executed.`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-plugin-doctor",
-  "version": "1.62.0",
+  "version": "1.64.0",
   "description": "CLI-first validator for Codex plugins, skills, and MCP package surfaces with runtime MCP protocol validation.",
   "type": "module",
   "main": "./dist/index.js",