knowledge-graph-mcp

Knowledge Graph MCP Server

An MCP (Model Context Protocol) server for tracking student learning via a knowledge graph. Built with FastMCP, it enables LLMs to build, query, and update a personalized knowledge map with spaced repetition scheduling.

Features

• Knowledge Graph Storage: SQLite-backed graph with concepts as nodes and relationships as edges
• Multi-dimensional Mastery Tracking: Track recall, application, and explanation abilities separately
• Spaced Repetition (SM-2): Automatic scheduling of review sessions based on performance
• Misconception Tracking: Record and query common misconceptions for targeted remediation
• Intelligent Queries: Find knowledge gaps, ready-to-learn concepts, struggling areas
• Mermaid Visualization: Generate visual diagrams of the knowledge graph

Installation

Option 1: Install from Smithery (Recommended)

Install directly via Smithery:

npx @smithery/cli install @zcsabbagh/knowledge-graph-mcp --client claude

Or use the hosted version at: https://smithery.ai/server/@zcsabbagh/knowledge-graph-mcp

Option 2: Install from source

Prerequisites: Python 3.10+

git clone https://github.com/zcsabbagh/knowledge-graph-mcp.git
cd knowledge-graph-mcp
pip install -e .

Usage

Running the Server

# From the project root
python -m knowledge_graph_mcp.server

Configure with Claude Code

Add to your Claude Code MCP settings (~/.claude/settings.json):

{
  "mcpServers": {
    "knowledge-graph": {
      "command": "python",
      "args": ["-m", "knowledge_graph_mcp.server"],
      "cwd": "/path/to/knowledge-graph-mcp"
    }
  }
}

Configure with Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "knowledge-graph": {
      "command": "python",
      "args": ["-m", "knowledge_graph_mcp.server"],
      "cwd": "/path/to/knowledge-graph-mcp"
    }
  }
}

MCP Tools

1. add_node

Create a new concept node.

add_node(
  concept="Quadratic Formula",
  description="Formula for solving ax² + bx + c = 0",
  domain="mathematics",
  difficulty=0.7,
  tags=["algebra", "formulas"]
)

2. add_edge

Create relationships between concepts.

Relation types:

• prerequisite - Must learn source before target
• builds_on - Target extends source concept
• related_to - Concepts are connected
• contradicts - Common misconception
• applies_to - Application domain
• parent_of - Category hierarchy

add_edge(
  source_concept="Algebra",
  target_concept="Quadratic Formula",
  relation_type="prerequisite"
)

3. update_node

Update mastery and record reviews. Providing a quality rating (0-5) triggers spaced repetition scheduling.

update_node(
  node_id="quadratic_formula",
  quality=4,  # SM-2 rating: 0=blackout, 5=perfect
  mastery_application=0.6,
  misconception_detected="forgets ± sign"
)

4. query_graph

Intelligent queries for learning insights.

Query types:

• prerequisites - All prerequisites for a concept
• ready_to_learn - Concepts where prereqs are mastered
• due_for_review - Needs review based on schedule
• struggling - High difficulty + low mastery
• stalled - Multiple reviews, no improvement
• misconceptions - Concepts with detected misconceptions
• knowledge_gaps - Low mastery blocking progress
• next_recommended - Best concept to study next

query_graph(query_type="next_recommended", domain="mathematics")

5. read_subgraph

Get the neighborhood around a concept with Mermaid visualization.

read_subgraph(
  center_node="calculus",
  depth=2,
  direction="upstream",  # or "downstream", "both"
  output_format="both"   # "json", "mermaid", or "both"
)

6. get_learning_path

Get ordered prerequisites for a target concept.

get_learning_path(target_concept="calculus")

7. get_statistics

Get learning progress metrics.

get_statistics(domain="mathematics")

How It Works

Data Model

Nodes represent concepts with:

• Mastery levels (overall, recall, application, explanation)
• Spaced repetition data (ease factor, interval, next review date)
• Difficulty rating and review history
• Tags and detected misconceptions

Edges represent relationships with:

• Relation type (prerequisite, builds_on, etc.)
• Strength/confidence rating
• Optional reasoning

Spaced Repetition (SM-2)

When you call update_node with a quality rating:

• 5: Perfect response → longer interval
• 4: Correct with hesitation
• 3: Correct with difficulty
• 2-0: Incorrect → reset interval

The algorithm calculates the next optimal review date based on performance history.

Mastery Calculation

Overall mastery combines dimensional scores:

mastery_level = 0.3 × recall + 0.4 × application + 0.3 × explanation

Storage

Data is stored in SQLite at ~/.knowledge_graph/knowledge.db by default.

Example Workflow

1. LLM discovers student doesn't know "quadratic formula"
   → add_node(concept="Quadratic Formula", difficulty=0.7)

2. LLM identifies prerequisites
   → add_edge("Algebra", "Quadratic Formula", "prerequisite")

3. Student attempts problem, struggles
   → update_node("quadratic_formula", quality=2,
                 misconception_detected="confuses ± with +")

4. LLM decides what to teach next
   → query_graph("next_recommended")

5. Visualize the learning path
   → get_learning_path("quadratic_formula")

License

MIT