{
  "markdown": "![mcp-probe — one command to diagnose your MCP server](https://raw.githubusercontent.com/Incultnitollc/mcp-probe/main/og-card.png)\n\n# mcp-probe\n\n**One command to diagnose your MCP server.**\n\nTests every tool, resource, and prompt your server exposes — then gives you a health report with a pass/fail scorecard.\n\nBuilt on the Anthropic Model Context Protocol (MCP) spec.\n\n> **Note:** Published to npm as `@incultnitollc/mcp-probe`. The CLI binary is `mcp-probe`. The unscoped name `mcp-doctor` on npm is owned by an unrelated tool, so this project ships under a scope. Versions `<= 0.2.1` shipped under the deprecated `@incultnitostudiosllc` scope — install `@incultnitollc/mcp-probe` instead.\n\n<p align=\"center\">\n  <img src=\"demo.gif\" alt=\"mcp-probe demo\" width=\"800\" />\n</p>\n\n```\nnpx @incultnitollc/mcp-probe test \"npx -y @modelcontextprotocol/server-everything\"\n```\n\n## Test your MCP server in 30 seconds\n\n| Check | Description |\n|-------|-------------|\n| **Tool calling** | Calls every tool with auto-generated sample arguments based on the input schema |\n| **Resource reading** | Reads every resource and verifies content is returned |\n| **Prompt rendering** | Gets every prompt with sample arguments and verifies messages are returned |\n| **Schema validation** | Checks tool schemas for missing descriptions, broken required fields, malformed types |\n| **Health scoring** | Summarizes everything into a pass/fail scorecard |\n\n## Install\n\n```bash\nnpm install -g @incultnitollc/mcp-probe\n```\n\nOr run directly:\n\n```bash\nnpx @incultnitollc/mcp-probe test \"your-server-command\"\n```\n\n## Usage\n\n### Local stdio server\n\n```bash\nnpx @incultnitollc/mcp-probe test \"npx -y @modelcontextprotocol/server-everything\"\n```\n\n### Remote server (Streamable HTTP)\n\n```bash\nnpx @incultnitollc/mcp-probe test https://your-server.example.com/mcp\n```\n\n### Remote server (SSE)\n\n```bash\nnpx @incultnitollc/mcp-probe test https://your-server.example.com/mcp --transport sse\n```\n\n### Authenticated remote server\n\n```bash\nnpx @incultnitollc/mcp-probe test https://your-server.example.com/mcp \\\n  --header \"Authorization: Bearer $TOKEN\"\n```\n\n### Options\n\n| Flag | Description |\n|---|---|\n| `--json` | Output results as JSON |\n| `--timeout <ms>` | Per-operation timeout (default 30000) |\n| `--transport <kind>` | Force `stdio`, `sse`, or `http` (auto-detected from target) |\n| `--header <Name: value>` | Add header to remote transport. Repeatable. |\n\n### Exit codes\n\n- `0` — All checks passed\n- `1` — One or more checks failed (useful for CI gates)\n\n### JSON output\n\nUse `--json` to get structured output for automation:\n\n```bash\nmcp-probe test --json \"your-server\" | jq '.score'\n```\n\n```json\n{\n  \"toolsCallable\": 12,\n  \"toolsTotal\": 13,\n  \"resourcesReadable\": 7,\n  \"resourcesTotal\": 7,\n  \"promptsGettable\": 3,\n  \"promptsTotal\": 4,\n  \"schemaErrors\": 0,\n  \"schemaWarnings\": 1\n}\n```\n\n## How tool calling works\n\nmcp-probe auto-generates arguments for each tool based on its `inputSchema`:\n\n- Only **required** fields get values (safest approach)\n- Uses `default` values and `enum` first choices when available\n- Infers smart defaults from field names (`url` → `https://example.com`, `email` → `test@example.com`)\n- Falls back to type-appropriate defaults (`string` → `\"test\"`, `number` → `1`, `boolean` → `false`)\n\nThis means tools with complex required inputs may fail — and that's useful information. It tells you your tool isn't self-contained enough for automated testing.\n\n## Publishability score (v1.1.0+)\n\n`mcp-probe` ships a second, complementary check: a **publishability composite** that scores your server 0–100 on whether its schemas, descriptions, and metadata are ready for other people to install. Run it as a shorthand:\n\n```bash\nnpx @incultnitollc/mcp-probe score \"npx -y @your-scope/your-server\" --package ./package.json\n```\n\nOr fold it into a full `test` run with `--publishability`:\n\n```bash\nnpx @incultnitollc/mcp-probe test \"npx -y @your-scope/your-server\" --publishability --package ./package.json\n```\n\nThe composite combines three sub-scores — **Protocol** (does the wire format work), **Edge cases** (does it handle weird inputs), and **Publishability** (would a stranger understand your tools) — and a five-axis breakdown across the publishability dimension:\n\n| Axis | What it checks |\n|---|---|\n| `description-five-axis` | Per-tool description density across **purpose, mutation, side-effects, invariants, examples**. Tools below 3.0/5 axes fire a ≤60 composite cap. |\n| `enum-shape` | Catches prose-only enums (e.g. `\"one of: open, closed\"` in the description with no JSON Schema `enum`). |\n| `mutation-legibility` | Does each tool tell a planner it mutates, or only reads? Name prefix / description signal / annotation all count. |\n| `anti-purpose-clause` | High-blast tools (delete, send, transfer) should include a \"do not use for X, prefer Y\" pointer to a narrower tool. |\n| `distribution-metadata` | npm package readiness — description length, keyword count, `repository` / `license` / `homepage` fields. Skipped without `--package`. |\n\n### What scores look like on real servers\n\nThe five official Anthropic MCP servers all land at **60/100** under v1.1.0 — the `description-five-axis` cap fires on every one. That's not a bug in the rubric; that's the bar Anthropic ships at, and the bar most servers will start from. Full scorecards in [`docs/publishability-scorecards/`](docs/publishability-scorecards/SUMMARY.md).\n\n### CI gate\n\n```yaml\n- uses: incultnitollc/mcp-probe@v1\n  with:\n    command: 'node dist/index.js'\n    publishability: 'true'\n    package: './package.json'\n    fail-under: '70'\n```\n\n### Pre-publish vs install-time\n\n`mcp-probe`'s publishability score is the **pre-publish quality** lane — for server authors before they ship. For the install-time **security** lane — server installers before they connect a third-party server — see [`@stephenywilson/mcp-doctor`](https://www.npmjs.com/package/@stephenywilson/mcp-doctor). Different audiences, complementary tools.\n\n## Contract testing — \"VCR for MCP\" (v1.2.0+)\n\n`test`/`score` tell you if your server is healthy *today*. **Contract testing tells you what changed since last time** — so a breaking schema edit or a poisoned tool description never ships silently.\n\nRecord a snapshot of your server's contract (its tools, resources, prompts, and their schemas — no traffic, no side effects), commit the `.mcpvcr` file, then `diff` or `gate` every PR against it.\n\n```bash\n# 1. Record a baseline (lists only — never calls a tool)\nmcp-probe record \"node dist/index.js\" --out .mcp/contract.mcpvcr\ngit add .mcp/contract.mcpvcr && git commit -m \"record MCP contract baseline\"\n\n# 2. See what a change did to the contract\nmcp-probe diff --baseline .mcp/contract.mcpvcr \"node dist/index.js\"\n\n# 3. Gate CI — exit 1 on breaking or security changes\nmcp-probe gate --baseline .mcp/contract.mcpvcr \"node dist/index.js\"\n```\n\nEvery change is classified so the gate is meaningful, not noisy:\n\n| Severity | Examples |\n|----------|----------|\n| ❌ **breaking** | tool removed · new required argument · property removed · type changed · enum narrowed |\n| ⚠️ **security** | **tool description mutated (rug-pull / tool-poisoning)** · `readOnlyHint` dropped · tool became destructive |\n| ✅ **additive** | new tool · new optional field · enum widened |\n| ℹ️ **info** | server name · resource/prompt description text |\n\n`gate` fails on `breaking,security` by default — tune with `--fail-on breaking` (or any comma-separated set). Snapshots are **deterministic**: re-recording an unchanged server produces a byte-identical file, so committed baselines and diffs stay clean. Compare two recorded files offline with `--against <file>` instead of a live target, and write a ready-to-post PR comment with `--markdown <path>`.\n\nWhy it matters: the **2026-07-28 MCP spec** ships breaking changes (dropped `initialize` handshake, error-code and JSON-Schema shifts, HTTP+SSE → Streamable HTTP). A recorded `.mcpvcr` baseline turns \"did we break our clients?\" into a one-line CI check. See [`examples/contract-gate.yml`](examples/contract-gate.yml) for the full PR workflow with auto-commenting.\n\n## Use cases\n\n- **MCP server development** — Run mcp-probe in your test suite to catch regressions\n- **CI/CD gates** — Block deploys if your MCP server doesn't pass health checks\n- **Server evaluation** — Quickly assess third-party MCP servers before integrating them\n- **Schema quality** — Find missing descriptions and malformed schemas before users hit them\n\n## CI integration\n\n`mcp-probe` exits `0` on full pass and `1` on any failure, so it drops directly into any CI pipeline:\n\n```yaml\n# .github/workflows/mcp-health.yml\n- name: Health-check MCP server\n  run: npx @incultnitollc/mcp-probe test \"$MCP_SERVER_CMD\"\n```\n\nUse `--json` for structured output and `jq` to gate on specific metrics (e.g. fail the build if `schemaWarnings > 0`).\n\n## GitHub Action\n\nDrop mcp-probe into your MCP server's GitHub Actions workflow in two lines:\n\n```yaml\n- uses: incultnitollc/mcp-probe@v1\n  with:\n    command: 'node dist/index.js'\n```\n\nGate your PRs on a publishability composite:\n\n```yaml\n- uses: incultnitollc/mcp-probe@v1\n  with:\n    command: 'node dist/index.js'\n    publishability: 'true'\n    package: './package.json'\n    fail-under: '70'\n```\n\n### Inputs\n\n| Name | Required | Default | Description |\n|---|---|---|---|\n| `command` | yes | — | Command that launches your MCP server (e.g. `node dist/index.js` or `npx -y @your-scope/your-server`). |\n| `fail-under` | no | `0` | Fail the job if the publishability composite drops below this value (0–100). Requires `publishability: 'true'`. |\n| `publishability` | no | `false` | Run the publishability suite — 5 checks + 0–100 composite. Requires `mcp-probe >= 1.1.0` (ships 2026-05-23). |\n| `package` | no | `''` | Path to `package.json` for the distribution-metadata check. Empty skips the distribution check. |\n| `html-report` | no | `''` | Path to write the HTML scorecard. Upload via `actions/upload-artifact` in a follow-on step. |\n| `mcp-probe-version` | no | `latest` | npm version, dist-tag, or `latest`. Pin for reproducible builds. |\n| `json-output` | no | `''` | Path to write the JSON report for downstream parsing. |\n\n### Outputs\n\n| Name | Description |\n|---|---|\n| `composite-score` | Publishability composite (0–100). Only set when `publishability: 'true'`. |\n| `band` | Grade band: `publishable` / `almost` / `rough` / `not-ready`. Only set when `publishability: 'true'`. |\n| `tools-pass-rate` | `tools_callable / tools_listed` as a decimal (e.g. `0.83`). |\n| `schema-warnings` | Total schema warning count across all tools. |\n\nMore examples: [`examples/basic.yml`](examples/basic.yml) · [`examples/publishability-gate.yml`](examples/publishability-gate.yml) · [`examples/matrix.yml`](examples/matrix.yml).\n\nMarketplace listing: [github.com/marketplace/actions/mcp-probe-mcp-server-health-check](https://github.com/marketplace/actions/mcp-probe-mcp-server-health-check).\n\n## Compared to MCP Inspector\n\nThe official [MCP Inspector](https://github.com/modelcontextprotocol/inspector) is a GUI for interactive exploration — point, click, see what a server returns. `mcp-probe` is a CLI for automated, repeatable diagnosis — every tool/resource/prompt called automatically, pass/fail scorecard out, exit code in. Use Inspector when you're exploring; use `mcp-probe` in CI, in pre-publish checks, or when you want a shareable scorecard of someone else's server.\n\n## Ecosystem\n\n- **[MCP Registry](https://mcp-registry-dh5.pages.dev)** — Cross-source catalog of MCP servers (~6,900 indexed across 6 upstream lists) with quality scores powered by `mcp-probe`. CLI: `npm i -g @incultnitollc/mcpr`. Built by Incultnito LLC.\n\n## Development\n\n```bash\ngit clone https://github.com/incultnitollc/mcp-probe.git\ncd mcp-probe\nnpm install\nnpm run dev -- test \"npx -y @modelcontextprotocol/server-everything\"\nnpm test\n```\n\n## License\n\nMIT - [Incultnito LLC](https://github.com/incultnitollc)\n",
  "bytes": 11962,
  "sha": "a82c98295342b5c78ee08585933d47a80da8fed8eff9705ede9f210d94f67677",
  "repo_slug": "incultnitollc/mcp-probe",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_incultnitollc_mcp_probe_87e9c81a/readme"
}