MCP Toolkit: Server Contract

The mcpcontract CLI dumps capabilities from live MCP servers, and lets you create changelogs, detect breaking changes, and generate documentation.

• Getting Started: jump to the Quick Start — install and run your first dump
• Backward Compatibility: backward compatibility for MCP servers - spot breaking changes
• MCP Description specification: mcpdesc.org — format documentation and the current specification
• CLI Commands: mcpcontract dump, diff, changelog, compare, document...

The current CLI targets MCP Description v0.8. For tooling that emits MCP Description v0.7, use the maintained v1/main branch and the latest 1.x release.

🚀 Quick Start

# Install the latest mcpcontract CLI v2 from npm
npm install -g @cisco_open/mcptoolkit-contract

# Verify installation
mcpcontract --version

# Extract the capabilities from a live MCP server 
mcpcontract dump --transport streamable-http --url "https://learn.microsoft.com/api/mcp" --format yaml --output "dump.yaml"

# Generate documentation in markdown format
mcpcontract document dump.yaml --template reference-documentation --output doc.md

Next: the 101 Tutorial — a five-minute guided walkthrough that then leads into the complete workflow tutorial for the full pipeline.

🔍 Backward Compatibility Analysis

Create dumps for two releases of an MCP server, then compare them in one step:

mcpcontract compare \
  --from v1.json \
  --to v2.json \
  --suggest-version \
  --output CHANGELOG.md

The compare command runs the full pipeline (diff → breaking analysis → changelog) in-process. The changelog goes to --output (or stdout), a human-readable verdict goes to stderr, and exit codes follow the same contract as breaking: 0 (compatible), 1 (breaking changes found), 2 (error). Use --exit-zero to suppress the exit-1 gate (e.g. when you always want the changelog regardless of result).

For CI pipelines that need per-step artifacts, configurable gating, or separate report/changelog steps, see the CI/CD guide — it covers both the one-step compare path and the staged diff → breaking → changelog pipeline.

Key Features:

• 20+ Change Types: Tool/prompt/resource additions, removals, renames, parameter changes
• 35 Default Rules: Based on MCP compatibility guidelines and Postel's Law
• Customizable Rules: YAML-based rules with conditional matching
• Exit Codes: 0 (compatible), 1 (breaking), 2 (error)
• Changelog Formats: release (comprehensive notes), compact (brief), plus legacy detailed/summary/stats

Compatibility Philosophy:

• Enum Additions are Compatible: Following the open-world assumption, adding enum values is backward compatible
• Postel's Law: "Be liberal in what you accept" - clients should handle unknown values gracefully
• Customizable: Teams can override with stricter rules if needed (see rules/strict-compatibility.yaml)

📘 Read the full MCP Compatibility Guidelines for detailed philosophy, patterns, and best practices.

Documentation:

• MCP Compatibility Guidelines — Philosophy and best practices
• Example Artifacts

📄 The MCP Description (mcpdesc) Specification

mcpcontract reads and writes documents in the MCP Description format (mcpdesc) — a portable, machine-readable contract that declares everything an MCP server offers (tools, resources, prompts, transports, security), much like OpenAPI does for REST APIs. Every dump, diff, document, and breaking operation is built on this format.

The current specification is published at mcpdesc.org and developed and maintained in the canonical mcpdesc/mcpdesc-specification repository.

• Read the v0.8 specification: mcpdesc.org/docs/specification/0.8.0
• Contribute to the format: mcpdesc/mcpdesc-specification
• Browse versioned schemas: schemas/mcp-description
• Bundled legacy material: the local spec/ tree and mcpdesc 0.7.0 schema are retained for compatibility and migration

The v2 CLI emits MCP Description v0.8 using an exact immutable schema URI. It retains v0.7 validation and migration support, but users who need new v0.7 dumps should use the maintained v1/main branch. New v0.8 dumps do not include x-cisco-metadata.

The format is versioned independently of this CLI. mcpcontract targets a specific mcpdesc version and is kept in sync as the specification advances, preserving backward compatibility with documents authored against older versions wherever possible. Companion tools — mcpeditor, mcpmock, and mcptest — consume the same independently maintained format.

📖 Commands

✅ dump - Generate an MCP description from a live server

Connects to a live MCP server and extract its description (transport, tools, prompts, resources)

Note: the command supports three transports:

• streamable-http or http (accepted as alias)
• stdio
• sse (legacy - deprecated transport for MCP servers)

Protocol negotiation defaults to --protocol auto, which probes modern MCP 2026-07-28 discovery and falls back to legacy initialization. Use --protocol legacy to skip discovery or --protocol 2026-07-28 to require modern discovery without fallback.

# Dump capabilities using a config file
mcpcontract dump --config server-config.json --output dump.json

#  Dump capabilities using CLI options - HTTP transport 
mcpcontract dump \
  --transport streamable-http \
  --url "http://localhost:3000/mcp" \
  --output dump.json

# Dump capabilities using CLI options - STDIO transport (server name auto-generated from command)
mcpcontract dump \
  --transport stdio \
  --command "npx" \
  --args "-y" "@modelcontextprotocol/server-everything" \
  --output dump.json

✅ document - Generate documentation

Generate human-readable documentation from an MCP description.

mcpcontract document dump.yaml --template reference-documentation --output doc.md
mcpcontract document dump.yaml --template mcpdesc-documentation --output README.md
# Authored multi-version descriptions require one effective view
mcpcontract document spec.yaml --protocol-version 2026-07-28 --output README.md

✅ diff - Compare two releases of an MCP server

Generate structural diff between two MCP descriptions.

mcpcontract diff --from dump-v1.json --to dump-v2.json --output diff.json
# Authored multi-version descriptions require one effective view
mcpcontract diff --from v1.json --to v2.json --protocol-version 2026-07-28

✅ breaking - Detect Breaking Changes

Apply compatibility rules to identify breaking changes. The output analysis file contains both the original diff data and severity annotations.

mcpcontract breaking --diff diff.json --rules rules/breaking-changes.yaml --output diff-breaking.json

Exit Codes: 0 (compatible), 1 (breaking), 2 (error)
Note: The analysis file includes the complete diff with added severity ratings, so changelog can use it as a standalone input.

✅ changelog - Generate Human-Readable Changelogs

Render markdown changelogs from a structural diff or an annotated diff. Run breaking first to highlight breaking changes.

# Comprehensive release notes (default)
mcpcontract changelog --diff diff-breaking.json --output CHANGELOG.md --format release

# Brief one-line-per-change summary
mcpcontract changelog --diff diff-breaking.json --output CHANGELOG.md --format compact

Input: --diff <file> — the structural diff from diff, or the annotated diff from breaking (e.g. diff-breaking.json). Run breaking first to highlight breaking changes. The command is a pure renderer and always exits 0 on success.

✅ compare - Run the Full Comparison Pipeline in One Step

Runs diff → breaking analysis → changelog in a single command. Useful for ad-hoc comparisons and simple CI steps where per-step artifacts are not needed.

# Compare two versions, render a changelog, and gate on breaking changes
mcpcontract compare --from v1.json --to v2.json --output CHANGELOG.md

# Include a SemVer recommendation in the report
mcpcontract compare --from v1.json --to v2.json --suggest-version --output CHANGELOG.md

# Compact format; exit 0 regardless of breaking changes (changelog always written)
mcpcontract compare --from v1.json --to v2.json --format compact --exit-zero --output CHANGELOG.md

# Escape hatches: also write the intermediate diff and breaking-analysis files
mcpcontract compare --from v1.json --to v2.json \
  --emit-diff diff.json \
  --emit-breaking diff-breaking.json \
  --output CHANGELOG.md

Exit Codes: 0 (compatible), 1 (breaking changes found), 2 (error) — same contract as breaking. --exit-zero suppresses the 1→0 promotion but never masks 2.

For fine-grained CI control (per-step artifacts, separate gate and report jobs), see the CI/CD guide.

✅ rules - Browse Compatibility Rules Catalog

Browse and explore the backward compatibility rules catalog with comprehensive documentation and examples.

# List all rules (default catalog)
mcpcontract rules list

# Discover available catalogs in the rules/ directory
mcpcontract rules list-catalogs

# List rules from custom catalog (shows severity comparison)
mcpcontract rules list --catalog rules/strict-compatibility-catalog
mcpcontract rules list --catalog rules/my-team-catalog

# Filter rules
mcpcontract rules list --category tools --breaking
mcpcontract rules list --severity critical

# Show detailed documentation for a rule
mcpcontract rules show parameter-enum-values-changed
mcpcontract rules show tool-removed

# Show documentation from custom catalog
mcpcontract rules show parameter-enum-values-changed --catalog rules/strict-compatibility-catalog

# Display pass/fail examples
mcpcontract rules examples parameter-added
mcpcontract rules examples parameter-enum-values-changed --variant enum-additions-only

# Display examples from custom catalog
mcpcontract rules examples parameter-added --catalog rules/my-team-catalog

# Validate catalog completeness
mcpcontract rules validate
mcpcontract rules validate --rules rules/strict-compatibility.yaml
mcpcontract rules validate --catalog rules/my-team-catalog

# Export catalog
mcpcontract rules export --output catalog.json
mcpcontract rules export --format markdown --output RULES.md
mcpcontract rules export --catalog rules/strict-compatibility-catalog --format markdown

Catalog: 34 documented rules across tools (12), prompts (8), resources (6), resourceTemplates (3), serverInfo (5) — each with rationale, migration guidance, and pass/fail examples. Custom team catalogs are supported via --catalog, which also shows how severities differ from the defaults. See the rules catalog tutorial.

✅ split - Split Large Dumps into Focused Subsets

Organize large federation server dumps by service or domain using regex-based filtering.

# Split by service prefix patterns
mcpcontract split federation-dump.json \
  --config split-config.yaml \
  --output-dir ./split-dumps \
  --validate

# Preview without creating files
mcpcontract split federation-dump.json \
  --config split-config.yaml \
  --dry-run

Key Features:

• Regex-based name pattern matching (Phase 1: tools only)
• Multiple output categories from single input
• Overlap support (tools can match multiple categories)
• Unmatched items handling (ignore/warn/error/separate-file)
• Split metadata tracking in outputs
• JSON and YAML format support

Status: ✅ Fully implemented and tested (Phase 1: tools filtering only)

✅ validate - Check compliance with specifications

Check a document is compliant with the MCP Description specification.

# Validate an MCP description
mcpcontract validate dump.yaml --schema mcpdesc --strict

🏗️ Project Structure

For a detailed file/module map see AGENTS.md. High-level layout:

mcpcontract/
├── src/
│   ├── commands/        # Commander subcommands (thin argument-parsing layer)
│   ├── lib/             # Core logic (dumper, differ, rules-engine, splitter, …)
│   └── index.ts         # CLI entry point
├── spec/                # Archived MCP Description v0.7 specification material
├── schemas/             # JSON schemas (versioned: mcp-description/, diff/, …)
├── rules/               # Compatibility rules (YAML) + documentation catalog
├── templates/           # Handlebars templates (dumps, changelogs)
├── scripts/             # Helper scripts (badge sync)
├── tests/               # Jest unit + integration tests, shell smoke tests
└── docs/
    ├── users/           # User guides, tutorials, examples
    └── maintainers/     # Architecture, design decisions, internal notes

📖 Example Artifacts

See docs/users/examples/ for working examples:

• microsoft-learn/ — real dumps from the public Microsoft Learn MCP server, including two historical snapshots for diff/changelog
• http-with-auth-config.yaml — MCP server config with Bearer-token authentication
• split-federation-services.yaml + split-example.md — splitting a federation dump by service
• html/ — sample HTML output from mcpcontract document

🔧 Maintenance

# Build
npm run build

# Watch mode (auto-rebuild on changes)
npm run watch

# Clean build directory
npm run clean

# Run tests 
npm test

# Test coverage
npm run test:coverage

📚 Documentation

• 101 Tutorial — Install & generate your first dump in five minutes
• Full Tour Tutorial — End-to-end tutorial
• User docs — Schemas, compatibility guidelines, examples
• Maintainer docs — Architecture and design decisions

License

This software is licensed under the Apache License 2.0. See LICENSE for details.