kcp-agent — KCP navigation planner MCP server

kcp-agent

🧾 See it run — interactive KCP playground · read the reveal

The reference agent for the Knowledge Context Protocol.

The Arena → — the real planner, bundled unmodified,

running live in your browser, head-to-head against the usual suspects. *The most deterministic

agents in the world. Every decision defensible.*

KCP defines how knowledge declares itself so agents can navigate it. kcp-agent is the other half: the agent that consumes KCP end to end. Given a task and a knowledge.yaml, it produces an inspectable load plan — which units to load and in what order, which to skip and exactly why, how it selects sub-manifests across a federation, and what the whole thing costs — and then, optionally, answers the task from only those units.

The valuable, novel core is LLM-free and deterministic. The plan is an audit-before-action artifact — the trusted-render principle ("a manifest may influence what an agent knows, never what it does") extended to the whole agent loop. Only the final synthesis step calls a model.

discover → verify signature → trust-gate → score units by task → federate (context + agent_identity)
        → temporal filter → budget (payment + rate_limits) → emit load plan → [follow] → [answer]

Install

npm install
npm run build

Native executables

CI cross-compiles self-contained binaries (no Node/Deno required on the target) for Linux x64/arm64, macOS x64/arm64, and Windows x64 — grab them from a release or from the kcp-agent-natives artifact on any CI run. To build one yourself:

npm ci && npm run build
deno compile --allow-read --allow-env --allow-net --node-modules-dir=auto \
  --output kcp-agent dist/cli.js

Use

plan — the inspectable load plan (no API key)

node dist/cli.js plan "how do I deploy to production?" --manifest ./path/to/knowledge.yaml --env prod

Plan for: "how do I deploy to production?"
  companyx-knowledge-hub v1.0.0 · kcp 0.24 · env prod

Trust: · no manifest attestation requirement

Load plan (2 units):
  ● 1. front-door (score 4)  overview.md  free
  ● 2. deploy-guide (score 3) docs/deploy.md  free

Budget: tier default
Federation:
  → platform-engineering  needs github_pat before fetch  [acquire github_pat]
  · platform-engineering-dev  context ["dev","test"] excludes env 'prod'
Skipped (2):
  · auth-guide: no task-relevance match

Each stage maps onto a layer of the spec: query scoring (§15), temporal validity (§4.22), agent attestation (§3.2), federation context + agentidentity (§3.6), and payment / rate-limits (§4.14/§4.15). A restricted unit the agent can't attest for is listed but marked not load-eligible** — fail-closed, with the reason attached.

Budgeting the context window. Tokens are the actually-scarce resource when feeding a model, so --context-budget names it — a token ceiling that works exactly like the money --budget: greedy by score, and a unit that would blow the ceiling is skipped with the arithmetic in the reason (over context budget: 1,240 tokens would exceed remaining 800 of 4,000), while a smaller lower-scored unit still gets its chance. Since the planner works on metadata before fetching (audit-before-action), a unit's size comes from a declared sizetokens (faithful) or bytes/4 (a flagged estimate); a unit that declares neither is admitted but counted unmeasured** (the projection is a lower bound) — unless --strict, which excludes it fail-closed. --context-budget composes with --budget: a unit must fit both ceilings.

Machine-readable plans

Use --json when another agent or integration consumes a plan. The output preserves the plan fields at the top level and adds:

Shortened. The full README is on GitHub.