{
  "markdown": "<!-- mcp-name: io.github.Jiansen/mcp-doctor -->\n\n<p align=\"center\">\n  <img src=\"assets/avatar-512.png\" width=\"120\" alt=\"mcp-doctor logo\">\n</p>\n\n<h1 align=\"center\">MCP Doctor</h1>\n\n<p align=\"center\">\n  <a href=\"https://pypi.org/project/mcp-doctor/\"><img src=\"https://img.shields.io/pypi/v/mcp-doctor\" alt=\"PyPI\"></a>\n  <a href=\"https://github.com/Jiansen/mcp-doctor/blob/main/LICENSE\"><img src=\"https://img.shields.io/badge/license-MIT-blue\" alt=\"License\"></a>\n  <a href=\"https://pypi.org/project/mcp-doctor/\"><img src=\"https://img.shields.io/pypi/pyversions/mcp-doctor\" alt=\"Python\"></a>\n  <a href=\"https://github.com/Jiansen/mcp-doctor/stargazers\"><img src=\"https://img.shields.io/github/stars/Jiansen/mcp-doctor?style=social\" alt=\"GitHub Stars\"></a>\n</p>\n\n<p align=\"center\">Check and improve the contract quality of any MCP server — for humans, agents, and platforms.</p>\n\n## Problem\n\nMost MCP servers are built with only one audience in mind (usually human developers reading a README). But a successful MCP server needs to satisfy three audiences simultaneously:\n\n- **Distribution platforms** (Registry, Smithery, PulseMCP, Glama) need structured metadata\n- **Human users** need clear purpose, trust signals, and low install friction\n- **AI agents** need unambiguous tool descriptions, declared side effects, and token-efficient responses\n\nMCP Doctor checks all six dimensions of \"contract quality\" and gives you actionable recommendations.\n\n## Quick Start\n\n```bash\npip install mcp-doctor\nmcp-doctor check /path/to/your-mcp-server\n```\n\n## What It Checks\n\n| Dimension | Question |\n|-----------|----------|\n| **Task Clarity** | Is the server's purpose immediately clear? |\n| **Trust & Safety** | Are side effects, permissions, and safety boundaries declared? |\n| **Interface Quality** | Are tools well-named, well-described, and well-typed? |\n| **Token Efficiency** | Will tool responses fit an agent's context budget? |\n| **Install Friction** | How fast can someone go from discovery to first use? |\n| **Cross-platform Readiness** | Is metadata complete for Registry, Smithery, PulseMCP, Glama? |\n\n## Usage\n\n### CLI\n\n```bash\n# Terminal output (default, rule-based)\nmcp-doctor check /path/to/server\n\n# JSON output (for CI/CD)\nmcp-doctor check /path/to/server --format json\n\n# Markdown output (for README badges or reports)\nmcp-doctor check /path/to/server --format markdown\n\n# AI-enhanced evaluation (requires OPENAI_API_KEY)\nmcp-doctor check /path/to/server --mode ai\n\n# AI mode with a specific model\nmcp-doctor check /path/to/server --mode ai --model gpt-4o\n```\n\n### As an MCP Server\n\nMCP Doctor is also an MCP server, so AI agents can use it to check other servers:\n\n```json\n{\n  \"mcpServers\": {\n    \"mcp-doctor\": {\n      \"command\": \"python\",\n      \"args\": [\"-m\", \"mcp_doctor.mcp_server\"]\n    }\n  }\n}\n```\n\nTools:\n- `check_server(path, format, mode, model)` — Run all 6 checks. Use `mode=\"ai\"` for LLM-enhanced review.\n- `list_dimensions()` — List what MCP Doctor evaluates\n\n### For AI Agents: Quick Install\n\n**One-liner** (paste this to your AI agent):\n\n> Install mcp-doctor (`pip install mcp-doctor`) and add it to your MCP config with command `python -m mcp_doctor.mcp_server`. Then use the `check_server` tool to check any MCP server's quality.\n\n**Step by step:**\n\n1. Install: `pip install mcp-doctor`\n2. Add to your MCP configuration:\n   ```json\n   {\n     \"mcpServers\": {\n       \"mcp-doctor\": {\n         \"command\": \"python\",\n         \"args\": [\"-m\", \"mcp_doctor.mcp_server\"]\n       }\n     }\n   }\n   ```\n3. Use the `check_server` tool with a path to any MCP server repo\n4. If MCP is not available, fall back to CLI: `mcp-doctor check /path/to/server --format json`\n\n**Agent workflow:** check server -> review scores -> identify lowest dimensions -> follow recommendations\n\n## Scoring\n\nEach dimension is scored 0-100 and graded A/B/C/D:\n\n- **A** (90+): Exemplary\n- **B** (75-89): Good, minor gaps\n- **C** (55-74): Adequate, notable gaps\n- **D** (<55): Needs significant improvement\n\n## Theoretical Foundation\n\nMCP Doctor is based on the **Contract Quality Framework** — the principle that a successful MCP product's promises (what it does, what it costs, what risks it carries) should be equally parseable by platforms, humans, and agents.\n\nThe framework draws from:\n- Anthropic's \"Writing effective tools for agents\" (tool description engineering, namespacing, token efficiency)\n- Official MCP Registry requirements (server.json schema, namespace verification)\n- Cross-platform analysis of Smithery, PulseMCP, Glama ranking signals\n\n## Evaluation Modes\n\n| Mode | Flag | Deterministic | Network | API Key |\n|------|------|:---:|:---:|:---:|\n| **Rule-based** (default) | `--mode rule` | Yes | No | No |\n| **AI-enhanced** | `--mode ai` | No | Yes (LLM API) | `OPENAI_API_KEY` |\n\n**Rule-based mode** is fully offline and deterministic. No network calls, no LLM, no API keys needed.\n\n**AI mode** sends a metadata summary (server name, tool definitions, README preview, rule-based scores) to an OpenAI-compatible API for qualitative review. No source code is sent. Reports include model name and version for reproducibility.\n\nAI mode supports any OpenAI-compatible provider:\n- `OPENAI_API_KEY` — API key (required for AI mode)\n- `OPENAI_BASE_URL` — Custom endpoint (for Ollama, vLLM, LM Studio, Azure, etc.)\n- `MCP_DOCTOR_MODEL` — Model name (default: `gpt-4o-mini`)\n\nInstall AI support: `pip install mcp-doctor[ai]`\n\n## Trust & Permissions\n\nMCP Doctor is **read-only**. It never modifies, deletes, or creates files.\n\n| What it accesses | Why |\n|-----------------|-----|\n| `server.json` | Parse MCP metadata |\n| `README.md` | Check documentation quality |\n| `LICENSE` | Verify license presence |\n| `*.py`, `*.json` in `src/` | Detect tool definitions |\n\nAll MCP tools have `readOnlyHint: true` and `destructiveHint: false` annotations.\n\n## Feedback\n\nFound a bug? Have a suggestion? We'd love to hear from you:\n\n- **GitHub Issues**: https://github.com/Jiansen/mcp-doctor/issues\n- **Quick report** (if you have `gh` CLI):\n  ```bash\n  gh issue create --repo Jiansen/mcp-doctor --title \"Bug: ...\" --body \"...\"\n  ```\n\nIf you're an agent, include the JSON output of `check_server` in your report for context.\n\n## Contributing\n\n```bash\ngit clone https://github.com/Jiansen/mcp-doctor.git\ncd mcp-doctor\npip install -e \".[dev,ai]\"\nruff check src/ tests/\npytest tests/ -v\n```\n\n---\n\nIf MCP Doctor helped you improve your server, consider giving it a star on GitHub — it helps others discover the tool.\n\n[![Star on GitHub](https://img.shields.io/github/stars/Jiansen/mcp-doctor?style=social)](https://github.com/Jiansen/mcp-doctor)\n\n## License\n\nMIT\n",
  "bytes": 6637,
  "sha": "e3616bb3e5003dabffa0b6dcf51435329923f28a3b5d4f9c50638406b5c57b71",
  "repo_slug": "jiansen/mcp-doctor",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_jiansen_mcp_doctor_4e2087b3/readme"
}