ckg-mcp

mcp-name: io.github.Yarmoluk/ckg-mcp

Give your agent the structure, not the search. ckg-mcp serves Compressed Knowledge Graphs — pre-structured, typed dependency graphs — to any MCP client. Instead of retrieving text chunks and hoping the model infers the relationships, your agent traverses declared edges: prerequisites, dependency chains, and category membership, returned as a tight subgraph.

On the open CKG Benchmark, this approach scores 3.8× the F1 of RAG at 11× fewer tokens — and unlike RAG, it cannot fabricate a relationship that isn't in the graph.

Quickstart (30 seconds)

pip install ckg-mcp        # or: uvx ckg-mcp  (zero-install)

Claude Desktop — add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "ckg": {
      "command": "ckg-mcp"
    }
  }
}

Claude Code (CLI):

claude mcp add ckg -- ckg-mcp

Cursor / Cline / Windsurf — same block in your MCP settings:

{ "mcpServers": { "ckg": { "command": "ckg-mcp" } } }

Prefer no global install? Swap the command for uvx:

{ "mcpServers": { "ckg": { "command": "uvx", "args": ["ckg-mcp"] } } }

Restart the client. Ask your agent: "Use the ckg tools — list the domains, then trace the prerequisite chain for 'Taylor Series' in calculus."

What you get

Four tools over 65 bundled domains (no database, no embeddings, no API key):

Example

list_domains()
→ calculus, circuits, machine-learning-textbook, glp1-obesity, payer-formulary, google-dataplex, ... (65)

get_prerequisites(domain="calculus", concept="Taylor Series")
→ Taylor Series → Power Series → Higher-Order Derivative → Derivative Function
  → … → Limit → … → Function   (20 concepts — every edge declared in the graph, not inferred from prose)

query_ckg(domain="circuits", concept="RC Discharging", depth=2)
→ subgraph: RC Discharging ← RC Circuit, Capacitor Energy Storage, Initial Conditions ...

Why it beats retrieval

Three architectures, same questions, measured on the open CKG Benchmark (45 domains, 7,928 queries, fully reproducible):

• 3.8× the F1 of RAG, at 11× fewer tokens per query.
• ~42× higher RDS (Retrieval Density Score = F1 per token) — the compound efficiency metric.
• ~10× cheaper to run the full query set ($7.81 vs $76.23; ≈$0.0010 vs $0.0106 per query).
• CKG strengthens with depth (0.37 → 0.77 from hop 0 to hop 5); RAG stays flat and low — retrieval has no mechanism for traversing a chain.
• *GraphRAG is not better than RAG here (0.120 vs 0.123, and more tokens). The win isn't "a graph" — it's a pre-structured, compiled* graph.

Don't trust the numbers — re-run them: ``bash git clone https://github.com/Yarmoluk/ckg-benchmark && cd ckg-benchmark pip install -r evaluation/requirements.txt python evaluation/ckg_harness.py --domain calculus python evaluation/analyze_results.py ``

How it works

A Compressed Knowledge Graph is a plain-text .csv/.md DAG — entities, typed dependency edges, and taxonomy — that the LLM reads directly:

ConceptID,ConceptLabel,Dependencies,TaxonomyID
1,Function,,FOUND
2,Domain and Range,1,FOUND
4,Composite Function,1|3,FOUND

ckg-mcp does deterministic graph traversal (BFS/DFS) over these declared edges and hands the agent the exact subgraph it asked for. Because the server returns declared edges, not generated text, it cannot invent a relationship that isn't in the graph — that's what "0 fabricated edges by construction" means. (The LLM still writes the final answer in prose; the knowledge it reasons over is exact.)

No graph database. No vector store. No retrieval pipeline. Drop the server in, or drop a single .md into a system prompt.

Bundled domains (65)

Reference graphs — laudato-si, art-of-war, token-cost-crisis, agent-reliability, ai-governance, hipaa-ai Data catalog / governance — google-dataplex, aws-data-catalog, azure-purview, databricks-unity, snowflake-horizon Life sciences / clinical — glp1-obesity, glp1-muscle-loss, drug-interactions, dementia, icd10-metabolic, cpt-em-coding, hipaa-compliance, payer-formulary, modeling-healthcare-data, bioinformatics, genetics, biology STEM / math — calculus, pre-calc, algebra-1, linear-algebra, geometry-course, statistics-course, functions, intro-to-physics-course, chemistry, ecology, signal-processing, fft-benchmarking Engineering / CS — circuits, digital-electronics, computer-science, quantum-computing, machine-learning-textbook, langchain-core, claude-skills, data-science-course, it-management-graph, intro-to-graph AI / data / pedagogy — conversational-ai, prompt-class, tracking-ai-course, automating-instructional-design, microsims, infographics, modeling-healthcare-data Business / society / other — economics-course, personal-finance, organizational-analytics, ethics-course, theory-of-knowledge, systems-thinking, digital-citizenship, learning-linux, reading-for-kindergarten, us-geography, asl-book, moss, unicorns, blockchain

Need a domain we don't ship? Build your own CKG from a CSV, or ask about managed enterprise domains → graphifymd.com.

Compatibility

Works with any MCP client — Claude Desktop, Claude Code, Cursor, Cline, Windsurf — and any agent framework that speaks MCP (LangGraph, AutoGen, etc.). Model-agnostic: the graph is plain text, so it works equally with Claude, GPT, Llama, or a local model. Python ≥ 3.10, stdio transport, single dependency (mcp).

Commercial

The open package ships 65 domains under MIT. Managed enterprise domains (clinical, regulatory, financial), weekly delta updates, and pilot engagements are available through [Graphify.md](https://graphifymd.com).

License

MIT. Source learning graphs derive from the McCreary Intelligent Textbook Corpus.

Citation

@misc{yarmoluk2026ckg,
  title  = {Benchmarking Knowledge Retrieval Architectures Across Educational
            and Commercial Domains: RAG, GraphRAG, and Compressed (Compact) Knowledge Graphs},
  author = {Yarmoluk, Daniel and McCreary, Dan},
  year   = {2026},
  note   = {Pre-print in preparation. v0.6.2.}
}

Links: CKG Benchmark · Paper · Graphify.md