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):

Tool	Signature	What it does
list_domains	list_domains()	List all available CKG domains. Call this first.
query_ckg	query_ckg(domain, concept, depth=3)	Extract the subgraph around a concept — related concepts up to depth hops.
get_prerequisites	get_prerequisites(domain, concept)	The full prerequisite chain — everything to understand first.
search_concepts	search_concepts(domain, query)	Find concepts in a domain by name.

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):

	CKG	RAG	GraphRAG
Macro-F1	0.47	0.12	0.12
Tokens / query	269	2,982	3,450
F1 @ 5 hops	0.772	0.170	—
Fabricated edges	0 by construction	variable	variable

• 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:

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.

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