Skip to content

cisco-open/mcptoolkit-contract

BranchesTags

Repository files navigation

MCP Toolkit: Server Contract

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

License: Apache-2.0 Status: pre-release Node.js: >=20.x

🚀 Quick Start

# Install from npm (recommended)
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:

📄 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.

This repository is the canonical home of the specification. The normative text, guides, examples, governance, and version history live under spec/; the versioned JSON Schemas live under schemas/mcp-description/.

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 (the full schema history is retained, and validate auto-detects each document's version). Companion tools — mcpeditor, mcpmock, and mcptest — consume the same format by vendoring a single schema version from here.

📖 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)
# 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

✅ 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

✅ 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

# 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/                # MCP Description (mcpdesc) specification — canonical source of truth
├── 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

License

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

About

a CLI to evaluate MCP servers throughout their lifecycle (dump, document, compare, changelog...)

Topics

quality mcp mcptoolkit mcpcontract

Resources

Readme

License

Apache-2.0 license

Code of conduct

Code of conduct

Contributing

Contributing

Security policy

Security policy
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases 2

1.0.0 Latest
Jul 1, 2026
+ 1 release

Packages

 
 
 

Contributors

Languages