The five tools
| Tool | What it does |
|---|---|
| knobe_verify | Integrity and conformance verdict for a file or pasted text: the protocol's four states, a separate conformance axis with each issue listed, both hashes, and lens.py's exit code. |
| knobe_read | An obligations-first read: the first content block is the sealed-context preamble (integrity verdict, provenance, license, trust posture, obligations), so an agent reads the conditions before the content. The second block carries the payload metadata and markdown body. |
| knobe_create | Assemble and seal a new object from fields and a body. The sealed file self-verifies before it is returned, and can be written to a path. |
| knobe_transform | Seal a derivative of a verified original. The derivative's parents field records the original's title and payload hash automatically; a broken seal cannot anchor a chain. |
| knobe_permits | Evaluate a proposed action (summarize, excerpt, translate, train, redistribute, publish, ...) against the object's own sealed terms. |
Resources and a prompt
The 31-fixture corpus ships with the package and is browsable as MCP resources: knobe://examples/… (sealed real-world KNOBEs), knobe://vectors/… (conformance and adversarial vectors with known verdicts), and knobe://guide (orientation for agents). A knobe-guarded-summarize prompt encodes the basic procedure: verify, consult the sealed terms, then act, qualify, or decline with a cited clause.
What knobe_permits returns
The evaluation reads the sealed record itself: quarantine status, privacy level, license posture, and any namespaced extension terms the author declared. The verdict is true, false, or "conditional", with the obligations that apply and a basis list citing each sealed field that produced it:
{
"action": "redistribute",
"allowed": false,
"obligations": ["quarantined: inspect and establish trust before relying on the content"],
"basis": [
{ "field": "privacy_level", "value": "sensitive", "effect": "deny distribution actions" },
{ "field": "license", "value": "All rights reserved", "effect": "no redistribution granted" }
],
"integrity": { "state": "verified", "conformance": "valid" }
}
An agent that consults this before acting can decline with a quoted source rather than a guess. Two boundaries hold throughout: a file whose seal fails verification permits nothing, and the verdict reports what the object declares. Enforcement belongs to the caller; a verified seal confirms integrity, not truth.
Install
From a checkout of the repository (the server lives in mcp/; run npm install there once):
{
"mcpServers": {
"knobe": {
"command": "node",
"args": ["/absolute/path/to/knobe-protocol/mcp/server.mjs"]
}
}
}
- Claude Desktop: add the block to
claude_desktop_config.json(Settings → Developer → Edit Config). - Claude Code:
claude mcp add knobe -- node /absolute/path/to/knobe-protocol/mcp/server.mjs - Cursor / Windsurf / others: add the same server block to the client's MCP configuration file.
Requires Node 20 or later. Once the package is published to npm as knobe-mcp, the command becomes npx -y knobe-mcp with no checkout needed.
Data flow and verification
Files are read from the paths you pass (or from pasted text), processed in the server process, and optionally written to a path you name. Nothing is transmitted anywhere; the server has no network code.
The engine is knobe-core.js, the dependency-free ES module whose verdicts are checked against lens.py across the published test corpus; the parity claim and its command are on the implementations page. The package's own test suite drives every tool through a full MCP client/server round-trip and byte-compares the vendored engine against the repository copy. Where any implementation disagrees with lens.py, lens.py is right.