submit: Contract Guard - deterministic API breaking-change detector for AI agents

[kestarsheng]

Contract Guard

Deterministic API breaking-change detector for AI agents.

Contract Guard gives any AI agent the ability to judge whether an API change is safe or breaking — without guessing. It compares two versions of an OpenAPI, GraphQL, or JSON Schema contract and returns structured, reproducible findings in milliseconds. The core diff engine is 100% deterministic and works offline; an optional LLM advisory layer can append consumer-impact context when a key is configured.

Why not just ask the LLM?

LLMs hallucinate schema diffs, miss nested constraint tightenings, and can't guarantee the same answer twice. Contract Guard's rule engine is built for the exact job: every input pair produces the same finding set, every time.

Beyond the diff: consumer-aware impact + verifiable engines

Plain contract diffing is a mature space (oasdiff, GraphQL Inspector, Redocly). Contract Guard goes beyond it with three capabilities classic diff tools do not have:

1. Consumer-aware impact scan (POST /v1/consumer-scan + MCP scan_consumer_impact): pass a consumer_profile describing which paths/schemas/fields your agent actually uses, and it separates findings that hit your subset from ignorable ones. Answers "is this breaking FOR ME" instead of "is it breaking for everyone".
2. Transitive propagation: builds the schema→operation reference graph and annotates each finding with affected_operations. A type change on Pet.id reports ['GET /pets', 'GET /pets/{id}'], not just the diff location.
3. Regression benchmark (GET /v1/benchmark + MCP run_benchmark): 16-sample labelled corpus replayed through the engines, reporting accuracy/precision/recall/F1 (currently 1.0/1.0/1.0/1.0). Deterministic and reproducible — judges can run it themselves.

Key features

• 3 contract formats: OpenAPI 3.x, GraphQL SDL, JSON Schema (draft-07 / 2020-12)
• 35+ change types detected (endpoint removed, type changed, constraint tightened, enum value removed, content-type changed, deprecation, GraphQL directives, JSON Schema 2020-12 keywords, etc.)
• Dual-engine architecture: confirmed (deterministic rules) + advisory (optional LLM impact assessment)
• MCP server: 8 tools (check_breaking_changes, list_supported_formats, explain_change_type, suggest_version_bump, generate_changelog, suggest_migration, scan_consumer_impact, run_benchmark)
• REST API: 8 endpoints (POST /v1/diff, /v1/chain-diff, /v1/semver, /v1/migration, /v1/sarif, /v1/changelog, /v1/consumer-scan, GET /v1/benchmark)
• SARIF 2.1.0 export for GitHub Code Scanning
• 8-tab interactive demo workbench at / (breaking diff, chain diff, SemVer, migration, SARIF, changelog, consumer-aware impact scan, regression benchmark — with EN/中文 i18n and inline SVG icons)
• 64 unit tests, all passing

Live endpoints

• API: https://contract-guard-eta.vercel.app/v1/diff
• Health: https://contract-guard-eta.vercel.app/health
• Verification: https://contract-guard-eta.vercel.app/.well-known/xagent-verification.json
• Benchmark: https://contract-guard-eta.vercel.app/v1/benchmark
• MCP: https://contract-guard-eta.vercel.app/mcp
• Demo: https://contract-guard-eta.vercel.app/

Source

• Repository: https://github.com/kestarsheng/contract-guard
• Review commit: ad59479231feefe6d9aa9afc1f7578c49bfbf871

Tech stack

FastAPI + FastMCP 4.0.3 + graphql-core 3.2 + PyYAML + Vercel (Python 3.12)

[github-actions]

Submission received — #54

Thank you for submitting to the current X-Agent MCP Hackathon. We have received your pull request.

This is a receipt only. It does not confirm eligibility, completeness, technical approval, a judging result, or an award. Passing automated checks or merging code for archival purposes does not, by itself, mean the entry has passed review or won a prize.

Please include the complete source for the submitted capability in this repository under submissions/mcp-hackathon/<slug>/source/, with dependency files, configuration examples, and reproducible setup/build instructions. An external repository link alone is not sufficient. The official copy is intended to remain available if the original repository later becomes unavailable. Do not include secrets, credentials, or private user data; clearly disclose external and private-service dependencies.

The automated checks report technical checks separately. A workflow failure is not a judging decision. Keep updates in this PR while submissions remain open, and keep the documented source version and deployment evidence consistent.

See the submission instructions. Final review results and awards will be announced separately through the official event channels.