# Clearon Content Archive MCP

MCP server for append-only content records, verified publication history, social follow-through, and retrieval-friendly metadata.

It is designed to preserve provenance and workflow state without publishing anything itself.

## What it does

- Stores append-only content events per slug.
- Maintains a materialized snapshot for fast reads and repairs stale snapshots from the durable event log during normal reads.
- Records verified WordPress and social outcomes.
- Tracks source corrections without rewriting earlier history.
- Provides overlap search, inventory, and follow-through reporting.
- Verifies whether event history exactly matches the stored snapshot.
- Finds records by exact slug, current post ID, and current or historical recorded publication/social URLs.

## What it does not do

- It does not publish to WordPress or social platforms.
- It does not treat a payload marked `publish` as proof of live publication.
- It does not make legal or editorial truth determinations.
- It does not allow artifact paths outside the configured workspace.

## Requirements

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

## Installation

```sh
cd tools/clearon-content-archive-mcp
npm install
npm test
npm run smoke
```

## MCP client setup

Example stdio configuration:

```json
{
  "mcpServers": {
    "clearon-content-archive": {
      "command": "node",
      "args": ["/absolute/path/to/clearon-content-archive-mcp/server.mjs"],
      "env": {
        "CLEARON_CONTENT_ARCHIVE_WORKSPACE": "/absolute/path/to/workspace"
      }
    }
  }
}
```

Use `CLEARON_CONTENT_ARCHIVE_WORKSPACE` to define the root against which local artifact paths are validated. Override the archive storage location with `CLEARON_CONTENT_ARCHIVE_ROOT`.

## Storage

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

- macOS: `~/Library/Application Support/clearon-content-archive-mcp/content-archive`
- Linux: `${XDG_DATA_HOME:-~/.local/share}/clearon-content-archive-mcp/content-archive`
- Windows: `%APPDATA%\\clearon-content-archive-mcp\\content-archive`

Each record lives under `records/<slug>/` and stores:

- `events.jsonl`
- `snapshot.json`

## Verification and repair

`verify_archive_record` is read-only. It compares the rebuilt event history to the stored snapshot and reports whether they match.

Automatic repair runs on normal record reads and mutation paths so a stale materialized snapshot does not hide a newer durable event.

The package audit CLI is:

```sh
npm run audit
```

It reports verification failures explicitly instead of silently skipping them.

## Recommended workflow

1. Register the local draft package.
2. Append verified publication or update results.
3. Append LinkedIn and X outcomes, including blockers or skips.
4. Record provenance corrections as new events.
5. Use overlap and search tools before drafting related work.
6. Use inventory and incomplete-follow-through output during audits.
7. Run verification after migration, manual recovery, or suspected corruption.

## Tools

- `get_server_health`
- `register_content_package`
- `get_content_record`
- `search_content_archive`
- `find_content_record`
- `update_content_artifacts`
- `record_publication`
- `record_social_result`
- `record_source_correction`
- `approve_voice_example`
- `compare_payload_to_live_state`
- `find_content_overlap`
- `list_incomplete_follow_through`
- `list_update_candidates`
- `generate_content_inventory`
- `verify_archive_record`

## URL handling

Stored URLs must use `http` or `https`, and URL credentials are rejected.

Because archive history is append-only, avoid writing sensitive URLs with tokens or other secrets in query strings.

## Development

```sh
npm test
npm run smoke
npm run syntax
npm run audit
```