agent-plugin-diagnostics

MCP Doctor

MCP Doctor is the repository for Agent Plugin Diagnostics, a Python-first toolkit for auditing MCP and AI coding-agent plugin setups across Claude Code, Codex, Cursor, VS Code, and Windsurf.

It helps answer a practical question: why is my agent plugin setup broken, risky, or non-portable, and what should I change?

What It Does

• Discovers MCP configuration across supported local clients.
• Normalizes server definitions into one report model.
• Detects missing commands, missing env vars, literal secrets, risky package invocations, plain HTTP URLs, broad filesystem roots, absolute project paths, and duplicate server names.
• Runs controlled MCP probes for initialize, initialized notification, ping, tools/list, advertised prompts/list, and advertised resources/list.
• Validates MCP probe responses against JSON-RPC 2.0 envelope rules and required MCP result shapes.
• Checks real installed agent apps and documented config paths with an opt-in local integration harness.
• Exports terminal, JSON, Markdown, and SARIF reports.
• Runs as an optional MCP server so agents can ask for diagnostics directly.

Install

Recommended isolated CLI install:

pipx install agent-plugin-diagnostics

Fast install with uv:

uv tool install agent-plugin-diagnostics

Run once without installing permanently:

uvx --from agent-plugin-diagnostics apd audit

Inside a virtual environment:

python -m pip install agent-plugin-diagnostics

For local development:

git clone https://github.com/fenil210/mcp-doctor.git
cd mcp-doctor
python -m venv .venv
.venv\Scripts\activate
python -m pip install -e ".[dev]"

On macOS and Linux, activate with source .venv/bin/activate.

Full install notes: docs/installation.md

Quick Start

Scan the current workspace:

apd scan

Run checks:

apd audit

Preview safe config fixes:

apd fix --dry-run

Apply applicable fixes with backup files:

apd fix --apply

Write a Markdown report:

apd export --format markdown --output apd-report.md

Probe a stdio server:

apd probe --server filesystem

Include remote Streamable HTTP or SSE servers:

apd probe --remote --timeout 10

Check installed agent apps and real config files:

apd integrations
apd integrations --format json
apd integrations --no-version

Explain a finding:

apd explain APD021

Generate a client snippet that installs MCP Doctor as an MCP server:

apd init --client codex
apd init --client cursor

Supported Clients

See docs/client-matrix.md for details.

Report Formats

Terminal output is designed for local debugging.

JSON output is designed for scripts and agent workflows.

Markdown output is designed for issues, pull requests, and setup documentation.

SARIF output is designed for GitHub code scanning and CI surfaces.

apd audit --format json
apd audit --format sarif --output apd.sarif

Real App Integration Harness

apd integrations checks the actual machine instead of assuming apps exist. It looks for documented config files, checks known CLI commands on PATH, optionally runs version commands with a timeout, and reuses the normal APD audit model for parsed config and server counts.

The harness is read-only. It does not launch GUI apps, edit configuration, install packages, or run configured MCP servers. Use apd probe separately when you want controlled MCP server startup checks.

MCP Server Mode

The standard installation includes MCP server mode.

Run:

apd serve-mcp

Available MCP tools:

• scan_agent_stack
• audit_agent_stack
• explain_finding
• generate_client_config
• list_supported_clients

Generate client config snippets with:

apd init --client claude-code
apd init --client claude-desktop
apd init --client cline
apd init --client codex
apd init --client cursor
apd init --client opencode
apd init --client roo-code
apd init --client vscode
apd init --client windsurf
apd init --client zed

Development

python -m ruff check .
python -m ruff format --check .
python -m mypy src/agent_plugin_diagnostics
python -m pytest

Project plan: features.md

Architecture: docs/architecture.md

Rules: docs/rule-index.md

Research notes: docs/research-notes.md

Installation: docs/installation.md

Release process: docs/releasing.md

Security Model

MCP Doctor is local-first and has no telemetry. Static checks do not make network calls. Probe mode starts configured stdio MCP servers only for controlled protocol checks. Remote HTTP and SSE probing requires apd probe --remote because it can make network requests. Protocol compliance checks are limited to the probe path APD actually exercises: initialize, initialized notification, ping, tools/list, and advertised prompt/resource listing.

Fix mode is dry-run by default. apd fix --apply only writes fixes that APD can express as exact file patches and creates .apd.bak backup files unless --no-backup is provided.

License

Apache-2.0.