io.github.zcsabbagh/knowledge-graph-mcp
Knowledge graph MCP for student learning with spaced repetition and mastery tracking
Open source Open in the app JSON README (API)
About
Knowledge graph MCP for student learning with spaced repetition and mastery tracking
Details
- Kind
- MCP servers
- Topic
- AI, RAG & memory
- Publisher
- zcsabbagh
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.1.0
- Stars
- 1
- Last push
- 2025-12-30T05:24:11Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-29 04:01:43
- Updated
- 2026-08-29 04:01:43
- Origin id
io.github.zcsabbagh/knowledge-graph-mcp
README
<!-- mcp-name: io.github.zcsabbagh/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](https://smithery.ai):
```bash
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+
```bash
git clone https://github.com/zcsabbagh/knowledge-graph-mcp.git
cd knowledge-graph-mcp
pip install -e .
```
## Usage
### Running the Server
```bash
# From the project root
python -m knowledge_graph_mcp.server
```
### Configure with Claude Code
Add to your Claude Code MCP settings (`~/.claude/settings.json`):
```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`:
```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