{
  "markdown": "# CliDeck MCP\n\n## Verifiable external memory for AI agents\n\nCliDeck MCP is an open-source framework for building verified, continuously\nupdated knowledge systems that AI agents can access through MCP.\n\n> **Built with Codex and GPT-5.6.** Codex was the primary engineering\n> environment for the project, while GPT-5.6 Luna powers its asynchronous\n> knowledge-growth pipeline. Published answers remain deterministic and do not\n> call a model at read time.\n\nA model should not have to memorize every version of every technical manual.\nIt needs strong fundamentals, reasoning ability, and the ability to use tools.\nExact, specialized, and rapidly changing facts can live in an external\nknowledge system and be updated without retraining the model.\n\nCliDeck MCP implements this architecture:\n\n- known questions are answered deterministically, without calling an AI model;\n- unknown questions become high-priority learning tasks;\n- Codex and GPT-5.6 discover and analyze official documentation;\n- independent validation passes check applicability and quality;\n- new knowledge is published as immutable revisions;\n- published knowledge is immediately reusable without AI.\n\n**Network Knowledge** is the first production Domain Pack. **Engineering\nMeasurements** demonstrates that the same core can support other technical and\nscientific domains.\n\n- Public MCP: `https://mcp.clideck.com/mcp`\n- Live read-only demo: `https://mcp.clideck.com/demo`\n- WebMCP Network Change Room: `https://mcp.clideck.com/webmcp`\n- Product page: `https://clideck.com/software/mcp`\n- Code license: Apache-2.0\n\n## The WebMCP Challenge extension\n\nCliDeck MCP existed before The WebMCP Challenge. The immutable knowledge\nsystem, public MCP endpoint, version-aware network tools, change review,\nsnapshot redaction, signed verification, continuous research pipeline, and\noperations console are pre-existing capabilities.\n\nThe **Network Evidence Workbench** was added after August 25, 2026 specifically\nfor the challenge. It gives a person and a browser agent the same live,\nrevision-safe workspace for examining real device output and finding sourced\nanswers in CliDeck.\n\n### What is new\n\n- a separate public `/webmcp` experience that leaves `/admin` and `/demo`\n  unchanged;\n- six stable browser-native WebMCP tools for reading the current case,\n  detecting context, searching knowledge/workflows, presenting agent analysis,\n  and tracking additional research;\n- local text and text-layer PDF extraction with visible page/line selection,\n  explicit limits, and secret redaction before any network request;\n- a monotonic `case_version` and abort propagation so a late response can never\n  overwrite a case the user has changed;\n- active-revision provenance beside official CliDeck results and a visually\n  separate browser-agent interpretation;\n- ordinary buttons for every primary action, so the product remains useful in\n  browsers without WebMCP.\n\n### Judge walkthrough\n\n1. Open `https://mcp.clideck.com/webmcp` in ChatGPT's in-app browser, or in\n   Chrome 149+ with `chrome://flags/#enable-webmcp-testing` enabled.\n2. Load the labelled Cisco Catalyst 9300 IOS XE 16.10 sample, analyze it, and\n   search for the applicable upgrade procedure.\n3. Enable **Share redacted evidence with browser agent** and ask the agent to\n   explain the current sourced result.\n4. Replace the sample with IOS XE 17.8.1. Observe the new context and\n   `case_version`, then search again for the EFSU-capable path.\n5. Upload a text-layer PDF or LOG, select the relevant page/line window, and\n   repeat the flow.\n6. Ask a genuinely unknown question and start a real tracked research task.\n\nThe page never connects to a device and never executes a command. Complete\nfiles stay in browser memory. Only the selected, locally redacted window is\nsent to CliDeck; browser-agent access requires one explicit opt-in. IP, MAC,\nhostname, and username values are intentionally preserved as diagnostic\ncontext and disclosed in the interface.\n\n## Why this project exists\n\nA general-purpose model may understand networking fundamentals while still\nhaving outdated or incomplete knowledge about exact commands, operating-system\nversions, restrictions, and operational procedures. Reading hundreds of\nmanuals during training does not guarantee a precise answer for a particular\ndevice and software release.\n\nCliDeck MCP separates responsibilities:\n\n- the model understands the question, reasons, and selects the appropriate\n  tool;\n- MCP stores exact, structured, and version-aware knowledge;\n- a Domain Pack enforces the rules of its subject area;\n- the core manages publication, history, trust, conflicts, and rollback.\n\nThis architecture may reduce the need to encode every version of specialized\ndocumentation directly into model weights. We do not claim proven pretraining\ncost reductions; that would require separate experiments. The practical\nbenefit already exists: exact knowledge can be validated and updated\nindependently of the model.\n\n## What makes CliDeck MCP different\n\n### Deterministic answers\n\nA known question does not invoke an LLM. PostgreSQL performs version-aware\nretrieval, the Domain Pack validates the result, and MCP returns a structured\nanswer.\n\nKnown answers are therefore:\n\n- fast;\n- repeatable;\n- inexpensive;\n- verifiable;\n- independent of model-generation variance.\n\nIf applicable knowledge is unavailable, the system returns `unknown` instead\nof guessing.\n\n### Learning from unknown questions\n\nAn unknown question becomes a maximum-priority knowledge demand:\n\n```text\nUnknown question\n      ↓\nOfficial-source discovery\n      ↓\nDownload and deterministic conversion\n      ↓\nChunking and extraction\n      ↓\nIndependent verification and Deep Review\n      ↓\nImmutable publication\n      ↓\nInstant deterministic reuse\n```\n\nA demand is considered learned only after the same deterministic query finds\nan active published revision.\n\n### A continuously running Codex knowledge factory\n\nThe pipeline runs continuously while enabled. Mechanical stages do not consume\nAI tokens:\n\n- downloading;\n- PDF, HTML, and text conversion;\n- OCR;\n- chunking;\n- hashing;\n- indexing;\n- publication.\n\nGPT-5.6 Luna runs through isolated, ephemeral Codex sessions and is used only\nfor work that requires semantic reasoning:\n\n- discovering official sources;\n- analyzing ambiguous material;\n- independent verification;\n- Deep Review;\n- expert tasks.\n\nUp to eight isolated executors lease work atomically. The pipeline can be paused\nand resumed without duplicating tasks or published knowledge. Routine\ndiscovery, analysis, verification, and Deep Review use GPT-5.6 Luna with low\nreasoning effort. Medium reasoning is reserved for unresolved Deep Review\ncases, rather than being spent on every record.\n\n### No separate model API integration required\n\nThe pipeline can run through an existing authenticated local Codex\ninstallation.\n\n> Runs through your existing local Codex setup. No separate model API\n> integration is required. Subject to your Codex plan and usage limits.\n\nThis allows developers to use available capacity in their Codex plan to grow a\nprivate or public knowledge system without first integrating and funding a\nseparate model API.\n\nThis is an operating option, not a promise of free or unlimited usage.\n\n## How Codex and GPT-5.6 were used\n\nCodex was not added at the end as a code-generation demo. It was the primary\nengineering workspace and collaborator throughout the project, from the first\narchitecture decisions to the running production system.\n\nDuring development, Codex and GPT-5.6 were used to:\n\n- translate product goals into the MCP, worker, researcher, and admin\n  architecture;\n- define trust boundaries, immutable revision contracts, release rollback, and\n  privacy controls;\n- implement the TypeScript services, PostgreSQL migrations, Domain Pack SDK,\n  scaffolder, and local operations dashboard;\n- design and test the continuous multi-executor pipeline;\n- build security tests, deterministic evaluations, browser tests, and\n  production smoke checks;\n- inspect real pipeline telemetry and correct throughput, reliability, and\n  data-conservation defects;\n- create the canonical backup, migration, deployment, health-check, and\n  rollback workflow.\n\nCodex and GPT-5.6 are also part of the product's operation:\n\n1. A known question is answered by deterministic PostgreSQL retrieval and\n   Domain Pack validation, with no model call.\n2. An unknown question creates a prioritized learning demand.\n3. Isolated Codex executions pinned to GPT-5.6 Luna\n   (`gpt-5.6-luna`) discover official material, analyze ambiguous fragments,\n   verify candidates, and perform Deep Review.\n4. The core—not the model—enforces schemas, applicability, risk, conflicts,\n   provenance, confidence, and immutable publication.\n5. Once published, the new answer becomes instantly reusable without another\n   GPT-5.6 call.\n\nThis separation is deliberate: **Codex and GPT-5.6 propose and review new\nknowledge; the deterministic core decides what is allowed to become active\nknowledge.** CliDeck MCP is therefore not a wrapper that asks an LLM a question\nand trusts whatever text comes back.\n\n### Universal Domain Packs\n\nCliDeck MCP is not limited to network equipment. Subject-specific behavior\nlives in Domain Packs.\n\nThe core owns:\n\n- immutable revisions;\n- releases and rollback;\n- provenance;\n- confidence thresholds;\n- conflict handling;\n- audit;\n- publication policy.\n\nA Domain Pack defines:\n\n- domain context;\n- record types;\n- data schemas;\n- normalization;\n- deterministic validation;\n- mapping into a universal knowledge revision.\n\nDevelopers can scaffold their own pack:\n\n```bash\npnpm domain:create -- --id marine-science --name \"Marine Science\"\npnpm domain:validate -- --id marine-science\n```\n\nThe scaffolder creates a manifest, schemas, mapper, fixtures, and tests. Codex\nand GPT-5.6 can help adapt a fork to a new subject without rewriting the\ntrusted publication and release core.\n\nOptional providers can add object storage, spatial data, relation graphs, or\ndomain-specific laboratory validation.\n\n## Network Knowledge\n\nThe first production pack stores network knowledge with explicit context:\n\n- vendor;\n- product family and model;\n- operating system;\n- version scope;\n- CLI mode;\n- risks and prerequisites;\n- verification;\n- rollback;\n- limitations and conflicts.\n\nThe public MCP supports:\n\n- device-context resolution;\n- command and diagnostic retrieval;\n- complete operational workflows;\n- expert research tasks;\n- CLI snapshot detection and redaction;\n- planned-change review;\n- post-change verification;\n- upgrade guidance;\n- CDP, LLDP, route, traceroute, and topology analysis;\n- generic queries across other Domain Packs.\n\nDangerous commands are not hidden. The system returns the available\ninformation while clearly explaining risk, prerequisites, verification, and\nrollback.\n\nPortable software is resolved independently from hardware vendor identity.\nONIE, SONiC, OpenWrt, Debian/Linux tooling, and Cumulus Linux/NVUE knowledge\ncan therefore be reused across documented platforms. Model and vendor overlays\nstill take precedence over family-wide records. NX-OS, IOS-XE, Cumulus, and\nOpenWrt use explicit version-branch rules: an exact or bounded record wins,\nand a nearby patch in the same branch is returned only as a labelled\nbest-effort fallback. Hardware-sensitive generic answers remain complete but\ncarry `requires_platform_confirmation` and a stop condition.\n\nExisting immutable revisions are indexed without rewriting their content or\nFTS data:\n\n```bash\npnpm knowledge:reindex-applicability -- --resume --verify\n```\n\nThe command is batched, resumable, checksum-recorded, and idempotent.\n\nCliDeck MCP provides guidance but never connects to a network device and never\nexecutes commands.\n\n## Verifiable knowledge\n\nEvery published revision must pass:\n\n- Domain Pack schema validation;\n- applicability and version checks;\n- deterministic risk classification;\n- conflict detection;\n- confidence and quality thresholds;\n- internal provenance validation;\n- additional requirements for dangerous procedures.\n\nAn official vendor document is sufficient evidence when a specific fragment\ndirectly supports the published claim.\n\nPublished revisions are immutable. Updated information creates a new revision,\nwhile releases allow the active knowledge state to be switched or rolled back\natomically.\n\n## Simple infrastructure\n\nPostgreSQL acts as:\n\n- the knowledge store;\n- the full-text search engine;\n- the task queue;\n- the lease manager;\n- the revision store;\n- the release engine;\n- the audit store.\n\nRedis, a vector database, and an external model API are not required\ndependencies.\n\n## Privacy and security\n\nPublic MCP responses never expose:\n\n- source URLs;\n- manual titles;\n- evidence fragments;\n- internal source IDs;\n- acquisition-pipeline details;\n- credentials or access tokens.\n\nMinimal internal provenance remains available to the local `super_admin` for\nverification and audit.\n\nRaw CLI is processed in memory. A user example is stored only after explicit\nopt-in, redacted again, isolated, and automatically removed after its retention\nperiod. It is never published automatically.\n\n## A truthful public demo\n\n`https://mcp.clideck.com/demo` is not a mock dashboard or a separate marketing\nimplementation.\n\nThe demo uses:\n\n- the same React frontend;\n- the same pages;\n- the same components;\n- the same charts and tables;\n- real production counters;\n- real pipeline and executor states;\n- the same administrative dialogs.\n\nThe only differences are enforced by the `public_demo` role:\n\n- source identity and private values are replaced server-side with `XXXXXXXX`;\n- final mutations are not sent;\n- the database, pipeline, and releases cannot be changed.\n\nSensitive values are removed by the server, not hidden with CSS blur.\n\n![The real CliDeck MCP production operations dashboard](docs/assets/clideck-mcp-demo.jpg)\n\n## Current status\n\nThe production instance contains more than 66,000 active knowledge revisions.\nLive statistics and current pipeline activity are available in the public demo.\n\nThe product evaluation suite contains 250 deterministic scenarios. The current\nresult is:\n\n- 250 passed;\n- 0 failed;\n- 0 dangerous false-safe results.\n\nDeep Network Pack coverage is currently concentrated on Cisco Catalyst and\nIOS-XE. Other vendors can be recognized, but their verified knowledge coverage\nvaries. The system prefers to return a limitation or `unknown` rather than\ngenerate an unsupported answer.\n\nProduction knowledge and third-party documents are not distributed with the\nopen-source repository. The repository contains the framework, schemas,\nscaffolder, tests, and only project-authored or explicitly permitted fixtures.\n\n## Connect\n\nAdd the hosted MCP server to Codex:\n\n```bash\ncodex mcp add clideck --url https://mcp.clideck.com/mcp\ncodex mcp list\n```\n\nRun a local instance:\n\n```bash\ncp .env.example .env\npnpm install --frozen-lockfile\ndocker compose up -d postgres\npnpm db:migrate\npnpm db:seed\npnpm build\npnpm dev:api\n```\n\nThe local MCP endpoint is:\n\n```text\nhttp://127.0.0.1:8787/mcp\n```\n\nCliDeck MCP uses Streamable HTTP and is not limited to CliDeck or Codex\nclients. Any compatible MCP client can connect to it.\n\n## Create your own Domain Pack\n\n```bash\npnpm domain:create -- --id marine-science --name \"Marine Science\"\npnpm install --lockfile-only\npnpm domain:validate -- --id marine-science\npnpm --filter @clideck/domain-marine-science test\n```\n\nRead the detailed guides:\n\n- [Domain Pack authoring](docs/DOMAIN_PACK_AUTHORING.md)\n- [Adapting a fork with Codex](docs/FORKING_WITH_CODEX.md)\n- [Architecture](docs/ARCHITECTURE.md)\n- [Security](docs/SECURITY.md)\n- [Data and licensing notice](DATA-NOTICE.md)\n\n## License and data\n\nApache-2.0 applies to the source code and project-authored sample fixtures.\n\nIt does not automatically grant rights to:\n\n- third-party documents;\n- production knowledge;\n- private manuals;\n- user data;\n- datasets imported by an operator.\n\nSee [DATA-NOTICE.md](DATA-NOTICE.md) for details.\n",
  "bytes": 16008,
  "sha": "3a68962fd7f095286ae61723a51def9885dcff361cf5f52f3098b29427a1a83b",
  "repo_slug": "smartroot7/clideck-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_com_clideck_network_knowledge_af3dfae9/readme"
}