Metadata-Version: 2.4
Name: cks-mcp
Version: 1.19.0
Summary: CKS MCP Server — Canonical Knowledge Structure for LLMs
Author: Vladyslav Hruznov
License: MIT
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: cks-runtime>=1.25.1
Requires-Dist: cks-core>=1.16.0
Requires-Dist: requests>=2.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
Provides-Extra: fastembed
Requires-Dist: fastembed>=0.3; extra == "fastembed"
Dynamic: license-file

# CKS MCP Server

> Model Context Protocol server for Canonical Knowledge Structure.

![Python](https://img.shields.io/badge/python-3.12%2B-blue)
![License](https://img.shields.io/badge/license-MIT-green)
![Tests](https://img.shields.io/badge/tests-179%20passed-brightgreen)
[![PyPI](https://img.shields.io/pypi/v/cks-mcp)](https://pypi.org/project/cks-mcp/)

`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](docs/index.md) — start with
[Getting Started](docs/getting-started.md) or jump straight to the
[Tools Reference](docs/tools/index.md).

---

# Ecosystem

Other projects build upon it:

| Project | Description | Repository |
|---------|-------------|------------|
| **cks-core** | Canonical semantic engine | [Deus-corp/cks-core](https://github.com/Deus-corp/cks-core) |
| **cks-runtime** | Operational environment – sessions, transactions, persistence | [Deus-corp/cks-runtime](https://github.com/Deus-corp/cks-runtime) |
| **cks-mcp** | MCP server – exposes CKS to LLMs (this repository) | [Deus-corp/cks-mcp](https://github.com/Deus-corp/cks-mcp) |

---

# Quick Start

1. Install and connect to Claude Desktop (see [Installation](#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](docs/getting-started.md).
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!**

![CKS Demo](https://github.com/Deus-corp/cks-mcp/releases/download/v1.10.2/demo.gif)

*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

```bash
pip install cks-mcp
```

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

See [Getting Started](docs/getting-started.md#optional-environment-variables)
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:
   ```bash
   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):
   ```json
   {
     "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](docs/getting-started.md) 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/`](docs/tools/index.md).

| 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/`](docs/tools/index.md).

## Validate a structure

```json
{
  "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](docs/tools/lifecycle.md) for the
other three tools in this group.

## Semantic search (no seed IDs required)

```json
{
  "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](docs/tools/search-and-graph.md).

## Branch, evolve independently, and merge back

```json
{"method": "tools/call", "params": {"name": "create_branch", "arguments": {"session_id": "trunk-session-id"}}}
```
```json
{"method": "tools/call", "params": {"name": "evolve_knowledge", "arguments": {"session_id": "branch-session-id", "operations": [...]}}}
```
```json
{"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](docs/tools/branching.md) for the full
conflict-resolution flow.

## Detect contradictions

```json
{
  "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](docs/tools/verification.md) 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

```bash
python -m pytest -v
```

179+ tests, all passing.

---

# License

MIT
