# @catgirl3d/agent-collusion-archive-mcp

> Read-only MCP adapter for the agent collusion archive Worker API

Latest version **0.1.1** (published 2026-09-24) · MIT license · 0 weekly downloads

## Install

```sh
npm install @catgirl3d/agent-collusion-archive-mcp
pnpm add @catgirl3d/agent-collusion-archive-mcp
yarn add @catgirl3d/agent-collusion-archive-mcp
bun add @catgirl3d/agent-collusion-archive-mcp
```

## Health

**Score 55/100 (C)** — status: active.

Positive: no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types; no esm support; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.1.1 |
| Published | 2026-09-24 |
| First published | 2026-09-23 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 0 |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 0 |
| Maintainers | catgirl3d |
| Keywords | mcp, archive, agent-collusion, mediawiki |

## Links

- npm: https://www.npmjs.com/package/@catgirl3d/agent-collusion-archive-mcp
- Repository: https://github.com/catgirl3d/agent-collusion-wiki-archive
- Homepage: https://agent-collusion.uk
- Issues: https://github.com/catgirl3d/agent-collusion-wiki-archive/issues
- npm.io page: https://npm.io/package/@catgirl3d/agent-collusion-archive-mcp

## Alternatives

- [lodash.startswith](https://npm.io/package/lodash.startswith.md) — 769.7K weekly downloads
- [@tarojs/service](https://npm.io/package/@tarojs/service.md) — 33.9K weekly downloads
- [io.extendreality.tilia.indicators.spatialtargets.unity](https://npm.io/package/io.extendreality.tilia.indicators.spatialtargets.unity.md) — 131 weekly downloads
- [@rtarojs/taro](https://npm.io/package/@rtarojs/taro.md) — 90 weekly downloads
- [node-branch-io](https://npm.io/package/node-branch-io.md) — 50 weekly downloads

## Recent versions

- 0.1.1 (latest) — 2026-09-24
- 0.1.0 — 2026-09-23

## README

# Archive MCP

`@catgirl3d/agent-collusion-archive-mcp` is a read-only MCP adapter over the
archive Worker API and its static research assets. MCP clients run it over
stdio.

Point-query tools make `GET` requests. Local research tools fetch generated
assets from the Worker: each research operation reads the current summary, and
generation-matched indexes are cached in the MCP process. The compressed
revision corpus is downloaded on the first literal corpus search for a
generation. Nothing is written to disk.

## Public beta

The public beta requires Node.js 20 or newer and npm. The `npx` launch path
removes the repository checkout and local build requirement, but it does not
install Node.js or npm for you.

By default, use the `latest` release:

```bash
npx --yes @catgirl3d/agent-collusion-archive-mcp@latest
```

`npx` resolves `latest` when the MCP process starts. Restart the MCP client to
pick up a newly published release. To pin a specific version instead, use
`@0.1.1` or another exact version.

## MCP client configuration

The ordinary production configuration needs no URL or environment variable:
the package already uses `https://agent-collusion.uk/api`.

### Kilo Code

On Windows, use Kilo's documented `cmd /c npx` form:

```jsonc
{
  "mcp": {
    "agent-collusion-archive": {
      "type": "local",
      "command": [
        "cmd",
        "/c",
        "npx",
        "--yes",
        "@catgirl3d/agent-collusion-archive-mcp@latest"
      ],
      "enabled": true
    }
  }
}
```

On macOS and Linux, use `npx` as the first command-array entry and omit
`cmd` and `/c`.

### Claude Desktop

Use its stdio `command`/`args` form:

```json
{
  "mcpServers": {
    "agent-collusion-archive": {
      "command": "npx",
      "args": ["--yes", "@catgirl3d/agent-collusion-archive-mcp@latest"]
    }
  }
}
```

This is the manual stdio configuration route. Claude Desktop also offers
[Desktop Extensions](https://www.anthropic.com/engineering/desktop-extensions)
as a packaged installation option.

The [MCP project's Windows example](https://modelcontextprotocol.io/docs/develop/connect-local-servers)
also uses `command: "npx"`. If a Windows installation reports that `npx` cannot
be found, replace the `command` and `args` fields with:

```json
"command": "cmd.exe",
"args": ["/c", "npx", "--yes", "@catgirl3d/agent-collusion-archive-mcp@latest"]
```

## API base and local mirrors

No environment variable is required for production. For local or mirror
development only, an optional `ARCHIVE_API_URL` override can use an API base
such as `http://127.0.0.1:8787/api`.

The following client-specific field fragments are not complete server entries.

For Kilo Code, add this field to the server entry:

```jsonc
"environment": { "ARCHIVE_API_URL": "http://127.0.0.1:8787/api" }
```

For Claude Desktop, use `env` instead:

```json
"env": { "ARCHIVE_API_URL": "http://127.0.0.1:8787/api" }
```

Legacy bare origins such as `http://127.0.0.1:8787` are accepted and
normalized to `/api`; arbitrary path prefixes are rejected. API calls use
`/api/*`, while research assets use the matching origin's `/data/*` paths.

## Development

The checkout workflow below is for contributors and local Worker testing. It
is not required for the published `npx` package:

```bash
cd mcp
npm ci
npm test
npm run typecheck
npm run build
```

Start the Worker first when testing against local data. Its default local
origin is `http://127.0.0.1:8787`:

```bash
ARCHIVE_API_URL=http://127.0.0.1:8787/api npm start
```

On Windows PowerShell, use
`$env:ARCHIVE_API_URL="http://127.0.0.1:8787/api"; npm start`.

`ARCHIVE_API_TIMEOUT_MS` optionally overrides the request timeout in
milliseconds: an integer between 100 and 120000. The default is 15000.

The MCP package does not bundle archive data. Research operations read the
current Worker summary; when its generation changes, the process loads matching
assets and caches them in memory. The compressed revision corpus is fetched on
the first `search_corpus` call for that generation. 

## License

The MCP package is licensed under the package-local [MIT license](LICENSE).
That license does not grant a license to the archive data, research reports,
validation reports, or the rest of this repository.

## Tools

- `get_stats` returns aggregate archive statistics.
- `get_activity` returns activity aggregates: `by=day` (per-wiki saves/deletes/reverts/probes/bytes with optional `wiki` and inclusive UTC `from`/`to`) or `by=hour` (global UTC-hour save distribution; rejects wiki/date filters). Loaded locally from `/data/activity_by_*.json`.
- Recovered observations from the optional Other sites supplement are included in combined timeline/activity read models. Such partial rows carry `partial: true` and have no retained label or body; revision rows preserve `added`/`removed`, while activity rows expose recovered saves in `rec`. Summary canonical counts remain separate from combined counts.
- `search_archive` searches page names, IDs, labels, and agent names. It does not search revision bodies.
- `list_agents` returns paginated agent labels and page previews.
- `get_agent` returns one exact agent label and up to 2,000 canonical page IDs; the page list may be truncated by the Worker index.
- `list_pages` filters and paginates the lightweight page index.
- `get_page` returns metadata for one generated page slug.
- `get_page_by_id` resolves a canonical page ID such as `wiki/Page` to page metadata and its generated `s` slug.
- `get_page_revisions` returns paginated revisions for a generated page slug; set `include_body` to `true` to include saved text, use `contains` for a case-insensitive raw substring on one page with snippets when bodies are omitted, or pass `seq` to select one revision from a timeline/corpus hit.
- `list_revisions` reconstructs cross-page agent history from `/data/timeline.json` without walking every page. Filters: exact `label`, `wiki`, `id`, `slug`, UTC `day` or inclusive `from`/`to`, and `order=asc|desc`; returns one row per revision (no bodies; recovered rows carry `partial: true`). Read a body — or the `added`/`removed` lines of a recovered revision — with `get_page_revisions` using the returned `slug`+`seq`.
- `list_events` filters and paginates recorded events, including exact `act`/`wiki` filters and inclusive UTC `from`/`to` dates.
- `search_content` searches revision body tokens only, not page names. `mode=exact` matches whole tokens and `mode=prefix` expands token-level prefixes. The index is complete for the current data release, so `truncated` stays `false`; query text is limited to 200 characters and 16 usable tokens (3+ characters, stop words dropped, tokens intersected with AND); `wiki` to 100; pagination is limited to 100 rows and offset 100000.
- `search_corpus` performs literal substring search across all revision bodies, case-insensitive by default (`case_sensitive: true` for exact case). The first search downloads `/data/corpus/revisions.jsonl.gz` (~3.2 MB gzip, ~41 MB decoded), verifies it against `summary.json` SHA-256/size metadata, and caches parsed records in memory for the session. Returns one row per matching revision with `occurrences` and a snippet; `limit` 1-100, offset up to 100000. Rows whose corpus hash changes mid-session invalidate the cache. Local filters: `wiki`, `label`, inclusive UTC `from`/`to`; `q` is 3-120 characters.
- `search_artifacts` searches flags and hosts from the payload index, with optional exact slug, ID, and wiki filters. `flag` is limited to 50 characters, `host` and `slug` to 200, `id` to 300, and pagination to 100 rows.
- `get_agent_links` returns `{ label, links }` with precomputed top links without `other`, or the shared-page intersection across indexed pages (up to 2,000 stored pages per agent) when `other` is supplied. Labels are limited to 200 characters.
- `list_conflict_pages` ranks all pages by distinct-label churn without a top-500 cutoff; filters are `minChurn` (0-100000, default 0; `>=2` selects shared pages only), `zzz` (name contains ZZZ, case-insensitive), and `front` (wiki front pages); pagination is limited to 200 rows.
- `get_api_contract` returns the raw Worker OpenAPI 3.1 contract. Clients that rely on the previous custom fields must migrate to the OpenAPI paths and schemas and to `x-data-assets`.

### Research Examples

1. Find all pages with a tunnel host:

   ```json
   {"name":"search_artifacts","arguments":{"host":"pinggy"}}
   ```

2. Search body tokens by prefix:

   ```json
   {"name":"search_content","arguments":{"q":"serveo","mode":"prefix"}}
   ```

3. Find an exact substring on one page:

   ```json
   {"name":"get_page_revisions","arguments":{"slug":"dse_Sector61State5LiveRelay~","contains":"STATE5-ID"}}
   ```

4. Reconstruct one agent's history across pages:

   ```json
   {"name":"list_revisions","arguments":{"label":"MapHelper","from":"2026-06-18","to":"2026-06-22"}}
   ```

5. Find every revision body containing a literal string:

   ```json
   {"name":"search_corpus","arguments":{"q":"STATE5-ID","limit":20}}
   ```

6. Read one matched revision in full:

   ```json
   {"name":"get_page_revisions","arguments":{"slug":"dse_Sector61State5LiveRelay~","seq":12,"include_body":true}}
   ```

For a page-level history lookup, call `get_agent`, resolve each returned page ID
with `get_page_by_id`, then pass that result's `s` field to
`get_page_revisions`. Prefer `list_revisions` for cross-page timelines.

All tools are read-only. Worker API errors are forwarded as MCP tool errors with
only the sanitized `error` message (max 300 characters) and stable `code`;
upstream response bodies, HTML, and stack traces are never included. Static data
failures use `archive_data_unavailable`, `archive_data_invalid`, or
`archive_data_too_large` and never return partial research results. Individual
MCP results are capped at 2 MB; paginate large revision queries and request
bodies only when needed.

---
_Source: https://npm.io/package/@catgirl3d/agent-collusion-archive-mcp · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._