CKS MCP Server

Model Context Protocol server for Canonical Knowledge Structure.

Python License Tests PyPI

cks-mcp is an MCP (Model Context Protocol) server that gives LLMs a canonical knowledge backbone. It exposes five tools — validate_knowledge, serialize_knowledge, explain_knowledge, evolve_knowledge, and verify_source — 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

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.
  • Full audit trail — every operation is captured in an immutable version history, providing complete accountability for AI-generated knowledge.

Installation

pip install cks-mcp

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

Quick Start

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 five tools is ready to use.

Interactive LLM client (Groq / DeepSeek / local)

export GROQ_API_KEY=your_key_here
python llm_client/cks_llm_client.py --provider groq

You can then type natural language requests; the LLM will automatically call the appropriate CKS tool.

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. This is the only legitimate way to create verification records.

Usage Examples

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\": [], ...}"
      }
    ]
  }
}

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

26+ tests, all passing.

License

MIT

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (1.77.0)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for Deus-corp from gravatar.com Deus-corp

Credits

Author: Vladyslav Hruznov

License

MIT

Requires

Python >=3.12

Provides Extra

dev

Report project as malware

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-0.7.1.tar.gz (20.3 kB view details)

Uploaded Source

Built Distribution

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

cks_mcp-0.7.1-py3-none-any.whl (16.5 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: cks_mcp-0.7.1.tar.gz
  • Upload date:
  • Size: 20.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.2.0 CPython/3.12.13

File hashes

Hashes for cks_mcp-0.7.1.tar.gz
Algorithm Hash digest
SHA256 5d78b7c34e6362f5b226de18d090d0c46a586d8477b463d1d7455efdb7eabbdc
MD5 85dade64ef63c95e36012eaba2e0f7e4
BLAKE2b-256 2645ab5a5c6c511df7d0ebbf6458941249c7f4bae95376952128dfddd7a2b47a

See more details on using hashes here.

File details

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

File metadata

  • Download URL: cks_mcp-0.7.1-py3-none-any.whl
  • Upload date:
  • Size: 16.5 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.2.0 CPython/3.12.13

File hashes

Hashes for cks_mcp-0.7.1-py3-none-any.whl
Algorithm Hash digest
SHA256 3ad55cb4d3ac08334ad2ab2946f4075fb482a57e89e201dd8e913487ec01ab19
MD5 6c8b701123eb2f9daca987ddbb2445fd
BLAKE2b-256 256df7eefc834eda75ce4a8975cb63dc9abebc6b24d62d1737b0339fa1409b67

See more details on using hashes here.

Release history Release notifications | RSS feed

1.77.0

2 files

1.76.8

2 files

1.76.7

2 files

1.76.6

2 files

1.76.5

2 files

1.76.4

2 files

1.76.3

2 files

1.76.2

2 files

1.76.1

2 files

1.76.0

2 files

1.75.0

2 files

1.74.1

2 files

1.74.0

2 files

1.73.0

2 files

1.72.0

2 files

1.71.2

2 files

1.71.1

2 files

1.71.0

2 files

1.70.1

2 files

1.70.0

2 files

1.69.1

2 files

1.69.0

2 files

1.68.2

2 files

1.68.1

2 files

1.68.0

2 files

1.67.0

2 files

1.66.0

2 files

1.65.0

2 files

1.64.0

2 files

1.63.0

2 files

1.62.0

2 files

1.61.0

2 files

1.60.0

2 files

1.59.0

2 files

1.58.0

2 files

1.57.3

2 files

1.57.2

2 files

1.57.1

2 files

1.57.0

2 files

1.56.2

2 files

1.56.1

2 files

1.56.0

2 files

1.55.0

2 files

1.54.1

2 files

1.54.0

2 files

1.53.3

2 files

1.53.2

2 files

1.53.1

2 files

1.53.0

2 files

1.52.3

2 files

1.52.2

2 files

1.52.1

2 files

1.52.0

2 files

1.51.3

2 files

1.51.2

2 files

1.51.1

2 files

1.51.0

2 files

1.50.0

2 files

1.49.0

2 files

1.48.0

2 files

1.47.0

2 files

1.46.0

2 files

1.45.0

2 files

1.44.0

2 files

1.43.0

2 files

1.42.0

2 files

1.41.0

2 files

1.40.0

2 files

1.39.0

2 files

1.38.0

2 files

1.37.0

2 files

1.36.0

2 files

1.35.0

2 files

1.34.0

2 files

1.33.0

2 files

1.32.2

2 files

1.32.1

2 files

1.32.0

2 files

1.31.1

2 files

1.31.0

2 files

1.30.0

2 files

1.29.0

2 files

1.28.0

2 files

1.27.1

2 files

1.27.0

2 files

1.26.0

2 files

1.25.0

2 files

1.24.0

2 files

1.23.0

2 files

1.22.0

2 files

1.21.0

2 files

1.20.3

2 files

1.20.2

2 files

1.20.1

2 files

1.20.0

2 files

1.19.0

2 files

1.18.1

2 files

1.18.0

2 files

1.17.0

2 files

1.16.2

2 files

1.16.1

2 files

1.16.0

2 files

1.15.0

2 files

1.14.4

2 files

1.14.3

2 files

1.14.2

2 files

1.14.1

2 files

1.14.0

2 files

1.13.2

2 files

1.13.1

2 files

1.13.0

2 files

1.12.2

2 files

1.12.1

2 files

1.12.0

2 files

1.11.1

2 files

1.11.0

2 files

1.10.6

2 files

1.10.5

2 files

1.10.3

2 files

1.10.2

2 files

1.10.1

2 files

1.10.0

2 files

1.9.3

2 files

1.9.2

2 files

1.9.1

2 files

1.9.0

2 files

1.8.2

2 files

1.8.1

2 files

1.8.0

2 files

1.7.14

2 files

1.7.13

2 files

1.7.12

2 files

1.7.11

2 files

1.7.10

2 files

1.7.9

2 files

1.7.8

2 files

1.7.7

2 files

1.7.6

2 files

1.7.5

2 files

1.7.4

2 files

1.7.3

2 files

1.7.2

2 files

1.7.1

2 files

1.7.0

2 files

1.6.19

2 files

1.6.18

2 files

1.6.17

2 files

1.6.16

2 files

1.6.14

2 files

1.6.13

2 files

1.6.12

2 files

1.6.11

2 files

1.6.10

2 files

1.6.9

2 files

1.6.8

2 files

1.6.7

2 files

1.6.6

2 files

1.6.5

2 files

1.6.4

2 files

1.6.3

2 files

1.6.2

2 files

1.6.1

2 files

1.6.0

2 files

1.5.4

2 files

1.5.2

2 files

1.5.1

2 files

1.5.0

2 files

1.4.1

2 files

1.4.0

2 files

1.3.5

2 files

1.3.4

2 files

1.3.3

2 files

1.3.2

2 files

1.3.1

2 files

1.3.0

2 files

1.2.6

2 files

1.2.5

2 files

1.2.4

2 files

1.2.3

2 files

1.2.2

2 files

1.2.1

2 files

1.2.0

2 files

1.1.1

2 files

1.1.0

2 files

1.0.10

2 files

1.0.9

2 files

1.0.8

2 files

1.0.7

2 files

1.0.6

2 files

1.0.5

2 files

1.0.4

2 files

1.0.3

2 files

1.0.2

2 files

1.0.1

2 files

1.0.0

2 files

0.7.8

2 files

0.7.7

2 files

0.7.6

2 files

0.7.5

2 files

0.7.4

2 files

0.7.3

2 files

0.7.2

2 files

This release

0.7.1 This release

2 files

0.7.0

2 files

0.6.3

2 files

0.6.2

2 files

0.6.1

2 files

0.6.0

2 files

0.5.2

2 files

0.5.1

2 files

0.5.0

2 files

0.4.4

2 files

0.4.3

2 files

0.4.2

2 files

0.4.1

2 files

0.4.0

2 files

0.3.3

2 files

0.3.2

2 files

0.3.1

2 files

0.3.0

2 files

0.2.1

2 files

0.2.0

2 files

0.1.1

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page