CKS MCP Server

Model Context Protocol server for Canonical Knowledge Structure.

Python License Tests

cks-mcp is an MCP (Model Context Protocol) server that gives LLMs a canonical knowledge backbone. It exposes the tools listed under Available Tools below, backed by the deterministic, immutable semantics of cks-core and the 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.

Ecosystem

CKS Core is the semantic foundation of the CKS 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

Install and connect to Claude Desktop (see Installation).
(Optional) For semantic search, set your Hugging Face token: export HF_TOKEN=hf_...
In the chat, start your message with "Use cks-mcp to…".
Claude automatically picks the right tool from the 21 available — validation, evolution, branching, merging, source verification, contradiction detection, semantic search, subgraph queries, sandboxing, and more.
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!

CKS Demo

In the video above, Claude creates a validated knowledge graph about the water cycle from a single sentence, using validate_knowledge and explain_knowledge. Twenty-one 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.

Installation

pip install cks-mcp

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

For semantic search, you also need a Hugging Face token:

export HF_TOKEN=hf_...

Connect to Claude Desktop

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

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"
    }
  }
}
```
Save the file and fully restart Claude Desktop (Cmd+Q, then reopen). After restart, a connector icon will appear – cks-mcp with twenty-one tools is ready to use.

Available Tools

Tool	Description
`validate_knowledge`	Validate a Knowledge Structure and return diagnostics. Supports opt‑in extensions (`embedding_projection`, `verification_record`). Provenance of `VerificationRecord` objects is checked automatically.
`serialize_knowledge`	Serialize a Knowledge Structure into canonical JSON.
`explain_knowledge`	Produce a semantic explanation of a Knowledge Structure.
`evolve_knowledge`	Apply Genesis/Decay operators to evolve a structure.
`verify_source`	Perform a real HTTP request to check a URL's availability and create a cryptographically signed `VerificationRecord`.
`list_versions`	List all available versions of a session's history.
`compare_versions`	Compute the structural difference between the current state of a session and a target version.
`revert_version`	Revert a session's Knowledge Structure to a specific previous version.
`merge_knowledge`	Three-way merge of knowledge structures with conflict detection.
`create_branch`	Fork a new session from an existing one, optionally from a specific historical version.
`merge_branch`	Session-aware three-way merge: merge a branch session into a target session, resolving the merge base automatically from the branch's recorded fork point.
`close_session`	Close a session, releasing it from the runtime (e.g. a branch already merged in).
`query_subgraph`	Extract a local k‑hop neighbourhood from a session's Knowledge Structure, with filters, optional budget, and compact mode.
`search_semantic`	Real embedding-based semantic search. Uses HuggingFace models to find relevant objects by meaning. Query "virtual machines" returns EC2, not S3.
`get_metrics`	Return runtime metrics: invocation counts and average execution times per operation type.
`visualize_graph`	Export a session's Knowledge Structure or a subgraph as a Mermaid diagram for native rendering in Claude Desktop.
`explain_diff`	Produce a natural-language explanation of changes between two versions, complementing `compare_versions`.
`suggest_evolution`	Inspect the current state of a session and receive guidance for constructing valid evolution operations.
`export_knowledge`	Export a session's Knowledge Structure to JSON-LD, Turtle, or RDF/XML for use with Protégé, Neo4j, or triple stores.
`detect_contradictions`	Detect logical contradictions (mutual exclusion, functional relation violations) using the new contradiction constraints.
`fork_sandbox`	Create an isolated branch, optionally apply a hypothesis, and show a diff from the fork point — safe to discard or promote.

Usage Examples

Semantic search (no seed IDs required!)

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

Response:

{
  "status": "success",
  "matched_seeds": ["ec2", "compute-service", "aws"],
  "subgraph": "...",
  "meta": { ... }
}

Compact subgraph query

{
  "method": "tools/call",
  "params": {
    "name": "query_subgraph",
    "arguments": {
      "session_id": "...",
      "seed_ids": ["earth", "mars"],
      "depth": 2,
      "compact_mode": true
    }
  }
}

Response (compact, token-efficient):

{
  "nodes": [
    {"id": "earth", "type": "Planet", "name": "Earth", "props": {...}},
    {"id": "mars", "type": "Planet", "name": "Mars", "props": {...}}
  ],
  "edges": [
    {"source": "earth", "target": "sun", "type": "orbits"}
  ]
}

Validate a structure with citation-hallucination detection

Pass "extensions": ["embedding_projection"] to validate_knowledge. This activates an extra constraint that checks every EmbeddingProjection object for a valid represents relation to an existing source object. A projection that references a non‑existent source (a fabricated citation) is mechanically flagged.

Validate a structure with verification integrity

When you use verify_source to check a URL, the resulting VerificationRecord is cryptographically signed. Any VerificationRecord found in a structure without a valid signature is automatically rejected, even if the model does not explicitly request the verification extension. This prevents LLMs from bypassing the check by simply omitting a parameter.

Basic validation

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

Response (with version and session information):

{
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"valid\": true, \"version_id\": \"...\", \"session_id\": \"...\", \"diagnostics\": [], ...}"
      }
    ]
  }
}

Compare two versions

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

Response:

{
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"session_id\": \"...\", \"target_version_id\": \"...\", \"changes\": [...]}"
      }
    ]
  }
}

Branch, evolve independently, and merge back

Fork a session, evolve the branch and its parent independently, then merge the branch back in:

{"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 of the target session and returns its serialized structure and version_id. A conflicting merge instead returns "merged": false with a conflicts list (object_id, base_state, target_state, source_state) — resolve each one on the target session with evolve_knowledge, then close_session the branch once it's fully integrated.

Query a subgraph

{
  "method": "tools/call",
  "params": {
    "name": "query_subgraph",
    "arguments": {
      "session_id": "...",
      "seed_ids": ["obj-1"],
      "depth": 2,
      "max_objects": 10
    }
  }
}

Response (truncated example):

{
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"subgraph\": \"...\", \"total_found_nodes\": 15, \"returned_nodes\": 10, \"is_truncated\": true, \"suggested_next_seed\": \"obj-7\"}"
      }
    ]
  }
}

Visualize a knowledge graph

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

Response (Mermaid diagram):

```mermaid
graph TD
    earth((Earth))
    sun((Sun))
    earth -->|orbits| sun
```

Explain the difference between two versions

{
  "method": "tools/call",
  "params": {
    "name": "explain_diff",
    "arguments": {
      "session_id": "...",
      "base_version_id": "...",
      "target_version_id": "..."
    }
  }
}

Response:

{
  "summary": "Added 2 objects and 1 relation. Modified 1 object.",
  "changes": [
    "Added object 'Pluto' (type: Planet)",
    "Added object 'Charon' (type: Moon)",
    "Added relation 'orbits' from 'Pluto' to 'Charon'",
    "Modified object 'Earth': changed 'status' from 'active' to 'inactive'"
  ]
}

Get AI assistance with evolution

{
  "method": "tools/call",
  "params": {
    "name": "suggest_evolution",
    "arguments": {
      "session_id": "...",
      "description": "Add a new planet Neptune that orbits the Sun"
    }
  }
}

Response:

{
  "current_objects": [
    {"id": "sun", "type": "Star", "name": "Sun"},
    {"id": "earth", "type": "Planet", "name": "Earth"},
    {"id": "moon", "type": "Moon", "name": "Moon"}
  ],
  "current_relations": [
    {"type": "orbits", "from": "earth", "to": "sun"},
    {"type": "orbits", "from": "moon", "to": "earth"}
  ],
  "guidance": "To add a new planet Neptune: use add_object with identity {id: 'neptune', type: 'Planet', name: 'Neptune'} and add_relation with participants ['neptune', 'sun'] and relation_type 'orbits'."
}

Export to RDF/JSON-LD

{
  "method": "tools/call",
  "params": {
    "name": "export_knowledge",
    "arguments": {
      "session_id": "...",
      "format": "turtle"
    }
  }
}

Response:

@prefix cks: <http://cks.org/> .
@prefix rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#> .

<http://cks.org/sun> rdf:type <http://cks.org/Star> ;
    rdfs:label "Sun" .

<http://cks.org/earth> rdf:type <http://cks.org/Planet> ;
    rdfs:label "Earth" ;
    <http://cks.org/orbits> <http://cks.org/sun> .

Detect contradictions

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

Response:

{
  "contradiction_count": 1,
  "contradictions": [
    {
      "code": "CKS-EXT-MUTUAL-EXCLUSION",
      "severity": "error",
      "source": "core",
      "message": "Relation 'rel-1' (type 'supports') and relation 'rel-2' (type 'contradicts') both connect 'a' to 'b', but a MutualExclusionRule declares these relation_types mutually exclusive."
    }
  ]
}

Fork a sandbox and test a hypothesis

{
  "method": "tools/call",
  "params": {
    "name": "fork_sandbox",
    "arguments": {
      "session_id": "...",
      "hypothesis": "Add Neptune as a planet orbiting the Sun",
      "operations": [
        {"type": "add_object", "identity": {"id": "neptune", "type": "Planet", "name": "Neptune"}},
        {"type": "add_relation", "identity": {"id": "rel-nep", "type": "Relation", "name": "orbits"}, "participants": ["neptune", "sun"], "relation_type": "orbits"}
      ]
    }
  }
}

Response:

{
  "sandbox_session_id": "...",
  "parent_session_id": "...",
  "operations_applied": 2,
  "diff_from_fork_point": {
    "summary": {"added_objects": 1, "added_relations": 1, "removed_objects": 0, "removed_relations": 0},
    "operations": [...]
  },
  "message": "Sandbox session '...' is an isolated fork of '...'; nothing here affects the parent. Keep exploring it with evolve_knowledge, promote it with merge_branch once satisfied, or discard it with close_session -- there is no obligation to merge."
}

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

107+ tests, all passing.

License

MIT

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

cks_mcp-1.12.0.tar.gz (66.2 kB view details)

Uploaded Jul 28, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

cks_mcp-1.12.0-py3-none-any.whl (56.0 kB view details)

Uploaded Jul 28, 2026 Python 3

File details

Details for the file cks_mcp-1.12.0.tar.gz.

File metadata

Download URL: cks_mcp-1.12.0.tar.gz
Upload date: Jul 28, 2026
Size: 66.2 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/7.0.0 CPython/3.12.13

File hashes

Hashes for cks_mcp-1.12.0.tar.gz
Algorithm	Hash digest
SHA256	`ba46872ae2f83959b601aed6ec6f6ae4aca753279a7a10386f588d48e1ba4c0f`
MD5	`b47b9817e213d2e2ca1e376744ceb6cc`
BLAKE2b-256	`b53be7866432af8f21d12a3dc37dcc84841fc261ae6ca33c412ea5935a194fb8`

See more details on using hashes here.

File details

Details for the file cks_mcp-1.12.0-py3-none-any.whl.

File metadata

Download URL: cks_mcp-1.12.0-py3-none-any.whl
Upload date: Jul 28, 2026
Size: 56.0 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/7.0.0 CPython/3.12.13

File hashes

Hashes for cks_mcp-1.12.0-py3-none-any.whl
Algorithm	Hash digest
SHA256	`37d7c74b4b608d4f61beef716712b55b69abdd162245a97e977bb1c20b01dd65`
MD5	`7805a086f59a978cd6875cf537f28542`
BLAKE2b-256	`a7c4c68c39f3e45637e80ffcce35d0c7ed769460e6130c49aafd52fa4bd9e014`