Skip to content

101-tutorial.md

Latest commit

 

History

History
90 lines (67 loc) · 2.78 KB

101-tutorial.md

File metadata and controls

90 lines (67 loc) · 2.78 KB
Raw

101 Tutorial

Get going with mcpcontract in five minutes using the public Microsoft Learn MCP Server.

Install

# From npm (recommended)
npm install -g @cisco_open/mcptoolkit-contract

# …or from source
git clone https://github.com/cisco-open/mcptoolkit-contract.git
cd mcptoolkit-contract && npm install && npm run build && npm install -g .

mcpcontract --version

1. Extract capabilities

# Interactive wizard (easiest first run)
mcpcontract dump

# …or directly
mcpcontract dump \
  --transport streamable-http \
  --url https://learn.microsoft.com/api/mcp \
  --format yaml \
  --output ms-learn-dump.yaml

Add --verbose to debug connection issues. The output is an mcpdesc document describing every tool the server exposes.

2. Validate

mcpcontract validate ms-learn-dump.yaml          # auto-detects schema + version
mcpcontract validate --show-compatibility        # CLI ↔ schema matrix

3. Generate documentation

mcpcontract document ms-learn-dump.yaml \
  --template reference-documentation \
  --output ms-learn-documentation.md

4. Track changes between versions

This repo ships two historical snapshots of the Microsoft Learn server so you can run a real comparison without dumping twice:

D=docs/users/examples/microsoft-learn

mcpcontract compare \
  --from $D/ms-learn-dump-v1.0.0-2025-11-20.yaml \
  --to   $D/ms-learn-dump-v1.0.0-2026-06-30.yaml \
  --suggest-version \
  --output CHANGELOG.md

You'll see 8 changes (4 breaking) and a recommended MAJOR bump (1.0.0 → 2.0.0) — new tool output schemas and capability changes, with the deprecated question parameter removed. compare exits 1 when breaking changes are found, which gates CI automatically. The full changelog lands in CHANGELOG.md; use --format compact for a brief one-line-per-change summary.

Under the hood, compare runs diff → breaking → changelog in one step. For CI pipelines that need per-step artifacts or separate gate/report jobs, see the CI/CD guide.

What you just did

  • Extracted capabilities from a live MCP server
  • Validated the dump against the mcpdesc schema
  • Rendered human-readable documentation
  • Compared two versions and generated release notes

Next steps