# CodexPluginDoctor > Local CLI validator for Codex plugin packages, skills, and MCP server bundles. - **Type:** MCP server - **Install:** `agentstack add mcp-esquetta-codexplugindoctor` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [Esquetta](https://agentstack.voostack.com/s/esquetta) - **Installs:** 0 - **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [Esquetta](https://github.com/Esquetta) - **Source:** https://github.com/Esquetta/CodexPluginDoctor ## Install ```sh agentstack add mcp-esquetta-codexplugindoctor ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # Codex Plugin Doctor [](https://github.com/Esquetta/CodexPluginDoctor/actions/workflows/ci.yml) [](https://www.npmjs.com/package/codex-plugin-doctor) [](./LICENSE) [](https://github.com/Esquetta/CodexPluginDoctor/releases) Codex Plugin Doctor is a local CLI validator for Codex plugin packages, skills, and MCP server bundles. It catches packaging, metadata, security, and runtime protocol problems before a plugin reaches users, teammates, or release workflows. ## Status Codex Plugin Doctor is a public stable CLI for local and CI validation. - Primary surface: GitHub repository and npm package - Distribution today: `npm install -g`, local source install, `npm link`, `npm pack`, GitHub Releases - Public npm package: `codex-plugin-doctor` - License: [MIT](./LICENSE) ## 1.0 Stability The 1.0 line is the stable compatibility baseline for plugin authors and CI consumers. - Public JSON schema surfaces and existing rule IDs/default severities are treated as stable through 1.0. - Runtime probing remains opt-in because it executes package-local MCP servers. - The project remains Codex-first; broader MCP Doctor positioning stays a post-1.0 expansion path. - Post-1.0 feature work should stay additive unless a documented major-version decision is made. See the [documentation index](./docs/README.md) for architecture, usage, security, and contributor guides. ## Why This Exists Codex plugin packages can fail in several places: - the package manifest is missing or points outside the package root - skills exist but do not expose valid `SKILL.md` metadata - `.mcp.json` is malformed or references unsafe secrets - an MCP server starts but does not complete the protocol handshake - tools, resources, or prompts list successfully but fail deeper runtime checks - verbose metadata creates noisy matching and unnecessary context cost This tool gives plugin authors a repeatable preflight check before distribution. ## What It Checks Static validation: - required `.codex-plugin/plugin.json` - manifest fields: `name`, `version`, `description` - skill directory wiring - `SKILL.md` presence and frontmatter fields - YAML single-line and block-scalar skill descriptions - `.mcp.json` structure - path traversal risks - hard-coded secret-like env values - description quality heuristics tuned against real plugin packages Security scorecard with `security`: - shell wrapper command warnings for MCP servers - encoded shell command failures - remote content piped into shell failures - MCP server `cwd` paths that escape the package root - plain HTTP remote transport warnings Runtime MCP validation with `--runtime`: - `initialize` - `notifications/initialized` - `tools/list` - `tools/call` - `resources/list` - `resources/read` - `resources/templates/list` - `prompts/list` - `prompts/get` - paginated list responses - runtime capability scorecard - redacted verbose transcript with `--verbose-runtime` - optional runtime approval gating with a precomputed `doctor runtime-plan` digest Output formats: - human text output - JSON reports - Markdown reports - Shields-compatible badge JSON and static badge Markdown - validation history JSONL and trend summaries - deterministic local attestation artifacts - output contract and rule catalog freeze metadata - bundled validation corpus reports - `--output` file writing - CI summary and artifact generation ## Quick Start Global install from npm: ```bash npm install -g codex-plugin-doctor codex-plugin-doctor --version codex-plugin-doctor self-test codex-plugin-doctor check path/to/plugin-package ``` Run `codex-plugin-doctor check .` from the root of a Codex plugin package that contains `.codex-plugin/plugin.json`. The Codex Plugin Doctor source repository is not itself a plugin package. If you already have Codex installed locally and do not know plugin paths, discover the installed plugin cache: ```bash codex-plugin-doctor list --installed codex-plugin-doctor check --installed codex-plugin-doctor check --installed --all-summary codex-plugin-doctor check --installed --compat --all-summary codex-plugin-doctor audit --installed --security --compat codex-plugin-doctor audit --installed --security --compat --policy security codex-plugin-doctor mcp path/to/mcp-package codex-plugin-doctor check --installed github codex-plugin-doctor explain plugin.manifest.missing ``` Run from source: ```bash npm install npm run build node dist/cli.js check examples/codex-doctor-runtime --runtime ``` For local global usage: ```bash npm link codex-plugin-doctor check examples/codex-doctor-runtime --runtime ``` Generate validation artifacts locally: ```bash npm run generate-validation-artifacts -- --target examples/codex-doctor-runtime --runtime-target examples/codex-doctor-runtime --out-dir validation-artifacts-local ``` ## Example Output Passing runtime package: ```text Codex Plugin Doctor =================== Status: PASS Target: \examples\codex-doctor-runtime Summary: 0 fail, 0 warn, 0 total Runtime Scorecard ---------------- initialize: pass tools/list: pass tools/call: pass resources/list: pass resources/read: pass resources/templates/list: pass prompts/list: pass prompts/get: pass No findings. ``` Risky package: ```text Codex Plugin Doctor =================== Status: FAIL Target: \examples\codex-doctor-risky Summary: 1 fail, 0 warn, 1 total Failures -------- x plugin.security.hard_coded_secret Message: The MCP server `dangerServer` contains a hard-coded secret-like env value for `OPENAI_API_KEY`. Impact: Hard-coded credentials inside plugin bundles increase leakage risk and make secure rotation difficult. Suggested fix: Replace the literal value for `OPENAI_API_KEY` with an environment reference or injected secret outside the package. ``` ## Useful Commands Run these from a Codex plugin package root: ```bash codex-plugin-doctor --version codex-plugin-doctor self-test codex-plugin-doctor doctor codex-plugin-doctor doctor contract codex-plugin-doctor doctor contract --json --output output-contract.json codex-plugin-doctor doctor corpus codex-plugin-doctor doctor corpus --json --output validation-corpus.json codex-plugin-doctor doctor npm codex-plugin-doctor doctor npm --json --output npm-preinstall.json codex-plugin-doctor doctor attest . codex-plugin-doctor doctor attest . --json --output attestation.json codex-plugin-doctor doctor attest . --json --sign-key-env CODEX_PLUGIN_DOCTOR_SIGNING_KEY --output attestation.json codex-plugin-doctor doctor attest verify attestation.json --target . --sign-key-env CODEX_PLUGIN_DOCTOR_SIGNING_KEY codex-plugin-doctor doctor attest verify attestation.json --target . --json --sign-key-env CODEX_PLUGIN_DOCTOR_SIGNING_KEY codex-plugin-doctor doctor inspector . codex-plugin-doctor doctor inspector . --server context7 --json --output inspector-command.json codex-plugin-doctor doctor diff --before ./old-plugin --after ./new-plugin codex-plugin-doctor doctor diff --before ./old-plugin --after ./new-plugin --json --output risk-diff.json codex-plugin-doctor doctor recommend . codex-plugin-doctor doctor recommend . --json --output recommendations.json codex-plugin-doctor doctor trust . codex-plugin-doctor doctor trust . --json --output trust-score.json codex-plugin-doctor doctor perf . codex-plugin-doctor doctor perf . --json --output perf.json codex-plugin-doctor doctor perf . --max-total-ms 2500 --max-stage-ms validation=500 codex-plugin-doctor doctor runtime-plan . codex-plugin-doctor doctor runtime-plan . --json --output runtime-plan.json codex-plugin-doctor doctor runtime-plan . --markdown --output runtime-plan.md codex-plugin-doctor doctor runtime-policy . codex-plugin-doctor doctor runtime-policy . --json --output runtime-policy.json codex-plugin-doctor doctor review-bundle . --output review-bundle --sign-key-env CODEX_PLUGIN_DOCTOR_SIGNING_KEY codex-plugin-doctor doctor review-bundle verify review-bundle --target . --sign-key-env CODEX_PLUGIN_DOCTOR_SIGNING_KEY codex-plugin-doctor doctor review-bundle diff --before old-review-bundle --after review-bundle codex-plugin-doctor doctor mcp . codex-plugin-doctor doctor mcp . --json --output mcp-healthcheck.json codex-plugin-doctor doctor export --bundle . codex-plugin-doctor doctor export --bundle . --output doctor-bundle.json codex-plugin-doctor doctor snapshot codex-plugin-doctor doctor snapshot --json codex-plugin-doctor doctor snapshot --output doctor-snapshot.json codex-plugin-doctor doctor clients codex-plugin-doctor doctor --update-check codex-plugin-doctor audit --installed codex-plugin-doctor audit --installed --security --compat codex-plugin-doctor audit --installed --security --compat --json --output local-audit.json codex-plugin-doctor audit --installed --security --compat --cache codex-plugin-doctor audit --installed --changed --cache codex-plugin-doctor audit deps . codex-plugin-doctor audit deps . --json --output dependency-audit.json codex-plugin-doctor audit deps . --recommend codex-plugin-doctor audit deps . --recommend --json --output dependency-remediation.json codex-plugin-doctor watch . codex-plugin-doctor watch . --json --output watch-latest.json --debounce-ms 500 codex-plugin-doctor init-git-hooks . codex-plugin-doctor init-git-hooks . --json codex-plugin-doctor mcp . codex-plugin-doctor mcp . --json codex-plugin-doctor mcp . --json --output mcp-doctor.json codex-plugin-doctor init my-plugin codex-plugin-doctor init my-mcp --template mcp-stdio codex-plugin-doctor init remote-mcp --template mcp-http codex-plugin-doctor init runtime-demo --template full-runtime codex-plugin-doctor security . codex-plugin-doctor security . --scorecard codex-plugin-doctor security . --json codex-plugin-doctor security . --policy security codex-plugin-doctor compat . codex-plugin-doctor compat . --all --scorecard 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 . --client claude-desktop --apply --backup codex-plugin-doctor compat . --client cursor codex-plugin-doctor compat . --client cursor --install-preview codex-plugin-doctor compat . --client cursor --apply --backup codex-plugin-doctor compat . --client cline codex-plugin-doctor compat . --client cline --install-preview codex-plugin-doctor compat . --scorecard codex-plugin-doctor compat . --json codex-plugin-doctor compat . --json --output compatibility.json codex-plugin-doctor check . codex-plugin-doctor check . --profile ci codex-plugin-doctor check . --profile strict codex-plugin-doctor check . --profile publish codex-plugin-doctor check . --policy codex-publish codex-plugin-doctor check . --policy mcp-strict codex-plugin-doctor check . --policy security codex-plugin-doctor check . --json codex-plugin-doctor check . --explain codex-plugin-doctor check . --json --output report.json codex-plugin-doctor check . --markdown --output report.md codex-plugin-doctor check . --badge-json --output doctor-badge.json codex-plugin-doctor check . --badge-markdown codex-plugin-doctor check . --sarif --output results.sarif codex-plugin-doctor check . --ascii codex-plugin-doctor check . --no-animations codex-plugin-doctor check . --runtime codex-plugin-doctor check . --runtime --require-runtime-approval --runtime-approval-digest sha256: codex-plugin-doctor check . --config .codex-doctor.json codex-plugin-doctor check . --history validation-history.jsonl codex-plugin-doctor history validation-history.jsonl codex-plugin-doctor history validation-history.jsonl --json codex-plugin-doctor history validation-history.jsonl --fail-on-regression codex-plugin-doctor fix . --dry-run codex-plugin-doctor fix . --interactive --backup codex-plugin-doctor fix . --apply --backup codex-plugin-doctor check . --json --runtime --verbose-runtime ``` `self-test` runs the bundled runtime-complete sample through static validation, runtime MCP probes, and the compatibility scorecard. It is the fastest post-install check after `npm install -g codex-plugin-doctor`. `doctor` checks the local environment, including package version, platform, Node version, npm global prefix, Codex home, and Codex plugin cache visibility. The text output also includes recommended next commands for self-test, installed plugin discovery, runtime checks, compatibility scoring, and CI setup. `doctor contract` publishes the machine-readable output contract, including public JSON schema surfaces, stable-through-1.0 compatibility metadata, and a frozen rule catalog digest. Add `--json` for automation or `--output output-contract.json` to write the contract to disk. `doctor corpus` runs the bundled validation corpus against healthy runtime, risky security, starter skill, and generic MCP packages, then reports whether each case matched its expected outcome. Add `--json` for automation or `--output validation-corpus.json` to write the corpus report to disk. `doctor npm ` runs a preinstall scan by packing the npm package with scripts disabled, extracting the publish tarball, and running validation, security, trust, and recommendation checks against the shipped contents. The JSON report includes tarball metadata such as filename, path, integrity, shasum, sizes, file count, and extracted package root so automation can prove which archive was scanned. Use a published Codex plugin package as the target; scanning `codex-plugin-doctor` itself intentionally reports a missing plugin manifest because this CLI package is not a plugin package. Add `--json` for automation or `--output npm-preinstall.json` to write the report to disk. `doctor attest ` creates a local attestation with stable package/report digests, validation/security/compatibility/trust summary, and verification metadata. Add `--sign-key-env NAME` to attach a local HMAC-SHA256 signature without printing the secret, or `--json --output attestation.json` to write the artifact to disk. `doctor attest verify --target --sign-key-env NAME` recomputes the package fingerprint, report digest, and HMAC signature offline; verification intentionally treats `generatedAt`, `targetPath`, `verification`, and `signature.keyHint` as unsigned display metadata. `doctor runtime-plan ` creates a non-executing runtime plan that lists MCP server commands, safe probe methods, risk reasons, and a stable approval digest before any local server is started. Add `--markdown --output runtime-plan.md` to preserve a review-ready approval artifact with the execution boundary, checklist, servers, probes, and risk reasons. `doctor runtime-policy ` evaluates the same runtime plan and security signals, then recommends `allow`, `review`, `sandbox_recommended`, or `deny` before local MCP execution starts. `doctor review-bundle --output --sign-key-env NAME` writes a signed review directory with runtime plan, runtime policy, attestation, release evidence, manifest, Markdown summary files, and SHA-256 file integrity digests. `doctor review-bundle verify --target --sign-key-env NAME` verifies the bundle manifest, expected files, manifest integrity digests, runtime artifacts, signed attestation, and signed release evidence offline before a reviewer trusts the handoff. `doctor review-bundle diff --before --after ` compares two review bundles and flags risk-increasing changes in status, runtime policy, release readiness, signatures, release evidence, and runtime plan digest. `check --runtime --require-runtime-approval --runtime-approval-digest ` refuses to run runtime probes unless the current plan digest matches the approved digest. `doctor release-evidence --sign-key-env NAME` creates one redacted release bundle with signed attestation, offline verification, corpus, performance, security, trust, package metadata, git release gates, and runtime approval status. Strict release evidence requires a clean tagged worktree; use `--allow-dirty` or `--allow-untagged` only for local rehearsal. `doctor release … ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [Esquetta](https://github.com/Esquetta) - **Source:** [Esquetta/CodexPluginDoctor](https://github.com/Esquetta/CodexPluginDoctor) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-esquetta-codexplugindoctor - Seller: https://agentstack.voostack.com/s/esquetta - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.