Clearon Source Audit MCP

MCP server for revision-bound source review, quotation matching, and prepublication evidence-control reports.

It is designed to preserve exactly what was audited. It does not publish articles, decide truth, or replace legal/editorial judgment.

What it does

• Binds each audit to an exact article revision fingerprint.
• Records source classifications and claim-to-source mappings.
• Verifies direct quotations against retrieved source text.
• Revalidates stored source-text fingerprints before trusting retrieved evidence.
• Flags procedural-language risks such as stating allegations as holdings.
• Generates immutable JSON reports for the audited revision.
• Highlights source-integrity mismatches as explicit publish/update review items for the user.

What it does not do

• It does not determine legal correctness or factual truth.
• It does not publish or modify external systems.
• It does not treat retrieval failure as proof that a source is false.
• It does not convert acknowledged warnings into substantive support.
• It does not treat acknowledged substantive claim gaps as publication-ready support.
• It does not treat source-integrity mismatches as repaired just because the user approved a publish/update exception.

Requirements

• Node.js 20 or newer
• A local MCP client that can launch a stdio server

Installation

Published package:

npm install -g clearon-source-audit-mcp
clearon-source-audit-mcp

Source checkout:

cd tools/clearon-source-audit-mcp
npm install
npm test
npm run smoke

MCP client setup

Example stdio configuration:

Installed package via npx:

{
  "mcpServers": {
    "clearon-source-audit": {
      "command": "npx",
      "args": ["-y", "clearon-source-audit-mcp"]
    }
  }
}

Source checkout:

{
  "mcpServers": {
    "clearon-source-audit": {
      "command": "node",
      "args": ["/absolute/path/to/clearon-source-audit-mcp/server.mjs"]
    }
  }
}

If you want audit data somewhere specific, set CLEARON_SOURCE_AUDIT_ROOT in the client environment.

Storage

By default, audit data is stored outside the repository in a user data directory:

• macOS: ~/Library/Application Support/clearon-source-audit-mcp/source-audits
• Linux: ${XDG_DATA_HOME:-~/.local/share}/clearon-source-audit-mcp/source-audits
• Windows: %APPDATA%\\clearon-source-audit-mcp\\source-audits

Override that location with CLEARON_SOURCE_AUDIT_ROOT.

Each audit stores:

• audit.json
• article.txt
• reports/*.json

Files are written with owner-only permissions where the host platform supports them.

Recommended workflow

1. Create or obtain the exact article text to audit.
2. Compute its SHA-256 fingerprint.
3. Call create_source_audit.
4. Call register_source for each source.
5. Call record_claim_mapping for checkable factual or legal claims.
6. Run run_mechanical_checks.
7. Fix weak claims, missing excerpts, quotation mismatches, and procedural warnings in the article.
8. If the article text changes, create a new audit for the new revision.
9. Call generate_source_report.
10. Use acknowledge_finding only when a human has actually reviewed and accepted a claim or source-retrieval warning.
11. If the report lists pending_publish_update_review_findings, use approve_source_integrity_finding only when you explicitly approve that exact source-integrity mismatch for publish/update.
12. Treat ready_for_human_approval as blocked until every claim is substantively supported and every non-integrity warning is either resolved or explicitly acknowledged.
13. Treat ready_for_publish_or_update as blocked until the report has no pending source-integrity review items.

Tools

• get_server_health
• create_source_audit
• get_source_audit
• list_source_audits
• register_source
• record_claim_mapping
• replace_claim_mapping
• run_mechanical_checks
• generate_source_report
• approve_source_integrity_finding
• acknowledge_finding

Network behavior

URL availability checks are opt-in. run_mechanical_checks and generate_source_report default check_urls to false.

When enabled, the server performs bounded HTTP(S) reachability checks and treats failures as warnings only. Before each request (including redirects), it rejects local/private DNS answers and pins the connection to the validated public addresses to narrow DNS-rebinding exposure. This is a convenience check, not a trust decision or a replacement for host-level egress controls.

Source-retrieval warnings use a stable acknowledgment string; transport details are preserved separately in the verification output.

Source-integrity warnings are handled differently. They appear in a dedicated publish/update review list in the report and require explicit user approval before the report becomes ready_for_publish_or_update.

Development

npm test
npm run smoke
npm run syntax
node --check server.mjs