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

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

Source checkout:

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

## MCP client setup

Example stdio configuration:

Installed package via `npx`:

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

Source checkout:

```json
{
  "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

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