<div align="center">

Contradiction MCP

Autonomous Cross-Source Inconsistency & Contradiction Intelligence Engine for AI Agents

<br/> <a href="https://glama.ai/mcp/servers/Daksh-create349/Contradiction-MCP"> <img src="https://glama.ai/mcp/servers/Daksh-create349/Contradiction-MCP/badges/card.svg" alt="Contradiction MCP on Glama" width="380" height="200" /> </a> <p align="center"> <a href="#the-problem-it-solves">Problem</a> • <a href="#core-capabilities">Capabilities</a> • <a href="#limitations--known-edge-cases">Limitations</a> • <a href="#system-architecture">Architecture</a> • <a href="#one-command-quickstart-all-ides">Quickstart</a> • <a href="#mcp-interface-12-canonical-tools-4-resources-2-prompts">Tools Reference</a> • <a href="#step-by-step-hands-on-tutorial">Tutorials</a> • <a href="#documentation-index">Docs</a> • <a href="CONTRIBUTING.md">Contributing</a> • <a href="#license">License</a> </p> </div>

---

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.
   • Mitigation: Focus analysis on cross-document source verification or filter by external source boundaries (sync_source / compare_sources). Full JSON-path namespace scoping is in development for future releases.

2. Heuristic Claim Extraction vs Nuanced Prose Negations:

   • Behavior: Heuristic extractors identify explicit version strings, ports, URLs, quantities, and key-value declarations from markdown tables, code fences, and bullet points. Complex natural language nuance, rhetorical negations (e.g., "We initially planned v3.0, but firmly rejected it in favor of v2.4"), or implied conditionals without standard configuration keys might not extract or may produce contradictory assertions requiring manual review.
   • Mitigation: Use explicit tabular or structured key-value declarations in documentation, or use create_claim to programmatically ingest claims with verified predicate semantics.

3. Connector Security Sandboxing & Network Boundaries:

   • Document Connector: File ingestion is strictly restricted to configured allowedRoots (default: current workspace). Paths outside these roots or attempts to navigate via directory traversal are rejected by design.
   • Website Connector: Enforces strict SSRF protections, blocking private RFC 1918 subnets, loopback interfaces (127.0.0.1, localhost), and cloud instance metadata endpoints (169.254.169.254). HTTP redirects are capped at 5 hops to prevent circular redirect exhaustion. Client-side rendered Single-Page Applications (SPAs) requiring JavaScript execution are not executed dynamically; static HTML snapshots or rendered markdown must be supplied.
   • GitHub Connector: Governed by GitHub REST API rate limits (60 requests/hour unauthenticated; 5,000 requests/hour with GITHUB_TOKEN).

4. Static Assertions vs Ephemeral Live Infrastructure:

   • Behavior: The engine analyzes declared assertions across files, repositories, API specs, and documentation. It does not probe live runtime network sockets, ephemeral cloud container states, or uncommitted database rows unless synced as structured state documents.

5. Pairwise Combinatorial Complexity on Monolithic Manifests:

   • Behavior: Files producing >1,000 claims increase pairwise combinations quadratically ($O(N^2)$ worst-case prior to subject grouping and similarity pruning).
   • Mitigation: Bounded file size guards (MAX_FILE_SIZE_BYTES, default 10MB) prevent memory exhaustion. Partition giant monolithic specifications into modular domain or component manifests.

6. Environment & Scope Assumptions:

   • Behavior: Contradiction MCP recognizes disjoint runtime environments (development, staging, testing, production, deployment, ci). However, if claims are ingested without explicit environment or scope metadata, the engine conservatively assumes they apply to the same global subject scope.
   • Mitigation: Provide explicit environment and scope arguments when syncing sources or creating claims to prevent false positives across heterogeneous environments.

7. Language & Domain Units:

   • Behavior: Predicate patterns, quantity normalizers (GB, MB, ms, s, ports, semantic versions, comma-formatted numbers), and terminology heuristics are tuned for English technical documentation and standard DevOps configurations. Multi-lingual prose extraction without standard keying is planned for future major releases.

---

System Architecture

Visual Dataflow

flowchart TD
    subgraph Clients["MCP Clients & IDEs"]
        Claude["Claude Desktop"]
        AGY["Google Antigravity"]
        Cursor["Cursor IDE"]
        HTTP["Remote HTTP / SSE"]
    end

    subgraph Protocol["MCP Protocol Layer"]
        StdioT["StdioServerTransport"]
        HttpT["StreamableHttpTransport"]
        Router["12 Canonical Tools | 4 Resources | 2 Prompts"]
    end

    subgraph Core["Analysis & Intelligence Engine"]
        Engine["ContradictionEngine"]
        Classifier["ContradictionClassifier"]
        Authority["AuthorityScorer"]
        Freshness["FreshnessScorer"]
        Advisor["ResolutionAdvisor"]
    end

    subgraph Connectors["Ingestion Connectors"]
        GH["GitHub Connector"]
        DOC["Document Connector (PDF/YAML/JSON/MD)"]
        WEB["Website Connector (SSRF Guarded)"]
    end

    subgraph Storage["Storage Layer"]
        DB[(SQLite WAL Mode)]
        Audit["Immutable Audit Trail"]
        Backups["Online Live Backups"]
    end

    Claude --> StdioT
    AGY --> StdioT
    Cursor --> StdioT
    HTTP --> HttpT

    StdioT --> Router
    HttpT --> Router

    Router --> Engine
    Router --> Connectors

    Conne