# OpenArchiver MCP Server

An MCP (Model Context Protocol) server for searching and administering an OpenArchiver instance.

## Toolsets

Set `OPENARCHIVER_TOOLSET` to choose which tools MCP clients can discover. The default is `core`.

### Core

Core is read-only and intended for everyday archive access:

- `search_emails` — search email text and structured fields.
- `get_email` — retrieve one archived email with decoded MIME text/HTML, attachment metadata, and thread details. Set `includeRaw: true` to also return the original API raw payload.
- `get_archive_stats` — return dashboard and per-source statistics together.
- `get_archive_health` — return global index health and optional per-source health.
- `list_ingestion_sources` — list accessible sources.
- `list_archived_emails_for_source` — browse a source with pagination.
- `search_attachments` — find a specific attachment by filename or indexed attachment text, with optional extension filtering.
- `download_attachment` — retrieve attachment bytes inline or save them to a local file, using the email and filename returned by `search_attachments`.

### Full

Full includes every core tool plus administrative tools:

- `list_users`, `get_user`, `create_user`, `update_user`, `delete_user` — user management.
- `list_roles` — discover IAM role IDs for user assignment.
- `reindex_archive` — reindex the entire archive or one source in `missing` or `full` mode.
- `get_queues` — inspect background queue counts.

In full mode, `get_archive_health` also requests the Super-Admin search-engine overview. Health sections are returned independently, so a permission failure in one section does not discard the others.

The API does not currently expose audit-log, retention-policy, retention-label, or legal-hold routes, so this MCP does not advertise nonfunctional tools for those features.

## Requirements

- Node.js 18 or newer
- A reachable OpenArchiver instance
- An OpenArchiver API key with permissions appropriate for the selected tools

Typical permissions include `search:archive` and `read:archive` for core access, `read:dashboard` and `read:ingestion` for statistics and health, `manage:all` for users, roles, queues, and index overview, `manage:ingestion` for a global reindex, and `sync:ingestion` for a source reindex.

## Installation

```bash
npm install
npm run build
npm test
```

Run the package directly with `npx` from GitHub Packages:

```bash
npx --yes --registry=https://npm.pkg.github.com --package=@imrasalghul/openarchiver-mcp@1.0.2 openarchiver-mcp
```

For GitHub Packages authentication, create a GitHub personal access token with `read:packages` (installation) or `write:packages` (publishing), then configure npm:

```bash
npm login --registry=https://npm.pkg.github.com --scope=@imrasalghul
```

## Configuration

- `OPENARCHIVER_API_KEY` — required API key.
- `OPENARCHIVER_API_URL` — required instance base URL, e.g. `https://archiver.example.com`; no default host.
- `OPENARCHIVER_TOOLSET` — `core` or `full`; defaults to `core`. Invalid values stop startup with an error.
- `OPENARCHIVER_TIMEOUT_MS` — positive request timeout in milliseconds; defaults to `30000`.

Example MCP configuration:

```json
{
  "mcpServers": {
    "openarchiver": {
      "command": "npx",
      "args": [
        "--yes",
        "--registry=https://npm.pkg.github.com",
        "--package=@imrasalghul/openarchiver-mcp@1.0.2",
        "openarchiver-mcp"
      ],
      "env": {
        "OPENARCHIVER_API_KEY": "your-api-key",
        "OPENARCHIVER_API_URL": "https://archiver.example.com",
        "OPENARCHIVER_TOOLSET": "core",
        "OPENARCHIVER_TIMEOUT_MS": "30000"
      }
    }
  }
}
```

Use `"OPENARCHIVER_TOOLSET": "full"` only for API keys intended to perform administrative operations.

The package is published to GitHub Packages, not npmjs.org.

## Development

```bash
npm run build
npm test
npm run check
```

The tests start a local mock API and verify MCP discovery, tool annotations, input validation, reindex routing, partial health responses, and successful handling of `204 No Content` deletions. They do not modify a live OpenArchiver instance.

## Email response format

OpenArchiver returns raw MIME as a serialized Node Buffer. `get_email` decodes it locally and returns a `parsed` object containing `text`, `html`, addresses, message headers, and attachment metadata (`filename`, MIME type, size, and SHA-256). Existing archive metadata and thread details are retained. Attachment bytes and the large raw byte array are omitted by default. `includeRaw: true` retains the original API payload alongside the decoded result.

HTML is returned as data and is not sanitized for browser rendering. MIME parsing uses [MailParser](https://nodemailer.com/extras/mailparser), including charset and transfer-encoding decoding. Parsing buffers the message and attachments in memory; very large messages require corresponding available memory.

## Live API validation

The live suite is separate from the mock tests and requires both an explicit target and API key. It prints check names and timings, without email contents, account details, passwords, or credentials. Use an environment variable or your secret manager for the API key.

```bash
export OPENARCHIVER_API_URL=https://archiver.example.com
read -rsp 'OpenArchiver API key: ' OPENARCHIVER_API_KEY
export OPENARCHIVER_API_KEY
npm run test:live
```

The read-only suite checks core/full discovery, authentication, every read tool, MIME decoding, attachment metadata, search filters/scopes/strategies/sorting, pagination, and missing-resource errors. It needs a populated archive and an administrative API key for full coverage.

Explicitly enable live writes when testing administrative operations:

```bash
npm run test:live -- --mutations --reindex-missing
```

`--mutations` creates one uniquely named temporary user with the `end_user` role, verifies changes, then deletes it and verifies absence in a `finally` block. It never changes existing users. `--reindex-missing` exercises both source and global missing-only reindex requests. `--reindex-full` additionally rebuilds both scopes and waits for indexing completion between requests. These operations create audit records and queue history. `OPENARCHIVER_TEST_REPORT` optionally names a JSON report file; it contains only test metadata.

Package creation runs the TypeScript build automatically (`npm pack`). The package includes the compiled modules and README, and the CLI has a Node interpreter line for Unix systems.