# knobe-mcp-server

MCP ([Model Context Protocol](https://modelcontextprotocol.io)) server for
sealing, verifying, and reading **[KNOBE Protocol v1](https://knobe.org)**
documents — with **human-confirmed authorship on every seal**.

KNOBE documents are ordinary markdown files carrying a cryptographically
sealed payload: title, attribution, license, privacy level, lineage, and a
hash of the body. Anyone can later verify that the document is intact, who
sealed it, and what its governance fields permit. This server lets AI agents
do the sealing and verifying — without ever letting an agent silently decide
who the author is.

## Why

Document-conversion pipelines (Pandoc, LibreOffice, OCR tools, …) produce
files with no provenance. Drop this server at the end of the pipeline and
every converted document comes out as a `.knobe.md` whose origin, author, and
integrity are verifiable — by a person, a CI job, or another agent. Works for
individuals sealing their own writing and for organizations sealing official
documents under the org's name.

## Quick start

```bash
git clone https://github.com/KnobeDev/knobe-mcp.git
cd knobe-mcp
npm install        # auto-builds dist/ via the prepare script
npm test           # vitest unit suite
```

Register with your MCP client (example: Claude Code / Claude Desktop):

```json
{
  "mcpServers": {
    "knobe": {
      "command": "node",
      "args": ["/absolute/path/to/knobe-mcp/dist/index.js"],
      "env": {
        "KNOBE_ROOT": "/path/to/your/documents",
        "KNOBE_DEFAULT_AUTHOR": "Your Organization"
      }
    }
  }
}
```

Then ask your agent things like:

> Convert report.docx to markdown, then seal it as a KNOBE document.
> Verify everything in ./inbox and tell me what failed.
> Seal these 40 converted files with the company as author.

## Tools

| Tool | Kind | Purpose |
|---|---|---|
| `knobe_seal_file` | write | Seal an existing file's content into a `.knobe.md` document |
| `knobe_seal_text` | write | Seal a text body passed in the call (in-memory pipeline output) |
| `knobe_seal_batch` | write | Seal up to 200 files; author confirmed once per batch (or per file with `confirm_each`) |
| `knobe_verify` | read-only | Integrity + conformance report; optional `action` evaluates sealed governance (`permits`) |
| `knobe_read` | read-only | Report + sealed payload + body preview |

Integrity states reported by `knobe_verify` / `knobe_read`:
**verified** · **verified-body-modified** (seal intact, body changed) ·
**failed** (hash mismatch) · **unreadable**.

## The author prompt (human-in-the-loop)

Sealing attributes authorship, so it is never silent:

1. If the connected client supports **MCP elicitation**, the user is prompted
   to confirm or change the author before each seal (batch = one prompt). The
   agent's `author` parameter and `KNOBE_DEFAULT_AUTHOR` are only *proposals*
   pre-filled into the prompt. Decline/cancel aborts the seal — nothing is
   written.
2. If the client cannot elicit, the explicit `author` parameter or
   `KNOBE_DEFAULT_AUTHOR` is used as-is; with neither, the seal fails with an
   actionable error.
3. `KNOBE_NO_CONFIRM=1` skips the prompt when an author is already known —
   for trusted, headless batch pipelines only.

This design means a prompt-injected or misbehaving agent cannot fabricate
attribution: the human either confirmed the author or explicitly configured
the pipeline to run unattended.

## Environment

| Variable | Effect |
|---|---|
| `KNOBE_ROOT` | Confine every read/write to this directory (recommended). Checked both lexically and via symlink resolution — a symlink inside the root pointing outside it is rejected. |
| `KNOBE_DEFAULT_AUTHOR` | Fallback/proposed author, e.g. your organization name |
| `KNOBE_NO_CONFIRM` | `1`/`true` skips the per-seal author prompt |

## Behavior notes

- Output defaults to `<source>.knobe.md` (`report.md` → `report.knobe.md`);
  existing files are never overwritten unless `overwrite=true` (atomic
  exclusive-create, no check-then-write race).
- Size limits: 16 MB per file read, 2,000,000 characters for `knobe_seal_text`
  bodies, 200 files per batch.
- If the user declines an author prompt mid-batch (`confirm_each=true`), the
  batch stops; already-sealed files stay on disk and are reported with
  `aborted: true`.
- Freshly sealed documents carry the protocol default
  `quarantine_status: "quarantine"`, so `knobe_verify` with
  `action: "redistribute"` correctly reports **not permitted** until the
  document's governance fields say otherwise — that is KNOBE working as
  designed.
- Everything inside a KNOBE document (body, payload) is untrusted content;
  `knobe_read` returns it as data, not instructions.

## Development

```bash
npm run build   # tsc + copies the vendored engine into dist/
npm test        # 31 vitest unit tests
npm run dev     # run from source via tsx
```

Layout: pure logic in `src/seal-core.ts` / `src/author.ts` / `src/files.ts`
(unit-tested, no SDK imports at runtime), thin MCP tool layer in
`src/tools.ts`, entry point `src/index.ts`.

The sealing engine `src/engine/knobe-core.js` is vendored **verbatim** from
<https://knobe.org/knobe-core.js> — the official KNOBE Protocol v1 reference
engine. Do not modify it; to update, re-download from the live site and rerun
the tests.

## License

[Apache-2.0](LICENSE). Includes the KNOBE Protocol v1 engine
(`src/engine/knobe-core.js`), © knobe.org, also Apache-2.0.