clideck-mcp

# CliDeck MCP

## Verifiable external memory for AI agents

CliDeck MCP is an open-source framework for building verified, continuously
updated knowledge systems that AI agents can access through MCP.

> **Built with Codex and GPT-5.6.** Codex was the primary engineering
> environment for the project, while GPT-5.6 Luna powers its asynchronous
> knowledge-growth pipeline. Published answers remain deterministic and do not
> call a model at read time.

A model should not have to memorize every version of every technical manual.
It needs strong fundamentals, reasoning ability, and the ability to use tools.
Exact, specialized, and rapidly changing facts can live in an external
knowledge system and be updated without retraining the model.

CliDeck MCP implements this architecture:

- known questions are answered deterministically, without calling an AI model;
- unknown questions become high-priority learning tasks;
- Codex and GPT-5.6 discover and analyze official documentation;
- independent validation passes check applicability and quality;
- new knowledge is published as immutable revisions;
- published knowledge is immediately reusable without AI.

**Network Knowledge** is the first production Domain Pack. **Engineering
Measurements** demonstrates that the same core can support other technical and
scientific domains.

- Public MCP: `https://mcp.clideck.com/mcp`
- Live read-only demo: `https://mcp.clideck.com/demo`
- WebMCP Network Change Room: `https://mcp.clideck.com/webmcp`
- Product page: `https://clideck.com/software/mcp`
- Code license: Apache-2.0

## The WebMCP Challenge extension

CliDeck MCP existed before The WebMCP Challenge. The immutable knowledge
system, public MCP endpoint, version-aware network tools, change review,
snapshot redaction, signed verification, continuous research pipeline, and
operations console are pre-existing capabilities.

The **Network Evidence Workbench** was added after August 25, 2026 specifically
for the challenge. It gives a person and a browser agent the same live,
revision-safe workspace for examining real device output and finding sourced
answers in CliDeck.

### What is new

- a separate public `/webmcp` experience that leaves `/admin` and `/demo`
  unchanged;
- six stable browser-native WebMCP tools for reading the current case,
  detecting context, searching knowledge/workflows, presenting agent analysis,
  and tracking additional research;
- local text and text-layer PDF extraction with visible page/line selection,
  explicit limits, and secret redaction before any network request;
- a monotonic `case_version` and abort propagation so a late response can never
  overwrite a case the user has changed;
- active-revision provenance beside official CliDeck results and a visually
  separate browser-agent interpretation;
- ordinary buttons for every primary action, so the product remains useful in
  browsers without WebMCP.

### Judge walkthrough

1. Open `https://mcp.clideck.com/webmcp` in ChatGPT's in-app browser, or in
   Chrome 149+ with `chrome://flags/#enable-webmcp-testing` enabled.
2. Load the labelled Cisco Catalyst 9300 IOS XE 16.10 sample, analyze it, and
   search for the applicable upgrade procedure.
3. Enable **Share redacted evidence with browser agent** and ask the agent to
   explain the current sourced result.
4. Replace the sample with IOS XE 17.8.1. Observe the new context and
   `case_version`, then search again for the EFSU-capable path.
5. Upload a text-layer PDF or LOG, select the relevant page/line window, and
   repeat the flow.
6. Ask a genuinely unknown question and start a real tracked research task.

The page never connects to a device and never executes a command. Complete
files stay in browser memory. Only the selected, locally redacted window is
sent to CliDeck; browser-agent access requires one explicit opt-in. IP, MAC,
hostname, and username values are intentionally preserved as diagnostic
context and disclosed in the interface.

## Why this project exists

A general-purpose model may understand networking fundamentals while still
having outdated or incomplete knowledge about exact commands, operating-system
versions, restrictions, and operational procedures. Reading hundreds of
manuals during training does not guarantee a precise answer for a particular
device and software release.

CliDeck MCP separates responsibilities:

- the model understands the question, reasons, and selects the appropriate
  tool;
- MCP stores exact, structured, and version-aware knowledge;
- a Domain Pack enforces the rules of its subject area;
- the core manages publication, history, trust, conflicts, and rollback.

This architecture may reduce the need to encode every version of specialized
documentation directly into model weights. We do not claim proven pretraining
cost reductions; that would require separate experiments. The practical
benefit already exists: exact knowledge can be validated and updated
independently of the model.

## What makes CliDeck MCP different

### Deterministic answers

A known question does not invoke an LLM. PostgreSQL performs version-aware
retrieval, the Domain Pack validates the result, and MCP returns a structured
answer.

Known answers are therefore:

- fast;
- repeatable;
- inexpensive;
- verifiable;
- independent of model-generation variance.

If applicable knowledge is unavailable, the system returns `unknown` instead
of guessing.

### Learning from unknown questions

An unknown question becomes a maximum-priority knowledge demand:

```text
Unknown question
      ↓
Official-source discovery
      ↓
Download and deterministic conversion
      ↓
Chunking and extraction
      ↓
Independent verification and Deep Review
      ↓
Immutable publication
      ↓
Instant deterministic reuse
```

A demand is considered learned only after the same deterministic query finds
an active published revision.

### A continuously running Codex knowledge factory

The pipeline runs continuously while enabled. Mechanical stages do not consume
AI tokens:

- downloading;
- PDF, HTML, and text conversion;
- OCR;
- chunking;
- hashing;
- indexing;
- publication.

GPT-5.6 Luna runs through isolated, ephemeral Codex sessions and is used only
for work that requires semantic reasoning:

- discovering official sources;
- analyzing ambiguous material;
- independent verification;
- Deep Review;
- expert tasks.

Up to eight isolated executors lease work atomically. The pipeline can be paused
and resumed without duplicating tasks or published knowledge. Routine
discovery, analysis, verification, and Deep Review use GPT-5.6 Luna with low
reasoning effort. Medium reasoning is reserved for unresolved Deep Review
cases, rather than being spent on every record.

### No separate model API integration required

The pipeline can run through an existing authenticated local Codex
installation.

> Runs through your existing local Codex setup. No separate model API
> integration is required. Subject to your Codex plan and usage limits.

This allows developers to use available capacity in their Codex plan to grow a
private or public knowledge system without first integrating and funding a
separate model API.

This is an operating option, not a promise of free or unlimited usage.

## How Codex and GPT-5.6 were used

Codex was not added at the end as a code-generation demo. It was the primary
engineering workspace and collaborator throughout the project, from the first
architecture decisions to the running production system.

During development, Codex and GPT-5.6 were used to:

- translate product goals into the MCP, worker, researcher, and admin
  architecture;
- define trust boundaries, immutable revision contracts, release rollback, and
  privacy controls;
- implement the TypeScript services, PostgreSQL migrations, Domain Pack SDK,
  scaffolder, and local operations dashboard;
- design and test the continuous multi-executor pipeline;
- build security tests, deterministic evaluations, browser tests, and
  production smoke checks;
- inspect real pipeline telemetry and correct throughput, reliability, and
  data-conservation defects;
- create the canonical backup, migration, deployment, health-check, and
  rollback workflow.

Codex and GPT-5.6 are also part of the product's operation:

1. A known question is answered by deterministic PostgreSQL retrieval and
   Domain Pack validation, with no model call.
2. An unknown question creates a prioritized learning demand.
3. Isolated Codex executions pinned to GPT-5.6 Luna
   (`gpt-5.6-luna`) discover official material, analyze ambiguous fragments,
   verify candidates, and perform Deep Review.
4. The core—not the model—enforces schemas, applicability, risk, conflicts,
   provenance, confidence, and immutable publication.
5. Once published, the new answer becomes instantly reusable without another
   GPT-5.6 call.

This separation is deliberate: **Codex and GPT-5.6 propose and review new
knowledge; the deterministic core decides what is allowed to become active
knowledge.** CliDeck MCP is therefore not a wrapper that asks an LLM a question
and trusts whatever text comes back.

### Universal Domain Packs

CliDeck MCP is not limited to network equipment. Subject-specific behavior
lives in Domain Packs.

The core owns:

- immutable revisions;
- releases and rollback;
- provenance;
- confidence thresholds;
- conflict handling;
- audit;
- publication policy.

A Domain Pack defines:

- domain context;
- record types;
- data schemas;
- normalization;
- deterministic validation;
- mapping into a universal knowledge revision.

Developers can scaffold their own pack:

```bash
pnpm domain:create -- --id marine-science --name "Marine Science"
pnpm domain:validate -- --id marine-science
```

The scaffolder creates a manifest, schemas, mapper, fixtures, and tests. Codex
and GPT-5.6 can help adapt a fork to a new subject without rewriting the
trusted publication and release core.

Optional providers can add object storage, spatial data, relation