Catching Documentation Drift Before It Breaks Production: How I Built Contradiction MCP

Description and use

Contradiction MCP systematically detects documentation drift across technical sources by extracting claims with provenance, performing context-aware comparison, and using semantic versioning logic to distinguish meaningful conflicts from harmless differences. The tool provides evidence-backed resolution advice and persists findings in an audit database, making contradiction detection traceable rather than producing mysterious verdicts.

Problem

Documentation drift between technical sources (README, Dockerfile, deployment configs, setup guides) causes broken setups and wasted debugging time. When AI coding agents rely on inconsistent documentation, they can make reasonable decisions based on incorrect information.

Outcome

Contradiction MCP systematically detects documentation drift across technical sources by extracting claims with provenance, performing context-aware comparison, and using semantic versioning logic to distinguish meaningful conflicts from harmless differences. The tool provides evidence-backed resolution advice and persists findings in an audit database, making contradiction detection traceable rather than producing mysterious verdicts.

Workflow

• Connect Contradiction MCP as an MCP server to AI coding agents or CLI tools via stdio or HTTP transport.
• Ingest supported technical sources: repository files (package.json, Dockerfiles, CI workflows, deployment manifests), technical documents (Markdown, YAML, JSON, CSV, plain text, Word, PDF, email), and web sources (public documentation, endpoints, status pages).
• Extract claims with provenance: each extracted claim retains subject, predicate, value, valueType, confidence, context (environment, scope, sourceRole), and provenance (filePath, lineNumber, pageNumber, rawSnippet).
• Generate candidate pairs of claims worth comparing across sources.
• Apply context analysis: filter out differences that are valid because of environment or scope (e.g., debug: true in dev vs. debug: false in prod; different ports for different services).
• Compare typed values using semantic versioning logic for version constraints (e.g., ^22.0.0 vs. >=22.1.0 <23.0.0 are compatible; >=18.0.0 <19.0.0 vs. >=22.0.0 <23.0.0 are disjoint).
• Classify contradictions by type, severity, and confidence.
• Score authority and freshness of each source to recommend which source should be trusted.
• Generate evidence-based advice for investigation and resolution.
• Persist findings and audit history in SQLite database.

Evidence

You clone a repository. The README says: Prerequisites: Node.js 18.x and PostgreSQL 14. You install the dependencies, configure the environment, run the migrations, and start the application. It fails. After hours of debugging, you discover that the Dockerfile now uses Node.js 22, the deployment configuration specifies PostgreSQL 16, and an internal setup guide still references an older version.

Source

This is documentation drift: the gradual divergence between what a system actually does and what its documentation claims.

Source

Agents rely on READMEs, architecture documents, configuration files, and API specifications to understand a project. If those sources disagree, an agent can make a perfectly reasonable decision based on incorrect information.

Source

I wanted to build something that could identify these conflicts systematically rather than relying on someone to notice them during a code review.

Source

Contradiction MCP extracts technical claims from different sources, compares claims that are relevant to one another, identifies potential contradictions, and provides evidence to help determine which