codex-plugin-doctor 0.2.0 → 0.2.1

package/README.md

@@ -160,6 +160,8 @@ codex-plugin-doctor init my-plugin
 codex-plugin-doctor compat .
 codex-plugin-doctor compat . --client codex
 codex-plugin-doctor compat . --client generic-mcp
+codex-plugin-doctor compat . --client claude-desktop
+codex-plugin-doctor compat . --client claude-desktop --install-preview
 codex-plugin-doctor compat . --json
 codex-plugin-doctor compat . --json --output compatibility.json
 codex-plugin-doctor check .
@@ -174,6 +176,8 @@ codex-plugin-doctor check . --config .codex-doctor.json
 codex-plugin-doctor check . --json --runtime --verbose-runtime
 ```
 
+`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.
+
 Optional local policy file:
 
 ```json

package/dist/compatibility/claude-desktop-install-preview.d.ts

@@ -0,0 +1,10 @@
+import { type CompatibilityEnvironment } from "./compatibility-matrix.js";
+export interface ClaudeDesktopInstallPreview {
+    targetPath: string;
+    configPath: string;
+    snippet: {
+        mcpServers: Record<string, unknown>;
+    };
+}
+export declare function buildClaudeDesktopInstallPreview(targetPath: string, environment?: CompatibilityEnvironment): Promise<ClaudeDesktopInstallPreview>;
+export declare function renderClaudeDesktopInstallPreview(preview: ClaudeDesktopInstallPreview): string;

package/dist/compatibility/claude-desktop-install-preview.js

@@ -0,0 +1,69 @@
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { getClaudeDesktopConfigPath, readMcpConfigPath } from "./compatibility-matrix.js";
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isRelativeLocalPath(value) {
+    return value.startsWith("./") ||
+        value.startsWith("../") ||
+        value.startsWith(".\\") ||
+        value.startsWith("..\\");
+}
+function normalizeLocalPathArgument(value, rootPath) {
+    return typeof value === "string" && isRelativeLocalPath(value)
+        ? path.resolve(rootPath, value)
+        : value;
+}
+function normalizeServerConfig(serverConfig, rootPath) {
+    if (!isRecord(serverConfig)) {
+        return serverConfig;
+    }
+    const normalized = { ...serverConfig };
+    if (typeof normalized.command === "string" && isRelativeLocalPath(normalized.command)) {
+        normalized.command = path.resolve(rootPath, normalized.command);
+    }
+    if (Array.isArray(normalized.args)) {
+        normalized.args = normalized.args.map((argument) => normalizeLocalPathArgument(argument, rootPath));
+    }
+    return normalized;
+}
+export async function buildClaudeDesktopInstallPreview(targetPath, environment = {}) {
+    const rootPath = path.resolve(targetPath);
+    const configPath = getClaudeDesktopConfigPath(environment);
+    if (!configPath) {
+        throw new Error("Claude Desktop config path could not be resolved on this platform.");
+    }
+    const mcpConfigPath = await readMcpConfigPath(rootPath);
+    if (!mcpConfigPath) {
+        throw new Error("No MCP config found for install preview.");
+    }
+    const parsed = JSON.parse(await readFile(mcpConfigPath, "utf8"));
+    const servers = parsed.mcpServers;
+    if (!isRecord(servers) || Object.keys(servers).length === 0) {
+        throw new Error("MCP config does not contain a non-empty `mcpServers` object.");
+    }
+    return {
+        targetPath: rootPath,
+        configPath,
+        snippet: {
+            mcpServers: Object.fromEntries(Object.entries(servers).map(([serverName, serverConfig]) => [
+                serverName,
+                normalizeServerConfig(serverConfig, rootPath)
+            ]))
+        }
+    };
+}
+export function renderClaudeDesktopInstallPreview(preview) {
+    return [
+        "Claude Desktop Install Preview",
+        "==============================",
+        `Target: ${preview.targetPath}`,
+        `Config: ${preview.configPath}`,
+        "",
+        "Add or merge this snippet into `claude_desktop_config.json`:",
+        JSON.stringify(preview.snippet, null, 2),
+        "",
+        "No files were modified."
+    ].join("\n");
+}

package/dist/compatibility/compatibility-matrix.d.ts

@@ -9,5 +9,12 @@ export interface CompatibilityMatrix {
     targetPath: string;
     results: CompatibilityResult[];
 }
-export declare function buildCompatibilityMatrix(targetPath: string): Promise<CompatibilityMatrix>;
+export interface CompatibilityEnvironment {
+    env?: Record<string, string | undefined>;
+    platform?: NodeJS.Platform;
+    homedir?: string;
+}
+export declare function readMcpConfigPath(targetPath: string): Promise<string | null>;
+export declare function getClaudeDesktopConfigPath(environment?: CompatibilityEnvironment): string | null;
+export declare function buildCompatibilityMatrix(targetPath: string, environment?: CompatibilityEnvironment): Promise<CompatibilityMatrix>;
 export declare function matrixExitCode(matrix: CompatibilityMatrix): 0 | 1;

package/dist/compatibility/compatibility-matrix.js

@@ -1,4 +1,5 @@
 import { readFile, stat } from "node:fs/promises";
+import os from "node:os";
 import path from "node:path";
 import { validatePlugin } from "../core/validate-plugin.js";
 async function fileExists(targetPath) {
@@ -10,6 +11,15 @@ async function fileExists(targetPath) {
         return false;
     }
 }
+async function directoryExists(targetPath) {
+    try {
+        const details = await stat(targetPath);
+        return details.isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
 function statusFromCheckResult(result) {
     if (result.status === "fail") {
         return "fail";
@@ -19,7 +29,7 @@ function statusFromCheckResult(result) {
     }
     return "pass";
 }
-async function readMcpConfigPath(targetPath) {
+export async function readMcpConfigPath(targetPath) {
     const rootPath = path.resolve(targetPath);
     const directMcpPath = path.join(rootPath, ".mcp.json");
     if (await fileExists(directMcpPath)) {
@@ -82,9 +92,119 @@ async function checkGenericMcp(targetPath) {
         };
     }
 }
-export async function buildCompatibilityMatrix(targetPath) {
+async function readMcpServerNames(targetPath) {
+    const mcpConfigPath = await readMcpConfigPath(targetPath);
+    if (!mcpConfigPath || !(await fileExists(mcpConfigPath))) {
+        return [];
+    }
+    try {
+        const parsed = JSON.parse(await readFile(mcpConfigPath, "utf8"));
+        const servers = parsed.mcpServers;
+        return typeof servers === "object" && servers !== null && !Array.isArray(servers)
+            ? Object.keys(servers)
+            : [];
+    }
+    catch {
+        return [];
+    }
+}
+export function getClaudeDesktopConfigPath(environment = {}) {
+    const platform = environment.platform ?? process.platform;
+    const env = environment.env ?? process.env;
+    const homeDirectory = environment.homedir ?? os.homedir();
+    if (platform === "win32") {
+        const appData = env.APPDATA;
+        return appData ? path.join(appData, "Claude", "claude_desktop_config.json") : null;
+    }
+    if (platform === "darwin") {
+        return path.join(homeDirectory, "Library", "Application Support", "Claude", "claude_desktop_config.json");
+    }
+    return null;
+}
+async function checkClaudeDesktop(targetPath, genericMcpResult, environment = {}) {
+    if (genericMcpResult.status !== "pass") {
+        return {
+            client: "Claude Desktop",
+            status: "skipped",
+            summary: "No valid MCP package config is available for Claude Desktop.",
+            details: ["Add a valid `.mcp.json` with a non-empty `mcpServers` object first."]
+        };
+    }
+    const configPath = getClaudeDesktopConfigPath(environment);
+    if (!configPath) {
+        return {
+            client: "Claude Desktop",
+            status: "warn",
+            summary: "Claude Desktop config path could not be resolved on this platform.",
+            details: ["Claude Desktop local config detection currently supports Windows and macOS."]
+        };
+    }
+    if (!(await fileExists(configPath))) {
+        const configDirectory = path.dirname(configPath);
+        return {
+            client: "Claude Desktop",
+            status: await directoryExists(configDirectory) ? "pass" : "warn",
+            summary: await directoryExists(configDirectory)
+                ? "Claude Desktop directory exists and a config file can be created."
+                : "Claude Desktop was not detected on this machine.",
+            details: [
+                configPath,
+                "Claude Desktop can add stdio MCP servers through `claude_desktop_config.json` when the app is installed."
+            ]
+        };
+    }
+    try {
+        const parsed = JSON.parse(await readFile(configPath, "utf8"));
+        const servers = parsed.mcpServers;
+        if (servers !== undefined && (typeof servers !== "object" ||
+            servers === null ||
+            Array.isArray(servers))) {
+            return {
+                client: "Claude Desktop",
+                status: "fail",
+                summary: "Claude Desktop config has an invalid `mcpServers` shape.",
+                details: [configPath, "`mcpServers` must be an object before this package can be added safely."]
+            };
+        }
+        const packageServerNames = await readMcpServerNames(targetPath);
+        const existingServerNames = typeof servers === "object" && servers !== null
+            ? Object.keys(servers)
+            : [];
+        const duplicateServerNames = packageServerNames.filter((serverName) => existingServerNames.includes(serverName));
+        if (duplicateServerNames.length > 0) {
+            return {
+                client: "Claude Desktop",
+                status: "warn",
+                summary: "Claude Desktop already has MCP server names from this package.",
+                details: [
+                    configPath,
+                    ...duplicateServerNames.map((serverName) => `Duplicate server: ${serverName}`)
+                ]
+            };
+        }
+        return {
+            client: "Claude Desktop",
+            status: "pass",
+            summary: "Claude Desktop config is valid and this MCP package can be added.",
+            details: [
+                configPath,
+                `Source package: ${path.resolve(targetPath)}`
+            ]
+        };
+    }
+    catch {
+        return {
+            client: "Claude Desktop",
+            status: "fail",
+            summary: "Claude Desktop config is not valid JSON.",
+            details: [configPath, "Repair the local Claude Desktop config before adding new MCP servers."]
+        };
+    }
+}
+export async function buildCompatibilityMatrix(targetPath, environment = {}) {
     const rootPath = path.resolve(targetPath);
     const genericMcpResult = await checkGenericMcp(rootPath);
+    const claudeDesktopResult = await checkClaudeDesktop(rootPath, genericMcpResult, environment);
     const codexResult = await validatePlugin(rootPath);
     const codexStatus = statusFromCheckResult(codexResult);
     const codexCompatibility = !await hasCodexManifest(rootPath)
@@ -106,12 +226,7 @@ export async function buildCompatibilityMatrix(targetPath) {
     const results = [
         codexCompatibility,
         genericMcpResult,
-        {
-            client: "Claude Desktop",
-            status: "skipped",
-            summary: "Client-specific package adapter is not implemented yet.",
-            details: ["Planned adapter after generic MCP compatibility is stable."]
-        },
+        claudeDesktopResult,
         {
             client: "Cursor",
             status: "skipped",

package/dist/run-cli.js

@@ -1,6 +1,7 @@
 import { writeFile } from "node:fs/promises";
 import { discoverInstalledPlugins, filterInstalledPlugins } from "./core/discover-installed-plugins.js";
 import { buildCompatibilityMatrix, matrixExitCode } from "./compatibility/compatibility-matrix.js";
+import { buildClaudeDesktopInstallPreview, renderClaudeDesktopInstallPreview } from "./compatibility/claude-desktop-install-preview.js";
 import { applyDoctorConfig, loadDoctorConfig } from "./core/doctor-config.js";
 import { initPluginPackage } from "./core/init-plugin.js";
 import { runCheck } from "./index.js";
@@ -25,7 +26,7 @@ const defaultIo = {
     }
 };
 function printUsage(io) {
-    io.writeStderr("Usage: codex-plugin-doctor check <path|--installed> [filter] [--json|--markdown] [--output <path>] [--runtime] [--verbose-runtime] [--no-animations] [--ascii]\n       codex-plugin-doctor compat <path> [--json] [--output <path>]\n       codex-plugin-doctor list --installed\n       codex-plugin-doctor explain <finding-id>\n       codex-plugin-doctor --version");
+    io.writeStderr("Usage: codex-plugin-doctor check <path|--installed> [filter] [--json|--markdown] [--output <path>] [--runtime] [--verbose-runtime] [--no-animations] [--ascii]\n       codex-plugin-doctor compat <path> [--client <client>] [--json] [--output <path>] [--install-preview]\n       codex-plugin-doctor list --installed\n       codex-plugin-doctor explain <finding-id>\n       codex-plugin-doctor --version");
 }
 function renderInstalledPlugins(plugins) {
     const lines = [
@@ -113,6 +114,7 @@ export async function runCli(args, io = defaultIo, options = {}) {
             ? [maybePath, ...remainingArgs]
             : remainingArgs;
         const jsonOutput = compatFlags.includes("--json");
+        const installPreview = compatFlags.includes("--install-preview");
         const clientIndex = compatFlags.indexOf("--client");
         const clientFilter = clientIndex === -1 ? null : compatFlags[clientIndex + 1];
         const outputIndex = compatFlags.indexOf("--output");
@@ -125,7 +127,31 @@ export async function runCli(args, io = defaultIo, options = {}) {
             io.writeStderr("Missing path after --output.");
             return 2;
         }
-        let matrix = await buildCompatibilityMatrix(targetPath);
+        if (installPreview && clientFilter?.toLowerCase() !== "claude-desktop") {
+            io.writeStderr("--install-preview requires --client claude-desktop.");
+            return 2;
+        }
+        if (installPreview) {
+            try {
+                const preview = await buildClaudeDesktopInstallPreview(targetPath, {
+                    env: terminalContext.env
+                });
+                const report = renderClaudeDesktopInstallPreview(preview);
+                if (outputPath) {
+                    await writeFile(outputPath, report, "utf8");
+                }
+                io.writeStdout(report);
+                return 0;
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : "Unknown install preview error.";
+                io.writeStderr(message);
+                return 1;
+            }
+        }
+        let matrix = await buildCompatibilityMatrix(targetPath, {
+            env: terminalContext.env
+        });
         if (clientFilter) {
             const filteredMatrix = filterCompatibilityMatrix(matrix, clientFilter);
             if (!filteredMatrix) {

package/package.json

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