CKS MCP Server

Model Context Protocol server for Canonical Knowledge Structure.

Python License Tests

cks-mcp is an MCP (Model Context Protocol) server that provides LLMs with structured, verifiable knowledge operations through the CKS ecosystem. It exposes four tools—validate_knowledge, serialize_knowledge, explain_knowledge, and evolve_knowledge—each backed by the deterministic, immutable semantics of cks-core and the operational management of cks-runtime.

Every tool call now 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. This minimises hallucinations and makes AI‑ generated knowledge auditable.

In addition to the built‑in validation rules, validate_knowledge supports opt‑in extensions — extra, non‑default constraints that can be activated per call without affecting global state. The first available extension, embedding_projection, mechanically detects citation hallucinations: it verifies that every EmbeddingProjection points to a real source object that actually exists in the structure. This turns the abstract goal of "reducing hallucinations" into a concrete, machine‑checkable property of the knowledge graph.

Installation

pip install cks-mcp

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

Quick Start

Launch the MCP server

cks-mcp

An MCP client (Claude Desktop, any MCP-compatible LLM) can then connect and call tools.

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 four 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 (e.g. embedding_projection).
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.

Usage Example

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

Catching citation hallucinations

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, giving you a clear, machine‑readable diagnostic instead of an undetected hallucination.

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.6.0.tar.gz (17.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.6.0-py3-none-any.whl (13.9 kB view details)

Uploaded Python 3

File details

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

File metadata

  • Download URL: cks_mcp-0.6.0.tar.gz
  • Upload date:
  • Size: 17.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.6.0.tar.gz
Algorithm Hash digest
SHA256 aff27047dfbd7d8cbf62c5c5fcd477a9b311838fb03fa74a7107f50a131508e7
MD5 75c812427639592d6dc2d6af07b01fde
BLAKE2b-256 aee8c8cea91e98ea0a4ce406b7c670769109e4b6315c073f23159fd24c443b94

See more details on using hashes here.

File details

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

File metadata

  • Download URL: cks_mcp-0.6.0-py3-none-any.whl
  • Upload date:
  • Size: 13.9 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.6.0-py3-none-any.whl
Algorithm Hash digest
SHA256 982a3b8329230d730d258182ebc8804364a572c28c9d5ee22b13d55b03965ed4
MD5 8a2306807206ff5418c723c1ab0f569c
BLAKE2b-256 8a8b0598c6f7ff1354f53cbd2f8a3e97be60edb6d4a5f0ec5acb33ce258a8e51

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

0.7.1

2 files

0.7.0

2 files

0.6.3

2 files

0.6.2

2 files

0.6.1

2 files

This release

0.6.0 This release

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