CKS MCP Server

Model Context Protocol server for Canonical Knowledge Structure.

cks-mcp is a fully asynchronous MCP (Model Context Protocol) server that gives LLMs a canonical knowledge backbone. It exposes 24 tools (listed under Available Tools below) for validation, evolution, branching, merging, semantic search, contradiction detection, sandboxing, and more, backed by the deterministic, immutable semantics of cks-core and the async operational management of cks-runtime.

Every tool call creates a Runtime Session and Transaction, producing an immutable Version and collecting Diagnostics. This guarantees full auditability and reproducibility.

📚 Full documentation: docs/index.md — start with Getting Started or jump straight to the Tools Reference.

---

Ecosystem

Other projects build upon it:

Project	Description	Repository
cks-core	Canonical semantic engine	Deus-corp/cks-core
cks-runtime	Operational environment – sessions, transactions, persistence	Deus-corp/cks-runtime
cks-mcp	MCP server – exposes CKS to LLMs (this repository)	Deus-corp/cks-mcp

---

Quick Start

1. Install and connect to Claude Desktop (see Installation).
2. (Optional) Semantic search works out of the box with the built-in fastembed engine (no API keys required). To use HuggingFace models instead, set CKS_EMBEDDING_PROVIDER=huggingface and export HF_TOKEN=hf_.... See Getting Started.
3. In the chat, start your message with "Use cks-mcp to…".
4. Claude automatically picks the right tool from the 24 available — validation, evolution, branching, merging, source verification, contradiction detection, semantic search, subgraph queries, sandboxing, and more.
5. Every operation is logged, versioned, and stored in a persistent SQLite database.

Just type "Use cks-mcp to..." and Claude does the rest. That's it. No programming, no command line — just a conversation!

In the video above, Claude creates a validated knowledge graph about the water cycle from a single sentence, using validate_knowledge and explain_knowledge. All 24 tools are ready for you: branching, merging, versioning, source verification, contradiction detection, subgraph queries, sandboxing, and more — all triggered by plain English.

---

Why cks-mcp?

LLMs generate plausible but unverified statements. cks-mcp gives them a canonical knowledge backbone: every piece of information must be explicitly structured, validated against formal constraints, and traceable to its origin.

• Eliminate citation hallucinations — optional extensions like embedding_projection mechanically detect references to non-existent sources.
• Ensure verification integrity — the verify_source tool performs a real HTTP check and cryptographically signs the result. Any VerificationRecord without a valid signature is automatically rejected, even if the model fails to request the check.
• Semantic search with real embeddings — the search_semantic tool uses HuggingFace models to find relevant nodes by meaning, not just keywords. A query for "how to train AI models" returns "Gradient Descent" and "Neural Network", not "Banana".
• Graph-based RAG — combine semantic search with query_subgraph to retrieve a full neighbourhood around the found concepts, giving the LLM the context it needs without hallucinating connections.
• Full audit trail — every operation is captured in an immutable version history, providing complete accountability for AI-generated knowledge.
• Time-travel debugging — list_versions, revert_version, and compare_versions give LLMs a full version-control system for knowledge, enabling safe rollbacks and change inspection.
• Contradiction detection — detect_contradictions flags mutual exclusions (e.g., both supports and contradicts between the same pair) and functional relation violations (e.g., a planet orbiting two different stars).
• Hypothesis sandboxing — fork_sandbox creates an isolated branch, optionally applies a hypothesis, and reports the diff from the fork point — all without touching the parent session. Safe to discard or promote.
• Content ingestion — ingest_document fetches a public URL, extracts title, description and keywords, and builds a preliminary Knowledge Structure.
• LLM-assisted knowledge construction — construct_knowledge converts free-form text into a validated Knowledge Structure using a local Ollama model (no API key needed) or the Anthropic API, auto-selected via CKS_LLM_PROVIDER.
• Session portability — export_session packages a full session bundle (structure + version history) for migration or archival.
• Telemetry dashboard — get_metrics now returns per‑tool latency percentiles (p50/p95/p99), success rates, and top error types since server start.

---

Installation

pip install cks-mcp

The server requires cks-runtime (which includes cks-core) as a dependency.

See Getting Started for the full list of environment variables and how to set them via a ~/.cks-mcp/.env file.

---

Connect to Claude Desktop

1. Install all three packages into a single virtual environment:

   python3 -m venv cks-env
   source cks-env/bin/activate
   pip install cks-core cks-runtime cks-mcp

2. Open Claude Desktop, go to Settings → Developer → Edit Config. The configuration file (claude_desktop_config.json) will open. Add the following block (adjust the path to your cks-mcp executable):

   {
     "mcpServers": {
       "cks-mcp": {
         "command": "/absolute/path/to/cks-env/bin/cks-mcp"
       }
     }
   }

3. Save the file and fully restart Claude Desktop (Cmd+Q, then reopen). After restart, a connector icon will appear – cks-mcp with 24 tools is ready to use.

See Getting Started for a walkthrough of your first session once the server is connected.

---

Available Tools

24 tools, grouped by function. Full reference with parameters and real request/response examples: docs/tools/.

Group	Tools
Knowledge Lifecycle	validate_knowledge, serialize_knowledge, explain_knowledge, evolve_knowledge
Version Control	list_versions, revert_version, compare_versions, explain_diff
Branching & Merging	create_branch, merge_branch, merge_knowledge, close_session, fork_sandbox
Graph Exploration	query_subgraph, search_semantic, visualize_graph
Verification & Integrity	verify_source, detect_contradictions
AI-Assisted & Ingestion	construct_knowledge, suggest_evolution, ingest_document
Export & Observability	export_knowledge, export_session, get_metrics

---

Usage Examples

A couple of representative calls — the full set, with real response shapes for every tool, is in docs/tools/.

Validate a structure

{
  "method": "tools/call",
  "params": {
    "name": "validate_knowledge",
    "arguments": {
      "json_data": "{\"objects\":[{\"identity\":{\"id\":\"obj-1\",\"type\":\"Definition\",\"name\":\"Test\"},\"structure\":{}}]}"
    }
  }
}

The response includes valid, session_id, version_id, and diagnostics — keep session_id for every following call on this structure. See Knowledge Lifecycle for the other three tools in this group.

Semantic search (no seed IDs required)

{
  "method": "tools/call",
  "params": {
    "name": "search_semantic",
    "arguments": {"session_id": "...", "query": "virtual machines in the cloud"}
  }
}

Returns matched objects by meaning (e.g. EC2, not S3), expanded into a subgraph. See Graph Exploration.

Branch, evolve independently, and merge back

{"method": "tools/call", "params": {"name": "create_branch", "arguments": {"session_id": "trunk-session-id"}}}

{"method": "tools/call", "params": {"name": "evolve_knowledge", "arguments": {"session_id": "branch-session-id", "operations": [...]}}}

{"method": "tools/call", "params": {"name": "merge_branch", "arguments": {"target_session_id": "trunk-session-id", "source_session_id": "branch-session-id"}}}

A successful merge commits a new version and returns the merged structure; a conflicting merge returns "merged": false with a conflicts list to resolve. See Branching & Merging for the full conflict-resolution flow.

Detect contradictions

{
  "method": "tools/call",
  "params": {
    "name": "detect_contradictions",
    "arguments": {"session_id": "..."}
  }
}

Requires MutualExclusionRule and/or FunctionalRelationRule objects in the structure declaring which relation types to check. See Verification & Integrity for the rule shapes and how this interacts with verify_source's provenance signing.

---

Security and Provenance

verify_source includes built-in protections:

• SSRF prevention: URLs are validated against a strict allowlist; private, loopback, and cloud metadata IPs are blocked. DNS rebinding attacks are neutralised by pinning the connection to the IP address resolved during the safety check.
• Cryptographic signing: every verification record is signed with a process-local HMAC. validate_knowledge unconditionally verifies this signature, so a hand‑written VerificationRecord can never pass as genuine.

---

Testing

python -m pytest -v

179+ tests, all passing.

---

License

MIT