{
  "markdown": "# SpecShield MCP Server\n\n**The API-change deploy gate for AI coding agents.** Ask *\"is it safe to ship this\nAPI change to my consumers?\"* right inside Claude, Cursor, and other MCP clients —\nand catch breaking changes before they reach your consumers.\n\nIt's a thin adapter over the [SpecShield](https://specshield.io) backend. Every tool\nis **read-only / analyze-only — it never modifies your code.**\n\n> Why not just diff specs? Plenty of tools (including free ones) list breaking\n> changes. SpecShield's job is the *decision*: **can I deploy this?** — the deploy\n> gate is the hero tool here.\n\n> ⚙️ **In CI/CD instead of an agent?** The [`specshield` CLI](https://www.npmjs.com/package/specshield) runs the same breaking-change and `can-i-deploy` checks in your pipeline (GitHub Action, exit codes). Same job, two entry points: this server for AI agents, the CLI for CI/CD.\n\n## Tools\n\n| # | Tool | What it answers |\n|---|------|-----------------|\n| 1 | **`is_change_safe`** ⭐ | Is this change safe to merge/deploy? Will it break consumers? (`safeToMerge` + risk + blocking reasons) |\n| 2 | `explain_breaking_changes` | What breaks, developer & consumer impact, suggested migration |\n| 3 | `generate_migration_guide` | Migration guide (markdown) + safe rollout steps |\n| 4 | `generate_release_notes` | Release notes for developer / customer / internal |\n| 5 | `compare_specs` | The raw diff (breaking / additions / modifications / warnings) + risk score |\n| 6 | `run_governance_review` 🔒 | API governance ruleset beyond breaking changes (missing operationId, error responses, security scheme, pagination, versioning…) → located findings + suggested fixes. **Paid (Team+)** |\n\nTools 1–5 accept specs inline (`baseSpecContent` / `targetSpecContent`) or by path\n(`baseSpecPath` / `targetSpecPath`). `run_governance_review` reviews a single spec\n(`specContent` / `specPath`).\n\n🔒 `run_governance_review` is a paid feature — a FREE API key returns a\n`payment_required` error. Upgrade at [specshield.io/pricing](https://specshield.io/pricing).\n\n> Full setup, verification & troubleshooting: **[docs/mcp-server-setup.md](docs/mcp-server-setup.md)**.\n\n## Install\n\nRequires **Node.js ≥ 20** and a SpecShield API key (from\n[specshield.io/account](https://specshield.io/account)).\n\n```bash\nnpx -y specshield-mcp-server\n```\n\n### Claude Desktop\n`claude_desktop_config.json`:\n```json\n{\n  \"mcpServers\": {\n    \"specshield\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"specshield-mcp-server\"],\n      \"env\": { \"SPECSHIELD_API_KEY\": \"ss_your_key_here\" }\n    }\n  }\n}\n```\n\n### Claude Code\n```bash\nclaude mcp add specshield --env SPECSHIELD_API_KEY=ss_your_key_here -- npx -y specshield-mcp-server\n```\n\n### Cursor\n`~/.cursor/mcp.json` (or the project `.cursor/mcp.json`):\n```json\n{\n  \"mcpServers\": {\n    \"specshield\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"specshield-mcp-server\"],\n      \"env\": { \"SPECSHIELD_API_KEY\": \"ss_your_key_here\" }\n    }\n  }\n}\n```\n\n## Configuration\n\n| Env var | Required | Default | Purpose |\n|---------|----------|---------|---------|\n| `SPECSHIELD_API_KEY` | **yes** | — | Your SpecShield API key. Store it as a secret; never commit it. |\n| `SPECSHIELD_API_URL` | no | `https://api.specshield.io` | Backend base URL (override for self-hosted/staging). |\n| `SPECSHIELD_TIMEOUT_MS` | no | `30000` | Per-request timeout. |\n| `SPECSHIELD_LOG_LEVEL` | no | `info` | `debug` \\| `info` \\| `warn` \\| `error` (logs go to stderr). |\n\n## Example prompts (lead with the deploy gate)\n\n- *\"Here are my old and new `openapi.yaml` — **is it safe to ship this API change to my consumers?**\"*\n- *\"Compare `v1.yaml` and `v2.yaml` and tell me if I can deploy, and why not.\"*\n- *\"Explain the breaking changes between these two specs and how consumers should migrate.\"*\n- *\"Generate customer-facing release notes for this API change.\"*\n\n## Security & privacy\n\n- **API key required.** Sent only as the `X-Api-Key` header to your configured backend.\n- **Read-only / analyze-only.** No mutation tools, no shell execution, no arbitrary\n  file access (a spec file is read only when you explicitly pass a path).\n- **No secret or spec logging.** The server never logs spec content, API keys, or\n  request bodies; error messages are redacted and machine-readable.\n- Specs are sent to your configured SpecShield backend for analysis.\n\n## Local development\n\n```bash\nnpm install\nnpm run build      # tsc → dist/\nnpm test           # vitest (no network)\nnpm run lint\nnpm run smoke      # boots the server against a stubbed backend and lists tools\nnpm start          # run the built server over stdio\n```\n\n## License\n\nMIT © SpecShield Software Private Limited\n",
  "bytes": 4644,
  "sha": "809d9700378bdab6f9be7ad809e976366808634780ef6269827fddc3c9def0aa",
  "repo_slug": "specshield26/specshield-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_specshield26_specshield_mcp_se_6594e982/readme"
}