knobe-mcp-server

MCP (Model Context Protocol) server for sealing, verifying, and reading KNOBE Protocol v1 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.

Related MCP server: hive-mcp-origin

Quick start

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

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

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

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

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. Includes the KNOBE Protocol v1 engine (src/engine/knobe-core.js), © knobe.org, also Apache-2.0.