Contradiction MCP README

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:

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. :

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

    Connectors --> DB
    Engine --> Classifier
    Engine --> Authority
    Engine --> Freshness
    Engine --> Advisor

    Engine --> DB
    DB --> Audit
    DB --> Backups

One-Command Quickstart (All IDEs)

Automatically configure Contradiction MCP into your favorite editor with a single command:

Universal CLI Setup

# Google Antigravity (configured in ~/.gemini/config/mcp_config.json and workspace)
npx -y contradiction-mcp install antigravity

# Cursor IDE (configured in ~/.cursor/mcp.json and workspace)
npx -y contradiction-mcp install cursor

# Claude Desktop App (configured in claude_desktop_config.json)
npx -y contradiction-mcp install claude

# Claude Code CLI (configured in ~/.claude.json & via claude mcp add)
npx -y contradiction-mcp install claude-code

# Windsurf IDE (configured in ~/.codeium/windsurf/mcp_config.json)
npx -y contradiction-mcp install windsurf

# Configure ALL detected IDEs simultaneously
npx -y contradiction-mcp install all

# Or install via Smithery CLI
npx -y smithery mcp add dakshshrivastav56/contradiction-mcp

Local Setup from Cloned Source

git clone https://github.com/Daksh-create349/Contradiction-MCP.git
cd "Contradiction MCP/contradiction-mcp"
npm install
npm run build

# Automatically configure in your current environment:
npm run install-mcp

# Or target a specific IDE:
node bin/cli.js install [antigravity|cursor|claude|claude-code|windsurf|all]

Manual IDE Client Configuration

If you prefer manual configuration, add the following configuration block to your client settings:

1. Claude Desktop (claude_desktop_config.json)

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "contradiction": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/contradiction-mcp/dist/index.js"],
      "env": {
        "NODE_ENV": "production",
        "DATABASE_PATH": "/ABSOLUTE/PATH/TO/contradiction-mcp/data/contradiction.db",
        "MCP_TRANSPORT": "stdio",
        "LOG_LEVEL": "error"
      }
    }
  }
}

2. Google Antigravity (mcp_config.json)

• Global: ~/.gemini/config/mcp_config.json
• Workspace: <workspace-root>/.agents/mcp_config.json

{
  "mcpServers": {
    "contradiction": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/contradiction-mcp/dist/index.js"],
      "env": {
        "NODE_ENV": "production",
        "DATABASE_PATH": "/ABSOLUTE/PATH/TO/contradiction-mcp/data/contradiction.db",
        "MCP_TRANSPORT": "stdio",
        "LOG_LEVEL": "error"
      }
    }
  }
}

3. Cursor IDE (.cursor/mcp.json)

{
  "mcpServers": {
    "contradiction": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/contradiction-mcp/dist/index.js"]
    }
  }
}

4. Streamable HTTP Remote Client

Connect distributed agents or team members to a centralized server daemon:

{
  "mcpServers": {
    "contradiction": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_SECRET_API_KEY"
      }
    }
  }
}

MCP Interface: 12 Canonical Tools, 4 Resources, 2 Prompts

Contradiction MCP exposes 12 canonical tools engineered to the highest specification standards (Glama Tool Definition Quality Score 5.0 / 5.0 Grade A). Every tool strictly follows verb_noun nomenclature, provides rich typed schemas, and isolates distinct operational domains.

Active Canonical MCP Tools (12)

[!TIP] Full Backwards Compatibility: Legacy tool names (health_check, sync_document, sync_website, sync_github_repository, scan_for_contradictions, scan_claim_for_contradictions, scan_source_for_contradictions, explain_claim_relationship, review_contradiction, dismiss_contradiction, reopen_contradiction, get_contradiction_history, get_claim_history, list_connectors, test_github_connection, sync_sources) continue to function without error via automatic request routing and parameter translation.

Active MCP Resources (4)

• health://metrics — Static snapshot of uptime, tool invocations, and contradiction tallies.
• contradiction://{id} — Dynamic resource returning live contradiction state for a specific ID.
• claim://{id} — Dynamic resource returning factual claim details, context, and provenance.
• source://{id} — Dynamic resource returning source metadata, type, and trust score.

Active MCP Prompts (2)

• investigate_contradiction — Interactive prompt guiding contradiction investigation, context analysis, and resolution.
• review_source_consistency — Agent prompt guiding systematic cross-source consistency audits.

Example Tool Payloads & Responses

{
  "filePath": "/tmp/deployment_spec.json",
  "subject": "api-server",
  "scope": "deployment",
  "environment": "production",
  "sourceRole": "deployment"
}

{
  "success": true,
  "sourceId": "76be8d2f-1e3b-48fd-922f-1b499251ac2b",
  "claimsCreated": 2,
  "claimsUpdated": 0
}

{}

{
  "status": "completed",
  "claimsScanned": 4,
  "candidatePairs": 2,
  "contradictionsFound": 1,
  "contradictions": [
    {
      "contradictionType": "VERSION_MISMATCH",
      "severity": "HIGH",
      "confidence": 1.0,
      "explanation": "Both claims describe the node_version for 'api-server'. However, architecture_guide.md reports '18.0.0' while deployment_spec.json reports '22.0.0'. Classified as VERSION_MISMATCH with HIGH severity.",
      "priorityScore": 0.93,
      "contradictionId": "2f1691be-9c1f-4e93-a86a-ef0c0ba54f9d"
    }
  ]
}

{
  "contradictionId": "2f1691be-9c1f-4e93-a86a-ef0c0ba54f9d"
}

{
  "recommendedClaimId": "a779fa4b-c680-482c-8f31-daf470aaaab7",
  "recommendedValue": "22.0.0",
  "confidenceScore": 0.88,
  "reasoning": "Claim B represents a higher-confidence candidate for current truth because it carries higher operational authority (0.85 vs 0.65) as deployment configuration and is equally fresh.",
  "authorityScoreA": 0.65,
  "authorityScoreB": 0.85
}

Step-by-Step Hands-On Tutorial

Tutorial: Detecting Real Document Contradictions in 30 Seconds

cd contradiction-mcp

# 1. Create two contradictory specifications for the same service:
cat << 'EOF' > /tmp/deployment_spec.json
{
  "node_version": "22.0.0",
  "database": "postgres-16"
}
EOF

cat << 'EOF' > /tmp/architecture_guide.md
# Architecture Guide
node_version: 18.0.0
database: postgres-14
EOF

# 2. Run test script to ingest and scan via Stdio MCP client:
npx tsx -e '
import { StdioClientTransport } from "@modelcontextprotocol/client/stdio";
import { Client } from "@modelcontextprotocol/client";

async function main() {
  const client = new Client({ name: "tester", version: "1.0.0" }, { capabilities: {} });
  await client.connect(new StdioClientTransport({ command: "node", args: ["dist/index.js"] }));

  // Ingest Deployment Spec (canonical: sync_source, role: deployment)
  await client.callTool({
    name: "sync_source",
    arguments: { filePath: "/tmp/deployment_spec.json", subject: "api-server", sourceRole: "deployment", environment: "production" }
  });

  // Ingest Architecture Guide (canonical: sync_source, role: documentation)
  await client.callTool({
    name: "sync_source",
    arguments: { filePath: "/tmp/architecture_guide.md", subject: "api-server", sourceRole: "documentation", environment: "production" }
  });

  // Automatically scan knowledge base (canonical: scan_contradictions)
  const scan = await client.callTool({ name: "scan_contradictions", arguments: {} });
  console.log("\nDISCOVERED CONTRADICTIONS:\n", JSON.stringify(JSON.parse(scan.content[0].text), null, 2));

  await client.close();
}
main();
'

Complete Command Reference

Environment Variables

Docker & Container Deployment

Run with Docker

# Build production container (multi-stage, non-root user):
docker build -t contradiction-mcp:latest .

# Run container with persistent data volume:
docker run -d \
  --name contradiction-mcp \
  -p 3000:3000 \
  -v contradiction-data:/app/data \
  -e MCP_TRANSPORT=http \
  -e HTTP_PORT=3000 \
  contradiction-mcp:latest

Run with Docker Compose

docker compose up -d
docker compose ps
docker compose logs -f

Release History

v0.3.1 (2026-09-15)

• Security & Extraction Hardening: Replaced shell string execution in DocumentConnector with safe execFileSync, eliminating command injection vectors in .docx processing.
• Website Connector Redirect Safety: Enforced a strict maximum of 5 HTTP redirects to prevent unbounded redirect loops and guaranteed timeout cleanup on all fetch error paths.
• Authority & Specification Role Scoring: Added 'specification' and 'deployment' to standard claim source roles with a dedicated authority score of 0.75 in AuthorityScorer, preventing specification claims from falling into low-confidence fallbacks.
• Evidence Metadata Alignment: Aligned connector provenance metadata (lineRange, evidence) with EvidenceEvaluator and AuthorityScorer schema expectations to accurately quantify citation directness and snippet quality.
• Deterministic Resolution Tie-Breaking: Enhanced ResolutionAdvisor to evaluate evidence quality as a deterministic tie-breaker before falling back to 'uncertain'.
• Environment Disjointness Heuristics: Expanded ContextAnalyzer environment comparison to recognize non-overlapping tiers (development, staging, testing, production, deployment, ci), eliminating false-positive contradiction flags across distinct environments.
• Comma-Formatted Numeric Normalization: Stripped comma separators in ValueComparator (isLikelyNumber, normalizeQuantity, compareNumbers) so formatted numbers (e.g., "5,000") compare accurately against integer values.
• Deterministic Database Pagination: Added SQL OFFSET support and primary key tie-breakers (ORDER BY created_at DESC, id ASC) across listSources, listClaims, and listContradictions queries.
• Server Tool Delegation Fixes: Delegated test_connection to registered connector implementations and forwarded pagination offsets and sync metadata.
• Expanded Regression Suite: Added dedicated regression test suite (tests/bugfixes.test.ts), raising test coverage to 181 passing tests across 25 suites.

v0.3.0 (2026-09-14)

• 12 Canonical Tools Architecture: Streamlined tool interface into 12 orthogonal, strictly typed verb_noun tools (check_health, list_sources, test_connection, sync_source, scan_contradictions, analyze_claim_pair, list_claims, get_claim, list_contradictions, get_contradiction, advise_resolution, resolve_contradiction).
• Zero-Breaking Backwards Compatibility Routing: Added a transparent request router shim ensuring all legacy tool names continue to function seamlessly with argument translation.
• Enhanced OpenXML (.docx) Ingestion: Direct extraction of table structures (<w:tr>, <w:tc>) as key-value assertions with XML stripping to eliminate duplicate claims.
• Multi-Format Cross-Document Consistency: Verified cross-referencing and contradiction discovery across Markdown runbooks, JSON configs, and Word architecture documents.
• Parametric Claim Queries: Extended SQLite database layer with multi-field filtering (predicate, environment, valueType, limit, offset).

v0.2.1 (2026-09-14)

• 22 Active MCP Tools: Full interface alignment including scan_source_for_contradictions for targeted source discovery.
• Section Heading Namespacing in Markdown: Hierarchical markdown headings (## to ######) namespace nested properties (e.g. ### API Gateway $\rightarrow$ api_gateway_port), preventing intra-document collisions while matching nested JSON configurations.
• Precision Predicate Similarity Guard: Enhanced claimMatcher requiring $\ge 50%$ token overlap on multi-token phrases, eliminating false matches between distinct properties sharing generic suffixes (node_version vs cache_version, runtime_node_version vs runtime_python_version).
• Scoped JSON Extraction: Streamlined flattenJsonObject to emit unique composite paths, avoiding leaf key duplication explosions.
• Numeric Claim Validation: Excluded valid single-digit numbers (4, 3) from short-value extraction warnings.
• Multi-Format Ingestion: End-to-end verified across Markdown, JSON, OpenXML .docx, and Kubernetes manifests.

v0.2.0 (2026-09-13)

• Initial public release with 21 core MCP tools, SQLite WAL persistence, GitHub, Document, and Website ingestion connectors.

Documentation Index

• Architecture Guide — Layered design, protocol topology, and component contracts.
• Security Model — Multi-layer SSRF defenses, directory containment, and scope authorizations.
• Connectors Reference — GitHub, Document (PDF/JSON/YAML/CSV/TXT), and Website connectors.
• Database & Migrations — Schema definitions, audit tables, and WAL configuration.
• Operations & Runbook — Online backups, rate limiting, scheduling, and graceful shutdown.
• Testing Strategy — Zero-mock philosophy, test suite itemization, and benchmarks.
• Practical Examples — Detailed walkthroughs of real-world contradiction scenarios.

License

This project is licensed under the MIT License.

MIT License
Copyright (c) 2026 Daksh Srivastava and Contradiction MCP Contributors

Free and open-source software — you are free to use, modify, distribute, sublicense, and deploy Contradiction MCP in personal and commercial environments.