codex-plugin-doctor 1.25.0 → 1.26.0

package/README.md

@@ -314,7 +314,7 @@ codex-plugin-doctor check . --json --runtime --verbose-runtime
 
 `init [path] --template ...` creates targeted starter packages. `skill-only` is the default minimal skill package, `mcp-stdio` adds a local stdio MCP config and mock server, `mcp-http` scaffolds a streamable HTTP MCP config, and `full-runtime` generates a stdio sample that passes the runtime protocol probes.
 
-`security <path>` renders a focused package security scorecard. It reuses the existing package security findings, then adds deeper MCP command-surface checks for shell wrappers, encoded shell payloads, remote pipe-to-shell startup patterns, `cwd` values outside the plugin root, and plain HTTP URLs. Security findings include structured evidence where available, such as server names, config paths, env keys, arg flags, and escaped paths. Findings also include deterministic SHA-256 fingerprints derived from the rule ID and canonical evidence, with package paths normalized for cross-machine stability. Use `--json` for automation or `--scorecard` for a compact status view.
+`security <path>` renders a focused package security scorecard. It reuses the existing package security findings, then adds deeper MCP command-surface checks for shell wrappers, encoded shell payloads, remote pipe-to-shell startup patterns, `cwd` values outside the plugin root, and plain HTTP URLs. Findings include structured, instance-specific evidence such as manifest fields, skill paths, server names, protocol methods, dependency sections, env keys, and bounded payload lengths. Deterministic SHA-256 fingerprints derive from the rule ID and canonical evidence, with package paths normalized for cross-machine stability. Secrets, prompt bodies, resource contents, tool payloads, stderr, and encoded commands are not copied into evidence. Use `--json` for automation or `--scorecard` for a compact status view.
 
 `compat --client claude-desktop` checks whether the MCP package can be added to the local Claude Desktop setup. On Windows it looks for `%APPDATA%\Claude\claude_desktop_config.json`; on macOS it looks for `~/Library/Application Support/Claude/claude_desktop_config.json`. A valid existing config returns `PASS`, a missing Claude Desktop install returns `WARN`, and a malformed local config returns `FAIL` so you do not add new servers into a broken config file. If the package server name already exists in Claude Desktop, the command returns `WARN` with the duplicate server name. Add `--install-preview` to print the JSON snippet that should be merged into `claude_desktop_config.json`; it does not modify files. Use `--apply --backup` only when you want the CLI to create a timestamped backup and merge the server config. Apply mode refuses to overwrite duplicate server names.
 
@@ -370,9 +370,9 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
-      - uses: Esquetta/CodexPluginDoctor@v1.25.0
+      - uses: Esquetta/CodexPluginDoctor@v1.26.0
         with:
-          version: "1.25.0"
+          version: "1.26.0"
           path: .
           runtime: "true"
           policy: codex-publish

package/dist/core/runtime-probe.js

@@ -21,22 +21,55 @@ function createRuntimeScorecard() {
         promptGet: "unsupported"
     };
 }
-function buildFailure(id, message, impact, suggestedFix) {
+function buildFailure(id, message, impact, suggestedFix, evidence) {
     return {
         id,
         severity: "fail",
         message,
         impact,
-        suggestedFix
+        suggestedFix,
+        ...(evidence ? { evidence } : {})
     };
 }
-function buildWarning(id, message, impact, suggestedFix) {
+function buildWarning(id, message, impact, suggestedFix, evidence) {
     return {
         id,
         severity: "warn",
         message,
         impact,
-        suggestedFix
+        suggestedFix,
+        ...(evidence ? { evidence } : {})
+    };
+}
+function methodForRuntimeFinding(id) {
+    if (id.includes(".initialize."))
+        return "initialize";
+    if (id.includes(".tools_list."))
+        return "tools/list";
+    if (id.includes(".tool_call."))
+        return "tools/call";
+    if (id.includes(".resources_list."))
+        return "resources/list";
+    if (id.includes(".resource_read."))
+        return "resources/read";
+    if (id.includes(".resource_templates_list."))
+        return "resources/templates/list";
+    if (id.includes(".prompts_list."))
+        return "prompts/list";
+    if (id.includes(".prompt_get."))
+        return "prompts/get";
+    if (id.includes(".startup.") || id.includes(".exited_early"))
+        return "startup";
+    return "protocol";
+}
+function withRuntimeEvidence(finding, serverName) {
+    return {
+        ...finding,
+        evidence: {
+            serverName,
+            method: methodForRuntimeFinding(finding.id),
+            ...(finding.evidence ?? {})
+        }
     };
 }
 function isPlainObject(value) {
@@ -511,55 +544,56 @@ function getContentBlockLength(content) {
     }
     return 0;
 }
-function collectOversizedToolCallWarnings(message) {
+function collectOversizedToolCallWarnings(message, evidence) {
     if (!isPlainObject(message.result) || !Array.isArray(message.result.content)) {
         return [];
     }
-    const hasOversizedContent = message.result.content.some((content) => {
-        return isPlainObject(content) && getContentBlockLength(content) > MAX_TOOL_CALL_CONTENT_LENGTH;
-    });
-    if (!hasOversizedContent) {
+    const contentLength = message.result.content.reduce((maximum, content) => {
+        return isPlainObject(content)
+            ? Math.max(maximum, getContentBlockLength(content))
+            : maximum;
+    }, 0);
+    if (contentLength <= MAX_TOOL_CALL_CONTENT_LENGTH) {
         return [];
     }
     return [
-        buildWarning("plugin.runtime.tool_call.content_too_large", "The tools/call response contains unusually large content payloads.", "Large tool call payloads increase runtime cost, transcript size, and the risk of degraded model performance.", "Keep tool responses concise or move large payloads into resource references instead of inline content.")
+        buildWarning("plugin.runtime.tool_call.content_too_large", "The tools/call response contains unusually large content payloads.", "Large tool call payloads increase runtime cost, transcript size, and the risk of degraded model performance.", "Keep tool responses concise or move large payloads into resource references instead of inline content.", { ...evidence, contentLength })
     ];
 }
-function collectOversizedResourceReadWarnings(message) {
+function collectOversizedResourceReadWarnings(message, evidence) {
     if (!isPlainObject(message.result) || !Array.isArray(message.result.contents)) {
         return [];
     }
-    const hasOversizedContent = message.result.contents.some((content) => {
+    const contentLength = message.result.contents.reduce((maximum, content) => {
         if (!isPlainObject(content)) {
-            return false;
+            return maximum;
         }
         const textLength = typeof content.text === "string" ? content.text.length : 0;
         const blobLength = typeof content.blob === "string" ? content.blob.length : 0;
-        return (textLength > MAX_RESOURCE_READ_CONTENT_LENGTH ||
-            blobLength > MAX_RESOURCE_READ_CONTENT_LENGTH);
-    });
-    if (!hasOversizedContent) {
+        return Math.max(maximum, textLength, blobLength);
+    }, 0);
+    if (contentLength <= MAX_RESOURCE_READ_CONTENT_LENGTH) {
         return [];
     }
     return [
-        buildWarning("plugin.runtime.resource_read.content_too_large", "The resources/read response contains unusually large resource payloads.", "Large resource contents increase runtime cost and can make downstream model use less reliable.", "Reduce inline resource size or break large resources into smaller references.")
+        buildWarning("plugin.runtime.resource_read.content_too_large", "The resources/read response contains unusually large resource payloads.", "Large resource contents increase runtime cost and can make downstream model use less reliable.", "Reduce inline resource size or break large resources into smaller references.", { ...evidence, contentLength })
     ];
 }
-function collectOversizedPromptGetWarnings(message) {
+function collectOversizedPromptGetWarnings(message, evidence) {
     if (!isPlainObject(message.result) || !Array.isArray(message.result.messages)) {
         return [];
     }
-    const hasOversizedContent = message.result.messages.some((promptMessage) => {
+    const contentLength = message.result.messages.reduce((maximum, promptMessage) => {
         if (!isPlainObject(promptMessage) || !isPlainObject(promptMessage.content)) {
-            return false;
+            return maximum;
         }
-        return getContentBlockLength(promptMessage.content) > MAX_PROMPT_GET_CONTENT_LENGTH;
-    });
-    if (!hasOversizedContent) {
+        return Math.max(maximum, getContentBlockLength(promptMessage.content));
+    }, 0);
+    if (contentLength <= MAX_PROMPT_GET_CONTENT_LENGTH) {
         return [];
     }
     return [
-        buildWarning("plugin.runtime.prompt_get.content_too_large", "The prompts/get response contains unusually large prompt message payloads.", "Large prompt bodies increase token cost and reduce the usefulness of prompt probing as a lightweight validation step.", "Keep prompt message content concise or move large context into resources.")
+        buildWarning("plugin.runtime.prompt_get.content_too_large", "The prompts/get response contains unusually large prompt message payloads.", "Large prompt bodies increase token cost and reduce the usefulness of prompt probing as a lightweight validation step.", "Keep prompt message content concise or move large context into resources.", { ...evidence, contentLength })
     ];
 }
 async function probeCommandServer(input) {
@@ -596,7 +630,10 @@ async function probeCommandServer(input) {
                 child.kill("SIGTERM");
             }
             resolve({
-                findings: [...warnings, ...(finding ? [finding] : [])],
+                findings: [
+                    ...warnings.map((warning) => withRuntimeEvidence(warning, serverName)),
+                    ...(finding ? [withRuntimeEvidence(finding, serverName)] : [])
+                ],
                 scorecard
             });
         };
@@ -752,14 +789,16 @@ async function probeCommandServer(input) {
                 const toolCallResponse = await sendRequest("tools/call", {
                     name: callableTool.tool.name,
                     arguments: callableTool.args
-                }, buildFailure("plugin.runtime.tool_call.timeout", `The MCP server \`${serverName}\` did not answer the tools/call request in time.`, "A server that cannot complete a basic tool invocation in time will feel broken in real Codex usage.", "Inspect the selected tool implementation and reduce its response latency."));
+                }, buildFailure("plugin.runtime.tool_call.timeout", `The MCP server \`${serverName}\` did not answer the tools/call request in time.`, "A server that cannot complete a basic tool invocation in time will feel broken in real Codex usage.", "Inspect the selected tool implementation and reduce its response latency.", { toolName: callableTool.tool.name }));
                 if (isErrorResponse(toolCallResponse) || !isValidCallToolResult(toolCallResponse)) {
                     scorecard.toolsCall = "fail";
-                    settle(buildFailure("plugin.runtime.tool_call.invalid", `The MCP server \`${serverName}\` returned an invalid tools/call result.`, "Codex cannot safely consume malformed tool call results from the server.", "Return a CallToolResult with a `content` array containing valid MCP content blocks."));
+                    settle(buildFailure("plugin.runtime.tool_call.invalid", `The MCP server \`${serverName}\` returned an invalid tools/call result.`, "Codex cannot safely consume malformed tool call results from the server.", "Return a CallToolResult with a `content` array containing valid MCP content blocks.", { toolName: callableTool.tool.name }));
                     return;
                 }
                 scorecard.toolsCall = "pass";
-                warnings.push(...collectOversizedToolCallWarnings(toolCallResponse));
+                warnings.push(...collectOversizedToolCallWarnings(toolCallResponse, {
+                    toolName: callableTool.tool.name
+                }));
             }
             if (!hasResourcesCapability(initializeResponse)) {
                 scorecard.resourcesList = "unsupported";
@@ -781,15 +820,17 @@ async function probeCommandServer(input) {
                 if (resources.length > 0) {
                     const resourceReadResponse = await sendRequest("resources/read", {
                         uri: resources[0].uri
-                    }, buildFailure("plugin.runtime.resource_read.timeout", `The MCP server \`${serverName}\` did not answer the resources/read request in time.`, "A server that lists resources but cannot read them in time will feel broken in Codex.", "Inspect the resource read path and reduce latency before returning resource contents."));
+                    }, buildFailure("plugin.runtime.resource_read.timeout", `The MCP server \`${serverName}\` did not answer the resources/read request in time.`, "A server that lists resources but cannot read them in time will feel broken in Codex.", "Inspect the resource read path and reduce latency before returning resource contents.", { resourceUri: resources[0].uri }));
                     if (isErrorResponse(resourceReadResponse) ||
                         !isValidReadResourceResult(resourceReadResponse)) {
                         scorecard.resourceRead = "fail";
-                        settle(buildFailure("plugin.runtime.resource_read.invalid", `The MCP server \`${serverName}\` returned an invalid resources/read result.`, "Codex cannot safely consume malformed resource contents from `resources/read`.", "Return a `contents` array where each entry has a string `uri` plus either string `text` or string `blob`."));
+                        settle(buildFailure("plugin.runtime.resource_read.invalid", `The MCP server \`${serverName}\` returned an invalid resources/read result.`, "Codex cannot safely consume malformed resource contents from `resources/read`.", "Return a `contents` array where each entry has a string `uri` plus either string `text` or string `blob`.", { resourceUri: resources[0].uri }));
                         return;
                     }
                     scorecard.resourceRead = "pass";
-                    warnings.push(...collectOversizedResourceReadWarnings(resourceReadResponse));
+                    warnings.push(...collectOversizedResourceReadWarnings(resourceReadResponse, {
+                        resourceUri: resources[0].uri
+                    }));
                 }
                 else {
                     scorecard.resourceRead = "skipped";
@@ -842,15 +883,17 @@ async function probeCommandServer(input) {
                         ...(buildPromptArguments(promptForGet)
                             ? { arguments: buildPromptArguments(promptForGet) }
                             : {})
-                    }, buildFailure("plugin.runtime.prompt_get.timeout", `The MCP server \`${serverName}\` did not answer the prompts/get request in time.`, "A server that lists prompts but cannot return prompt content in time will feel broken in Codex.", "Inspect the prompt retrieval path and reduce latency before returning prompt messages."));
+                    }, buildFailure("plugin.runtime.prompt_get.timeout", `The MCP server \`${serverName}\` did not answer the prompts/get request in time.`, "A server that lists prompts but cannot return prompt content in time will feel broken in Codex.", "Inspect the prompt retrieval path and reduce latency before returning prompt messages.", { promptName: promptForGet.name }));
                     if (isErrorResponse(promptGetResponse) ||
                         !isValidPromptGetResult(promptGetResponse)) {
                         scorecard.promptGet = "fail";
-                        settle(buildFailure("plugin.runtime.prompt_get.invalid", `The MCP server \`${serverName}\` returned an invalid prompts/get result.`, "Codex cannot safely consume malformed prompt messages from `prompts/get`.", "Return a `messages` array where each entry has a valid `role` and a valid MCP content block."));
+                        settle(buildFailure("plugin.runtime.prompt_get.invalid", `The MCP server \`${serverName}\` returned an invalid prompts/get result.`, "Codex cannot safely consume malformed prompt messages from `prompts/get`.", "Return a `messages` array where each entry has a valid `role` and a valid MCP content block.", { promptName: promptForGet.name }));
                         return;
                     }
                     scorecard.promptGet = "pass";
-                    warnings.push(...collectOversizedPromptGetWarnings(promptGetResponse));
+                    warnings.push(...collectOversizedPromptGetWarnings(promptGetResponse, {
+                        promptName: promptForGet.name
+                    }));
                 }
             }
             settle(null);

package/dist/core/validate-plugin.js

@@ -193,19 +193,20 @@ function isDescriptionLikelyVerbose(description, mode) {
 }
 function validateRequiredManifestFields(discoveredPackage) {
     const findings = [];
-    const { manifest } = discoveredPackage;
+    const { manifest, rootPath } = discoveredPackage;
+    const manifestPath = relativePackagePath(rootPath, discoveredPackage.manifestPath);
     if (!manifest.name) {
-        findings.push(buildFailure("plugin.manifest.name.missing", "The plugin manifest is missing a `name` field.", "Codex cannot identify the plugin reliably without a stable package name.", "Add a kebab-case `name` field to `.codex-plugin/plugin.json`."));
+        findings.push(buildFailure("plugin.manifest.name.missing", "The plugin manifest is missing a `name` field.", "Codex cannot identify the plugin reliably without a stable package name.", "Add a kebab-case `name` field to `.codex-plugin/plugin.json`.", { manifestPath, field: "name" }));
     }
     if (!manifest.version) {
-        findings.push(buildFailure("plugin.manifest.version.missing", "The plugin manifest is missing a `version` field.", "Release and compatibility workflows cannot reason about the package version.", "Add a semantic `version` field to `.codex-plugin/plugin.json`."));
+        findings.push(buildFailure("plugin.manifest.version.missing", "The plugin manifest is missing a `version` field.", "Release and compatibility workflows cannot reason about the package version.", "Add a semantic `version` field to `.codex-plugin/plugin.json`.", { manifestPath, field: "version" }));
     }
     if (!manifest.description) {
-        findings.push(buildFailure("plugin.manifest.description.missing", "The plugin manifest is missing a `description` field.", "The package will be harder to understand and present in Codex surfaces.", "Add a concise `description` field to `.codex-plugin/plugin.json`."));
+        findings.push(buildFailure("plugin.manifest.description.missing", "The plugin manifest is missing a `description` field.", "The package will be harder to understand and present in Codex surfaces.", "Add a concise `description` field to `.codex-plugin/plugin.json`.", { manifestPath, field: "description" }));
     }
     if (manifest.description &&
         isDescriptionLikelyVerbose(manifest.description, "plugin")) {
-        findings.push(buildWarning("plugin.heuristic.description.too_long", "The plugin manifest description is likely too verbose.", "Overly long metadata increases context cost and can dilute plugin discovery quality.", "Shorten the manifest description to a precise one- or two-sentence summary."));
+        findings.push(buildWarning("plugin.heuristic.description.too_long", "The plugin manifest description is likely too verbose.", "Overly long metadata increases context cost and can dilute plugin discovery quality.", "Shorten the manifest description to a precise one- or two-sentence summary.", { manifestPath, field: "description" }));
     }
     return findings;
 }
@@ -230,7 +231,12 @@ async function validateSkillsDirectory(discoveredPackage) {
         return [];
     }
     return [
-        buildFailure("plugin.skills.path.missing", "The plugin manifest points to a missing skills directory.", "Codex will not be able to load the packaged skills as expected.", `Create the skills directory at \`${skillsPath}\` or update the manifest path.`)
+        buildFailure("plugin.skills.path.missing", "The plugin manifest points to a missing skills directory.", "Codex will not be able to load the packaged skills as expected.", `Create the skills directory at \`${skillsPath}\` or update the manifest path.`, {
+            manifestPath: relativePackagePath(rootPath, discoveredPackage.manifestPath),
+            field: "skills",
+            configuredPath: manifest.skills,
+            resolvedPath: skillsPath
+        })
     ];
 }
 async function validateSkillDefinitions(discoveredPackage) {
@@ -254,27 +260,47 @@ async function validateSkillDefinitions(discoveredPackage) {
         const skillFilePath = path.join(skillRoot, "SKILL.md");
         const skillFileExists = await fileExists(skillFilePath);
         if (!skillFileExists) {
-            findings.push(buildFailure("plugin.skill.skill_md.missing", `The skill \`${skillDirectory.name}\` is missing \`SKILL.md\`.`, "Codex cannot load a skill directory that does not contain the required SKILL.md entrypoint.", `Add \`SKILL.md\` to \`${skillRoot}\` with at least \`name\` and \`description\` frontmatter.`));
+            findings.push(buildFailure("plugin.skill.skill_md.missing", `The skill \`${skillDirectory.name}\` is missing \`SKILL.md\`.`, "Codex cannot load a skill directory that does not contain the required SKILL.md entrypoint.", `Add \`SKILL.md\` to \`${skillRoot}\` with at least \`name\` and \`description\` frontmatter.`, {
+                skillName: skillDirectory.name,
+                skillPath: relativePackagePath(rootPath, skillFilePath)
+            }));
             continue;
         }
         const skillContent = await readFile(skillFilePath, "utf8");
         const frontmatter = parseSkillFrontmatter(skillContent);
         if (!frontmatter?.name) {
-            findings.push(buildFailure("plugin.skill.name.missing", `The skill \`${skillDirectory.name}\` is missing a \`name\` field in frontmatter.`, "Codex cannot expose skill metadata correctly without a stable skill name.", `Add a \`name\` field to the frontmatter in \`${skillFilePath}\`.`));
+            findings.push(buildFailure("plugin.skill.name.missing", `The skill \`${skillDirectory.name}\` is missing a \`name\` field in frontmatter.`, "Codex cannot expose skill metadata correctly without a stable skill name.", `Add a \`name\` field to the frontmatter in \`${skillFilePath}\`.`, {
+                skillName: skillDirectory.name,
+                skillPath: relativePackagePath(rootPath, skillFilePath),
+                field: "name"
+            }));
         }
         if (!frontmatter?.description) {
-            findings.push(buildFailure("plugin.skill.description.missing", `The skill \`${skillDirectory.name}\` is missing a \`description\` field in frontmatter.`, "Codex uses skill descriptions for discovery and implicit matching, so missing descriptions reduce skill usability.", `Add a scoped \`description\` field to the frontmatter in \`${skillFilePath}\`.`));
+            findings.push(buildFailure("plugin.skill.description.missing", `The skill \`${skillDirectory.name}\` is missing a \`description\` field in frontmatter.`, "Codex uses skill descriptions for discovery and implicit matching, so missing descriptions reduce skill usability.", `Add a scoped \`description\` field to the frontmatter in \`${skillFilePath}\`.`, {
+                skillName: skillDirectory.name,
+                skillPath: relativePackagePath(rootPath, skillFilePath),
+                field: "description"
+            }));
         }
         if (frontmatter?.description &&
             isDescriptionLikelyVerbose(frontmatter.description, "skill")) {
-            findings.push(buildWarning("plugin.heuristic.skill_description.too_long", `The skill \`${skillDirectory.name}\` description is likely too verbose.`, "Overly long skill descriptions increase context cost and reduce the precision of skill matching.", `Shorten the \`description\` field in \`${skillFilePath}\` to a tightly scoped summary.`));
+            findings.push(buildWarning("plugin.heuristic.skill_description.too_long", `The skill \`${skillDirectory.name}\` description is likely too verbose.`, "Overly long skill descriptions increase context cost and reduce the precision of skill matching.", `Shorten the \`description\` field in \`${skillFilePath}\` to a tightly scoped summary.`, {
+                skillName: skillDirectory.name,
+                skillPath: relativePackagePath(rootPath, skillFilePath),
+                field: "description"
+            }));
         }
         for (const supportReference of extractSupportAssetReferences(skillContent)) {
             const supportPath = path.resolve(skillRoot, supportReference);
             const supportFileExists = await fileExists(supportPath);
             const supportDirectoryExists = await directoryExists(supportPath);
             if (!supportFileExists && !supportDirectoryExists) {
-                findings.push(buildWarning("plugin.skill.asset_reference.missing", `The skill \`${skillDirectory.name}\` references missing support asset \`${supportReference}\`.`, "Skills that point to missing scripts, templates, assets, or examples are harder to execute and can fail when an agent follows the instructions.", `Create \`${supportPath}\` or update the reference in \`${skillFilePath}\`.`));
+                findings.push(buildWarning("plugin.skill.asset_reference.missing", `The skill \`${skillDirectory.name}\` references missing support asset \`${supportReference}\`.`, "Skills that point to missing scripts, templates, assets, or examples are harder to execute and can fail when an agent follows the instructions.", `Create \`${supportPath}\` or update the reference in \`${skillFilePath}\`.`, {
+                    skillName: skillDirectory.name,
+                    skillPath: relativePackagePath(rootPath, skillFilePath),
+                    assetReference: supportReference,
+                    assetPath: relativePackagePath(rootPath, supportPath)
+                }));
             }
         }
     }
@@ -299,7 +325,12 @@ async function validateMcpConfig(discoveredPackage) {
     const mcpConfigExists = await fileExists(mcpConfigPath);
     if (!mcpConfigExists) {
         return [
-            buildFailure("plugin.mcp.path.missing", "The plugin manifest points to a missing `.mcp.json` file.", "Codex cannot load bundled MCP server definitions if the referenced config file does not exist.", `Create \`${mcpConfigPath}\` or update the manifest \`mcpServers\` path.`)
+            buildFailure("plugin.mcp.path.missing", "The plugin manifest points to a missing `.mcp.json` file.", "Codex cannot load bundled MCP server definitions if the referenced config file does not exist.", `Create \`${mcpConfigPath}\` or update the manifest \`mcpServers\` path.`, {
+                manifestPath: relativePackagePath(rootPath, discoveredPackage.manifestPath),
+                field: "mcpServers",
+                configuredPath: manifest.mcpServers,
+                configPath: relativePackagePath(rootPath, mcpConfigPath)
+            })
         ];
     }
     let parsedConfig;
@@ -308,31 +339,42 @@ async function validateMcpConfig(discoveredPackage) {
     }
     catch {
         return [
-            buildFailure("plugin.mcp.invalid_json", "The referenced `.mcp.json` file is not valid JSON.", "Codex will not be able to parse bundled MCP server configuration.", `Fix the JSON syntax in \`${mcpConfigPath}\`.`)
+            buildFailure("plugin.mcp.invalid_json", "The referenced `.mcp.json` file is not valid JSON.", "Codex will not be able to parse bundled MCP server configuration.", `Fix the JSON syntax in \`${mcpConfigPath}\`.`, { configPath: relativePackagePath(rootPath, mcpConfigPath), field: "json" })
         ];
     }
     if (!isPlainObject(parsedConfig)) {
         return [
-            buildFailure("plugin.mcp.invalid_shape", "The referenced `.mcp.json` file must contain a JSON object.", "Codex expects bundled MCP configuration to be object-shaped so server entries can be resolved reliably.", `Wrap the MCP configuration in a top-level object inside \`${mcpConfigPath}\`.`)
+            buildFailure("plugin.mcp.invalid_shape", "The referenced `.mcp.json` file must contain a JSON object.", "Codex expects bundled MCP configuration to be object-shaped so server entries can be resolved reliably.", `Wrap the MCP configuration in a top-level object inside \`${mcpConfigPath}\`.`, { configPath: relativePackagePath(rootPath, mcpConfigPath), field: "root" })
         ];
     }
     const servers = parsedConfig.mcpServers;
     if (!isPlainObject(servers) || Object.keys(servers).length === 0) {
         return [
-            buildFailure("plugin.mcp.invalid_shape", "The referenced `.mcp.json` file must contain a non-empty `mcpServers` object.", "Without a valid `mcpServers` object, Codex cannot discover the bundled MCP server definitions.", `Define bundled servers under \`mcpServers\` in \`${mcpConfigPath}\`.`)
+            buildFailure("plugin.mcp.invalid_shape", "The referenced `.mcp.json` file must contain a non-empty `mcpServers` object.", "Without a valid `mcpServers` object, Codex cannot discover the bundled MCP server definitions.", `Define bundled servers under \`mcpServers\` in \`${mcpConfigPath}\`.`, {
+                configPath: relativePackagePath(rootPath, mcpConfigPath),
+                field: "mcpServers"
+            })
         ];
     }
     const findings = [];
     for (const [serverName, serverConfig] of Object.entries(servers)) {
         if (!isPlainObject(serverConfig)) {
-            findings.push(buildFailure("plugin.mcp.server.invalid", `The MCP server \`${serverName}\` must be configured as an object.`, "Codex cannot interpret a server entry unless it is represented as an object with server options.", `Change the \`${serverName}\` entry in \`${mcpConfigPath}\` to an object.`));
+            findings.push(buildFailure("plugin.mcp.server.invalid", `The MCP server \`${serverName}\` must be configured as an object.`, "Codex cannot interpret a server entry unless it is represented as an object with server options.", `Change the \`${serverName}\` entry in \`${mcpConfigPath}\` to an object.`, {
+                configPath: relativePackagePath(rootPath, mcpConfigPath),
+                serverName,
+                field: "server"
+            }));
             continue;
         }
         const command = serverConfig.command;
         const url = serverConfig.url;
         const env = serverConfig.env;
         if (typeof command !== "string" && typeof url !== "string") {
-            findings.push(buildFailure("plugin.mcp.server.transport.missing", `The MCP server \`${serverName}\` must define either \`command\` or \`url\`.`, "Codex needs a process command for STDIO servers or a URL for streamable HTTP servers.", `Add either \`command\` or \`url\` to the \`${serverName}\` entry in \`${mcpConfigPath}\`.`));
+            findings.push(buildFailure("plugin.mcp.server.transport.missing", `The MCP server \`${serverName}\` must define either \`command\` or \`url\`.`, "Codex needs a process command for STDIO servers or a URL for streamable HTTP servers.", `Add either \`command\` or \`url\` to the \`${serverName}\` entry in \`${mcpConfigPath}\`.`, {
+                configPath: relativePackagePath(rootPath, mcpConfigPath),
+                serverName,
+                field: "transport"
+            }));
         }
         if (isPlainObject(env)) {
             for (const [envKey, envValue] of Object.entries(env)) {

package/dist/mcp/generic-mcp-doctor.js

@@ -4,13 +4,14 @@ import { buildCompatibilityMatrix, readMcpConfigPath } from "../compatibility/co
 import { readJsonFile } from "../core/read-json-file.js";
 import { formatFindingFingerprintLine, withFindingFingerprints } from "../reporting/finding-fingerprint.js";
 import { auditMcpServerConfig, buildSecurityAuditFromFindings } from "../security/security-audit.js";
-function buildFinding(severity, id, message, impact, suggestedFix) {
+function buildFinding(severity, id, message, impact, suggestedFix, evidence) {
     return {
         id,
         severity,
         message,
         impact,
-        suggestedFix
+        suggestedFix,
+        ...(evidence ? { evidence } : {})
     };
 }
 function isPlainObject(value) {
@@ -30,12 +31,12 @@ function isPathWithinRoot(rootPath, candidatePath) {
     return (relativePath === "" ||
         (!relativePath.startsWith("..") && !path.isAbsolute(relativePath)));
 }
-function buildStaticMcpFindings(mcpConfigPath, parsedConfig) {
-    if (!mcpConfigPath) {
+function buildStaticMcpFindings(configPath, parsedConfig) {
+    if (!configPath) {
         return {
             serverCount: 0,
             findings: [
-                buildFinding("fail", "mcp.config.missing", "No MCP config was found for this target.", "A generic MCP package needs a `.mcp.json` file or a Codex manifest `mcpServers` reference before clients can discover servers.", "Add `.mcp.json` with a non-empty top-level `mcpServers` object.")
+                buildFinding("fail", "mcp.config.missing", "No MCP config was found for this target.", "A generic MCP package needs a `.mcp.json` file or a Codex manifest `mcpServers` reference before clients can discover servers.", "Add `.mcp.json` with a non-empty top-level `mcpServers` object.", { configPath: ".mcp.json", field: "mcpServers" })
             ]
         };
     }
@@ -43,7 +44,7 @@ function buildStaticMcpFindings(mcpConfigPath, parsedConfig) {
         return {
             serverCount: 0,
             findings: [
-                buildFinding("fail", "mcp.config.invalid_shape", "The MCP config must be a JSON object.", "MCP clients expect object-shaped configuration so server entries can be resolved deterministically.", `Wrap the MCP config in a top-level object inside \`${mcpConfigPath}\`.`)
+                buildFinding("fail", "mcp.config.invalid_shape", "The MCP config must be a JSON object.", "MCP clients expect object-shaped configuration so server entries can be resolved deterministically.", `Wrap the MCP config in a top-level object inside \`${configPath}\`.`, { configPath, field: "root" })
             ]
         };
     }
@@ -52,18 +53,18 @@ function buildStaticMcpFindings(mcpConfigPath, parsedConfig) {
         return {
             serverCount: 0,
             findings: [
-                buildFinding("fail", "mcp.config.invalid_shape", "The MCP config must contain a non-empty `mcpServers` object.", "Without server entries, MCP clients cannot discover any package capabilities.", `Define MCP servers under \`mcpServers\` in \`${mcpConfigPath}\`.`)
+                buildFinding("fail", "mcp.config.invalid_shape", "The MCP config must contain a non-empty `mcpServers` object.", "Without server entries, MCP clients cannot discover any package capabilities.", `Define MCP servers under \`mcpServers\` in \`${configPath}\`.`, { configPath, field: "mcpServers" })
             ]
         };
     }
     const findings = [];
     for (const [serverName, serverConfig] of Object.entries(servers)) {
         if (!isPlainObject(serverConfig)) {
-            findings.push(buildFinding("fail", "mcp.server.invalid", `The MCP server \`${serverName}\` must be configured as an object.`, "MCP clients cannot interpret a server entry unless it is represented as an object with server options.", `Change the \`${serverName}\` entry in \`${mcpConfigPath}\` to an object.`));
+            findings.push(buildFinding("fail", "mcp.server.invalid", `The MCP server \`${serverName}\` must be configured as an object.`, "MCP clients cannot interpret a server entry unless it is represented as an object with server options.", `Change the \`${serverName}\` entry in \`${configPath}\` to an object.`, { configPath, serverName, field: "server" }));
             continue;
         }
         if (typeof serverConfig.command !== "string" && typeof serverConfig.url !== "string") {
-            findings.push(buildFinding("fail", "mcp.server.transport.missing", `The MCP server \`${serverName}\` must define either \`command\` or \`url\`.`, "MCP clients need a process command for stdio servers or a URL for remote servers.", `Add either \`command\` or \`url\` to the \`${serverName}\` entry in \`${mcpConfigPath}\`.`));
+            findings.push(buildFinding("fail", "mcp.server.transport.missing", `The MCP server \`${serverName}\` must define either \`command\` or \`url\`.`, "MCP clients need a process command for stdio servers or a URL for remote servers.", `Add either \`command\` or \`url\` to the \`${serverName}\` entry in \`${configPath}\`.`, { configPath, serverName, field: "transport" }));
         }
     }
     return {
@@ -92,19 +93,26 @@ export async function buildGenericMcpDoctor(targetPath, environment = {}) {
     }
     else if (!isPathWithinRoot(rootPath, mcpConfigPath)) {
         staticFindings = [
-            buildFinding("fail", "mcp.config.path_outside_root", "The MCP config path resolves outside the target root.", "A package that reads MCP configuration outside its root is harder to audit and can depend on unreviewed local files.", "Keep `.mcp.json` or the manifest `mcpServers` reference inside the package root.")
+            buildFinding("fail", "mcp.config.path_outside_root", "The MCP config path resolves outside the target root.", "A package that reads MCP configuration outside its root is harder to audit and can depend on unreviewed local files.", "Keep `.mcp.json` or the manifest `mcpServers` reference inside the package root.", {
+                configPath: path.relative(rootPath, mcpConfigPath).replaceAll("\\", "/"),
+                resolvedPath: mcpConfigPath,
+                field: "configPath"
+            })
         ];
     }
     else {
         try {
             parsedConfig = await readJsonFile(mcpConfigPath);
-            const staticResult = buildStaticMcpFindings(mcpConfigPath, parsedConfig);
+            const staticResult = buildStaticMcpFindings(path.relative(rootPath, mcpConfigPath).replaceAll("\\", "/"), parsedConfig);
             staticFindings = staticResult.findings;
             serverCount = staticResult.serverCount;
         }
         catch {
             staticFindings = [
-                buildFinding("fail", "mcp.config.invalid_json", "The MCP config is not valid JSON.", "MCP clients cannot parse server configuration until the JSON syntax is valid.", `Fix the JSON syntax in \`${mcpConfigPath}\`.`)
+                buildFinding("fail", "mcp.config.invalid_json", "The MCP config is not valid JSON.", "MCP clients cannot parse server configuration until the JSON syntax is valid.", `Fix the JSON syntax in \`${mcpConfigPath}\`.`, {
+                    configPath: path.relative(rootPath, mcpConfigPath).replaceAll("\\", "/"),
+                    field: "json"
+                })
             ];
         }
     }

package/dist/security/security-audit.js

@@ -331,7 +331,7 @@ export async function buildSecurityAudit(targetPath) {
     const discoveredPackage = await discoverPackage(targetPath);
     if (!discoveredPackage) {
         const findings = [
-            buildFinding("fail", "plugin.security.audit_unavailable", "The target directory is missing `.codex-plugin/plugin.json`, so the package security audit cannot run.", "Without a Codex plugin manifest, the audit cannot resolve packaged skills or MCP server configuration safely.", "Run the audit against a Codex plugin package root.", { targetPath: path.resolve(targetPath) })
+            buildFinding("fail", "plugin.security.audit_unavailable", "The target directory is missing `.codex-plugin/plugin.json`, so the package security audit cannot run.", "Without a Codex plugin manifest, the audit cannot resolve packaged skills or MCP server configuration safely.", "Run the audit against a Codex plugin package root.", { manifestPath: ".codex-plugin/plugin.json" })
         ];
         return buildSecurityAuditFromFindings(targetPath, findings);
     }

package/dist/security/trust-score.js

@@ -11,13 +11,14 @@ const lifecycleScripts = new Set([
     "prepublish",
     "prepare"
 ]);
-function buildFinding(severity, id, message, impact, suggestedFix) {
+function buildFinding(severity, id, message, impact, suggestedFix, evidence) {
     return {
         id,
         severity,
         message,
         impact,
-        suggestedFix
+        suggestedFix,
+        ...(evidence ? { evidence } : {})
     };
 }
 async function fileExists(targetPath) {
@@ -61,10 +62,10 @@ function auditScripts(packageJson) {
         }
         scriptsChecked += 1;
         if (containsRemotePipeInstall(scriptValue)) {
-            findings.push(buildFinding("fail", "trust.package.remote_pipe_install", `The package lifecycle script \`${scriptName}\` pipes remote content into a shell.`, "Remote download-and-execute scripts can run unreviewed code during install or publish workflows.", "Replace remote pipe execution with pinned package dependencies or a checked-in reviewed setup script."));
+            findings.push(buildFinding("fail", "trust.package.remote_pipe_install", `The package lifecycle script \`${scriptName}\` pipes remote content into a shell.`, "Remote download-and-execute scripts can run unreviewed code during install or publish workflows.", "Replace remote pipe execution with pinned package dependencies or a checked-in reviewed setup script.", { packageJsonPath: "package.json", scriptName }));
             continue;
         }
-        findings.push(buildFinding("warn", "trust.package.lifecycle_script", `The package defines lifecycle script \`${scriptName}\`.`, "Lifecycle scripts execute automatically during package manager workflows and increase supply-chain review scope.", "Keep lifecycle scripts minimal, documented, and covered by release review."));
+        findings.push(buildFinding("warn", "trust.package.lifecycle_script", `The package defines lifecycle script \`${scriptName}\`.`, "Lifecycle scripts execute automatically during package manager workflows and increase supply-chain review scope.", "Keep lifecycle scripts minimal, documented, and covered by release review.", { packageJsonPath: "package.json", scriptName }));
     }
     return {
         findings,
@@ -73,26 +74,41 @@ function auditScripts(packageJson) {
 }
 function dependencySections(packageJson) {
     return [
-        packageJson.dependencies,
-        packageJson.devDependencies,
-        packageJson.optionalDependencies,
-        packageJson.peerDependencies
-    ].filter(isPlainObject);
+        { name: "dependencies", dependencies: packageJson.dependencies },
+        { name: "devDependencies", dependencies: packageJson.devDependencies },
+        { name: "optionalDependencies", dependencies: packageJson.optionalDependencies },
+        { name: "peerDependencies", dependencies: packageJson.peerDependencies }
+    ]
+        .filter((entry) => isPlainObject(entry.dependencies))
+        .map((entry) => ({
+        name: entry.name,
+        dependencies: entry.dependencies
+    }));
 }
 function auditDependencies(packageJson) {
     const findings = [];
     let dependenciesChecked = 0;
-    for (const dependencies of dependencySections(packageJson)) {
+    for (const { name: dependencySection, dependencies } of dependencySections(packageJson)) {
         for (const [dependencyName, versionSpec] of Object.entries(dependencies)) {
             if (typeof versionSpec !== "string") {
                 continue;
             }
             dependenciesChecked += 1;
             if (versionSpec === "*" || versionSpec.toLowerCase() === "latest") {
-                findings.push(buildFinding("warn", "trust.package.unpinned_dependency", `The dependency \`${dependencyName}\` uses broad version spec \`${versionSpec}\`.`, "Broad dependency ranges make package resolution less reproducible across installs and releases.", "Pin the dependency to a specific compatible range or exact version."));
+                findings.push(buildFinding("warn", "trust.package.unpinned_dependency", `The dependency \`${dependencyName}\` uses broad version spec \`${versionSpec}\`.`, "Broad dependency ranges make package resolution less reproducible across installs and releases.", "Pin the dependency to a specific compatible range or exact version.", {
+                    packageJsonPath: "package.json",
+                    dependencyName,
+                    dependencySection,
+                    versionSpec
+                }));
             }
             if (/^(git\+|github:|http:\/\/|https:\/\/)/i.test(versionSpec)) {
-                findings.push(buildFinding("warn", "trust.package.remote_dependency", `The dependency \`${dependencyName}\` resolves from remote spec \`${versionSpec}\`.`, "Remote dependency specs can change outside the npm registry's normal version and integrity workflow.", "Prefer registry-published dependencies with pinned semver ranges."));
+                findings.push(buildFinding("warn", "trust.package.remote_dependency", `The dependency \`${dependencyName}\` resolves from remote spec \`${versionSpec}\`.`, "Remote dependency specs can change outside the npm registry's normal version and integrity workflow.", "Prefer registry-published dependencies with pinned semver ranges.", {
+                    packageJsonPath: "package.json",
+                    dependencyName,
+                    dependencySection,
+                    versionSpec
+                }));
             }
         }
     }
@@ -104,7 +120,7 @@ function auditDependencies(packageJson) {
 function dedupeFindings(findings) {
     const seen = new Set();
     return findings.filter((finding) => {
-        const key = `${finding.id}\n${finding.message}`;
+        const key = `${finding.id}\n${JSON.stringify(finding.evidence ?? {})}`;
         if (seen.has(key)) {
             return false;
         }

package/package.json

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