Daksh-create349/Contradiction-MCP

**Autonomous Cross-Source Inconsistency & Contradiction Intelligence Engine for AI Agents**
Problem •
Capabilities •
Limitations •
Architecture •
Quickstart •
Tools Reference •
Tutorials •
Docs •
Contributing •
License
---
The Problem It Solves
Modern engineering ecosystems rely on fragmented, uncoordinated sources of truth:
- **Code Repositories**: package.json, Dockerfile, CI/CD workflows (.github/workflows/*.yml)
- **Deployment Manifests**: Kubernetes YAML, Helm values, cloud environment configurations
- **Technical Documentation**: Architecture guides, runbooks, developer setup portals, READMEs
- **Public Endpoints**: OpenAPI/Swagger schemas, status feeds, live web documentation
When these systems diverge—for example, a Kubernetes manifest deploying Node.js 22 while technical documentation instructs developers to run Node.js 18, or conflicting database engine versions across staging and production—silent regressions, deploy failures, and hallucinations in LLM reasoning occur.
**Contradiction MCP** bridges these silos through automated multi-source ingestion, context-aware contradiction reasoning, source authority and freshness scoring, human-in-the-loop review/resolution workflows, and immutable audit trails.
---
Core Capabilities
- **Zero Mocks**: Real embedded SQLite with Write-Ahead Logging (WAL), real filesystem I/O with directory containment guards, and real HTTP fetchers with pre-flight DNS validation.
- **Context-Aware Contradiction Engine**: Eliminates false positives by understanding semantic contexts:
- **Environments**: production vs staging vs development
- **Scopes**: file vs deployment vs cluster
- **Roles**: source_of_truth vs deployment vs documentation
- **Deterministic SemVer Mathematics & Value Type Isolation**: Employs rigorous version range satisfaction algebra rather than naive string comparisons. Strict IPv4/IPv6/host type discrimination ensures IP addresses (e.g. 127.0.0.1) are never misclassified as SemVer versions or compared against ports.
- **Namespace-Aware Leaf Predicate Matching**: Protects against heading-level false positives. Parameters under shared Markdown headings (e.g. 2_configuration_quantum_config_yaml_host vs 2_configuration_quantum_config_yaml_port) are discriminated by leaf property semantics so unrelated parameters never falsely match.
- **Multi-Column Matrix & Header Delimiter Parsing**: Markdown tables automatically skip table header rows and delimiter rows, cleanly extracting multi-column tables into composite property claims (e.g. python_minimum: 3.12+, python_recommended: 3.13).
- **Visual CI Badge Contradiction Detection**: Parses Markdown Shields.io and GitHub Action status badges to uncover visual discrepancies (e.g. conflicting build_status: passing vs build_status: failing badges).
- **Multi-Source Ingestion Pipeline**:
- **GitHub Connector**: Analyzes runtime engines, Dockerfiles, GitHub Actions workflows, and READMEs.
- **Document Connector**: Extracts structured claims from JSON, YAML, Markdown, CSV, TXT, RFC822 (.eml), and OpenXML (.docx) documents with exact page- and line-numbered evidence citations.
- **Public Website Connector**: Web crawler hardened with multi-layer SSRF protection against loopback, private IPv4/IPv6 CIDRs, and cloud metadata endpoints (169.254.169.254).
- **Scoring & Advisory Intelligence**:
- AuthorityScorer: Ranks conflicting claims based on source hierarchy and origin credibility.
- FreshnessScorer: Applies exponential half-life time decay models.
- EvidenceEvaluator: Quantifies citation directness and snippet quality.
- ResolutionAdvisor: Generates actionable resolution recommendations without mutating state without operator consent.
- **Review & Resolution Workflows**: Full lifecycle transitions (OPEN → REVIEWED → RESOLVED / DISMISSED → REOPENED) backed by append-only audit histories.
- **Dual Transport Architecture**: Operates over standard **Stdio** (for Claude Desktop, Google Antigravity, Cursor) or **Streamable HTTP/SSE** with Bearer API key authentication and sliding rate limiting.
---
Limitations & Known Edge Cases
While Contradiction MCP is battle-tested on cross-document and cross-source consistency audits, users and integrating agents should take note of current architectural boundaries and operational edge cases:
1. **Intra-Manifest Hierarchical Collisions (Deeply Nested JSON/YAML/K8s)**:
- **Behavior**: Key-value extraction flattens object hierarchies into leaf tokens. In complex single manifests (such as Kubernetes deployments or Terraform plans), parameters sharing identical leaf keys across distinct blocks (e.g., readinessProbe.initialDelaySeconds vs livenessProbe.initialDelaySeconds, or container resources.requests.cpu vs resources.limits.cpu) can trigger intra-file candidate comparisons and false-positive warnings.