CliDeck MCP — Network Knowledge

Built with Codex and powered by GPT-5.6, CliDeck MCP turns trusted sources and unanswered questions into verified, continuously updated knowledge any AI agent can reuse.

Comment

The problem

General-purpose AI models can understand a technical domain while still being unreliable on exact commands, product versions, limitations, tolerances, and operational procedures. Reading hundreds of manuals during training does not guarantee a precise answer for a specific device and software release, and retraining a model every time documentation changes is not practical.

CliDeck MCP explores a different architecture: the model keeps the fundamentals, reasoning ability, and tool-use skills, while exact and rapidly changing knowledge lives in a verified external system that can be updated independently.

I do not claim that this project has already proven lower pretraining costs; that would require separate experiments. The working result demonstrates the practical benefit: exact knowledge can be validated, versioned, updated, and reused without putting an LLM in every answer path.

What I built

CliDeck MCP is an open-source, agent-native framework for verified, continuously updated MCP knowledge systems.

Known questions are answered deterministically from active, version-aware knowledge. Unknown questions become maximum-priority learning demands and move through a continuous pipeline:

unknown question
      → official-source discovery
      → deterministic download, conversion, OCR, and chunking
      → Luna analysis
      → 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. Discovery or an AI-generated candidate alone is not counted as success.

The production instance currently contains more than 66,000 active knowledge revisions. Recent production telemetry shows that more than 99% of completed answers use the deterministic no-AI path. The public product eval contains 250 scenarios and currently passes 250/250 with zero dangerous false-safe outcomes.

Why it is different

Most retrieval systems either place an LLM in every response path or require a custom ingestion application for every subject. CliDeck MCP separates a stable knowledge core from subject-specific Domain Packs.

The core owns:

  • immutable revisions and atomic releases;
  • rollback and active knowledge state;
  • provenance and confidence thresholds;
  • conflict detection and audit;
  • task leases, retries, and publication policy.

A Domain Pack defines:

  • its context dimensions;
  • record and payload schemas;
  • normalization and deterministic validation;
  • mapping into a universal knowledge revision.

Network Knowledge is the first production Domain Pack. Engineering Measurements is a small project-authored proof pack with exact decimal values, normalized units, tolerances, procedures, and conversions. It proves that the architecture is not a network database disguised as a universal framework.

A developer can scaffold another pack and adapt a fork with Codex without rewriting the immutable release and trust core.

Network Knowledge

The production Network Pack stores explicit vendor, product family, model, operating system, version scope, CLI mode, risks, prerequisites, verification, rollback, limitations, and conflicts.

The public server exposes 16 MCP tools across the Network and generic Domain Pack interfaces. They support:

  • device-context resolution;
  • command, diagnostic, and workflow retrieval;
  • expert research tasks;
  • CLI snapshot fingerprinting and in-memory redaction;
  • planned-change review;
  • reusable short verification handles and post-change verification;
  • upgrade guidance;
  • CDP, LLDP, route, traceroute, and topology/path analysis;
  • feedback and explicitly consented, re-redacted examples;
  • listing, describing, and querying arbitrary registered Domain Packs.

Dangerous commands are not hidden. The system returns the available information while clearly explaining risks, prerequisites, verification, and rollback. CliDeck MCP provides guidance but never connects to a device and never executes a command.

Deep verified coverage is currently concentrated on Cisco Catalyst and IOS-XE. Junos and Arista EOS device detection is available, but their knowledge coverage is limited. Unsupported cases return an explicit limitation or unknown instead of an invented answer.

Continuous Codex-powered learning

The pipeline can run through an existing authenticated local Codex installation. No separate model API integration is required. Usage remains subject to the operator's Codex plan and usage limits; this is not a promise of free or unlimited processing.

Mechanical work does not consume AI tokens:

  • downloading public documents;
  • PDF, HTML, and text conversion;
  • local OCR;
  • chunking and hashing;
  • indexing and publication.

Luna is reserved for semantic work: official-source discovery, ambiguous extraction, verification, Deep Review, and expert tasks. Up to four isolated executors atomically lease useful work. The pipeline can be paused and resumed without duplicating tasks or published revisions.

This makes it possible to use spare capacity in an existing Codex plan to grow a private or public knowledge system instead of first wiring and funding a separate model API.

Product experience and truthful demo

The project includes a complete operations console rather than only backend endpoints. It shows live publications, source intake, record flow, active Luna executors, coverage, knowledge, requests, releases, conflicts, quality, provenance, and pipeline health.

The public demo is not a mock or a separately designed marketing dashboard. /admin and /demo use the same compiled React application, the same 18 pages, components, charts, tables, filters, tooltips, and confirmation dialogs.

The public_demo role reads real production data but cannot mutate the system. Source identity and private values are removed server-side and replaced with XXXXXXXX; they are not merely blurred with CSS.

Verification, privacy, and safety

Every published revision passes Domain Pack validation, applicability and version checks, deterministic risk classification, conflict detection, confidence and quality thresholds, and internal provenance validation. An official vendor document is sufficient evidence when a specific fragment directly supports the claim.

Published revisions are immutable. Updates create new revisions, and active knowledge can be switched or rolled back atomically.

Public responses never expose source URLs, manual titles, evidence fragments, internal source IDs, credentials, or acquisition-pipeline details. Raw CLI is processed in memory. Opted-in examples are redacted again, isolated, expire automatically, and are never published automatically.

Architecture

  • Node.js 24, TypeScript, Hono, Zod 4, and MCP TypeScript SDK;
  • PostgreSQL 16 with full-text search and pg_trgm;
  • separate API, mechanical worker, restricted researcher, and LAN admin processes;
  • continuous isolated Codex/Luna executors with PostgreSQL leases;
  • immutable delta releases, checkpoints, and atomic rollback;
  • systemd services behind a Cloudflare Tunnel;
  • LAN-only administrative authentication and a public read-only demo.

PostgreSQL is the only required stateful dependency. Redis, a vector database, and an external model API are not required.

How I used Codex

Codex was the primary engineering collaborator throughout the project. I used it to:

  • turn the initial idea into threat boundaries and immutable contracts;
  • implement the MCP server, API, worker, researcher, scheduler, and admin console;
  • build the Domain Pack abstraction and scaffolder;
  • migrate and reconcile the production knowledge database;
  • design deterministic risk, version, conflict, and publication gates;
  • implement the continuous unknown-to-knowledge learning loop;
  • create PostgreSQL integration, security, browser, and product-eval suites;
  • diagnose production bottlenecks and improve batching, retries, publication, and observability;
  • build one canonical backup, migration, deployment, smoke-test, and rollback workflow.

Codex was not used only to generate code. It helped repeatedly inspect the running production system, compare intended behavior with real metrics, find incorrect assumptions, and iterate on the architecture.

Try it

Any compatible Streamable HTTP MCP client can connect to the public endpoint. The project is not limited to CliDeck or Codex clients.

The repository is Apache-2.0 for source code and project-authored fixtures. Production knowledge, third-party documents, private manuals, and operator-imported datasets are not distributed with the repository.

Built With

  • batfish
  • cloudflare-tunnel
  • codex
  • containerlab
  • github-actions
  • gpt-5.6
  • hono
  • mcp-typescript-sdk
  • model-context-protocol
  • node.js-24
  • pnpm
  • postgresql-16
  • systemd
  • typescript
  • zod
Share this project:

Updates