@knolo/mcp

@knolo/mcp

@knolo/mcp is a read-only MCP server forpinned Knolo V5 Knowledge Images. It exposes the same four tools as@knolo/openclaw: knolo_search, knolo_get, knolo_verify, andknolo_status. Pins, policy checks, and query receipts come from@knolo/tools. When at least one mount includes a kar block, the serveralso exposes knolo_kar_evaluate, knolo_kar_verify, andknolo_cortex_verify.

The server speaks stdio only. It does not download images, open a runtimenetwork connection, write or compile knowledge, or expose MCP resources orprompts. Install and pin each image before starting it. A hash, state-root,or policy-root mismatch exits non-zero before the MCP connection starts.Optional mount fields builtAt, sourceDigest, and sourceRoots, plusgrokHome, let knolo_status and knolo_verify report a stale source tree.Without those fields the status object stays imageId, stateRoot, source,and status. A stale source does not make a matching pin invalid.

Caller identity is agentId in the config file, default mcp. That id mustbe listed in the mount's agents array. Tool arguments cannot set it. Anoptional config sessionId is stored on the receipt instead of the MCPclient name when it is set. Otherwise the client's clientInfo.name isstored as sessionId. Neither value is used for authorization. sessionIdis captured when the process starts. One shared stdio process cannot see adifferent session id for each chat. One principal per mount is what policyevaluation sees.

knolo_search lowercases the query. A quoted phrase is one contiguous wholephrase. Unquoted OR selects any remaining term. Unquoted stopwords and termsshorter than 3 characters are dropped. A query that drops every term matchesnothing. Each kept term must appear as a whole word. match is all, any,partial, or none. Hits with more matched terms come first, then matches inthe path's final segment and the first line, then matches in the rest of thetext, then object id. The stopword list is in thebox doc. A direct EQL SEARCH string is adifferent matcher: every space-separated term is a substring, in object idorder.

Every search writes an openclaw-knolo-query-v1 receipt before it returnshits. The receipt records match, hitCount, durationMs, and the plan.hitCount is the number of allowed hits. durationMs times the query andthe policy check, not the audit write. Verify checks hitCount against thestored result and does not replay the clock. Older receipts without thosefields still verify. An unwritable auditDir returns AUDIT_UNAVAILABLE andno hits.Before each tool call, a server started from a config file stats that config,every mounted image, and any pinned KAR graph. An unchanged size andmodification time keeps the loaded image. A changed file is checked againstthe pin in that config. A match replaces the loaded image. A mount removedfrom the config is no longer served, even when its image file is still ondisk. A mismatch returns IMAGE_INVALID and does not serve the previousimage. A config file that cannot be read fails that call. agentId,sessionId, and maxHits stay at the values from process start. KAR graphsare authorized with that same startup agentId.

npm latest is @knolo/[email protected]. This tree sets server.json and the MCPserver version to 0.2.2. The published 0.2.1 tarball still reports0.2.0 in those two fields. A mount without a kar block exposesthe four tools above. A mount with a kar block also exposesknolo_kar_evaluate, knolo_kar_verify, and knolo_cortex_verify. Theregistry name in server.json is io.github.HiveForensics-AI/knolo.Published @knolo/[email protected] remains the four-tool server.

The Google ADK examples start thisserver over stdio and run one search.Python andTypeScript both use MCP. TheOpenAI Agents SDK example uses thesame server. ThePydantic AI example, theLangflow example, theDify example, and theCrewAI example use the sameserver. TheVercel AI SDK example calls the sameservice through @knolo/ai-sdk. @knolo/[email protected] is published. TheMastra example calls the same servicethrough @knolo/mastra. @knolo/[email protected] is not published yet. TheOpenAI Agents native tools callthe same service through @knolo/openai-agents.@knolo/[email protected] is not published yet. TheAnthropic Agent Skill registersthis server from a Claude Code plugin.

The stdio image is built frompackages/mcp/Dockerfile in this repository. It is not onDocker Hub. The container reads KNOLO_MCP_CONFIG, does not listen on aport, and runs as a non-root user. A bad pin exits before the server acceptsa tool call. An unwritable audit directory returns AUDIT_UNAVAILABLE andno hits. Publishing the image and opening the docker/mcp-registry pullrequest are separate steps. The draft catalog entry islistings/docker/server.yaml. The integrationnote is Docker.

Goose launches this server as a stdioextension. The draft islistings/goose/extension.yaml. Goose doesnot receive a URL. The server does not listen on a port. Submitting theextension is a separate pull request.

The awesome-mcp-servers line belongs underKnowledge & Memory. It names this package as a local TypeScript server andpins @knolo/[email protected]. There is no badge, because Knolo is not listed thereyet. Submitting the line is a separate pull request.

Config

Paths are absolute. sha256 is 64 lowercase hex characters. stateRoot issha256- plus 64 lowercase hex characters.

{
  "agentId": "mcp",
  "auditDir": "/var/lib/knolo/receipts",
  "mounts": [
    {
      "id": "handbook",
      "path": "/opt/knolo/handbook.knolo",
      "sha256": "<64 hex>",
      "stateRoot": "sha256-<64 hex>",
      "policyPath": "/opt/knolo/handbook.policy.json",
      "agents": ["mcp"],
      "principal": "<policy principal>",
      "kar": {
        "graphPath": "/opt/knolo/handbook.kar.json",
        "graphSha256": "<64 hex>"
      }
    }
  ]
}

kar is optional. graphSha256 is the raw file SHA-256, 64 lowercase hexcharacters, without a sha256- prefix. The server hashes that file and bindsit to the mount before it accepts a connection. A hash or binding mismatchexits before MCP starts. A call for a mount that has no kar block failsclosed when the three tools are enabled by another mount.

knolo_kar_evaluate takes mountId, proposition, and an inline planobject of at most 65536 UTF-8 bytes. SATISFIED means evidence requirementswere met. It does not mean a claim is proven.UNSATISFIED_EVIDENCE_REQUIREMENTS is a completed evaluation. The plan isparsed by the KAR plan parser. Domain Pack template names are not accepted.

knolo_kar_verify takes the same mount, proposition, and plan, plus exactlyone of result or dossier. knolo_cortex_verify takes mountId, ananswer trace, and an optional question. It uses the pinned graph when thetrace references KAR. These tools do not call a model and do not runaskCortex.

Query receipts stay openclaw-knolo-query-v1. KAR and Cortex tools writeknolo-mcp-evidence-receipt-v1 in auditDir before they return a result. Anunwritable audit directory returns AUDIT_UNAVAILABLE and no result.

Start it with knolo-mcp --config /absolute/knolo-mcp.json orKNOLO_MCP_CONFIG. Logs go to stderr. Stdout is JSON-RPC only.

Clients

Claude Desktop, Claude Code, and Cursor:

{
  "mcpServers": {
    "knolo": {
      "command": "npx",
      "args": ["-y", "@knolo/mcp", "--config", "/absolute/knolo-mcp.json"]
    }
  }
}

Claude Code CLI:

claude mcp add knolo -- npx -y @knolo/mcp --config /absolute/knolo-mcp.json

VS Code (.vscode/mcp.json):

{
  "servers": {
    "knolo": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@knolo/mcp",
        "--config",
        "${workspaceFolder}/knolo-mcp.json"
      ]
    }
  }
}

Cline uses the same stdio server. The file hash, knolo verify, and theCline settings block are in llms-install.md. The publishedserver pin is @knolo/[email protected]. The CLI pin for stateRoot is@knolo/[email protected]. Pins, the policy file, and the audit directory stay inthe config.

{
  "mcpServers": {
    "knolo": {
      "command": "npx",
      "args": ["-y", "@knolo/[email protected]", "--config", "/absolute/knolo-mcp.json"]
    }
  }
}

The 400×400 listing logo islogo.png.The marketplacesubmission iscline/mcp-marketplace#3696.

The package requires Node 20 or newer, @knolo/core ^6.2.1, and@knolo/tools ^0.2.1. Coverage, composition, and authoring stay outsidethis server. Verification checks integrity. It does not decide that a claimor an answer is true.