MCP Server¶

The knowledgespaces MCP server lets you use Knowledge Space Theory directly from Claude, ChatGPT, or any MCP-compatible AI assistant. No Python code needed — the LLM calls the tools for you.

What is MCP?

The Model Context Protocol (MCP) is an open standard that allows AI assistants to use external tools, read data sources, and follow guided workflows. Think of it as a plugin system for LLMs.

What the server provides¶

Tools (7)¶

The server exposes all core KST operations as callable tools:

Tool	Description
`build_structure`	Build a knowledge structure from prerequisite pairs
`build_structure_from_skills`	Derive structure from a skill map (CB-KST)
`fit_blim_model`	Estimate BLIM parameters from response data via EM
`assess_student`	Assess a student’s knowledge state from responses
`select_next_question`	Pick the next optimal question (EIG-based adaptive)
`inspect_structure`	Analyze structure: atoms, base, paths, properties
`plot_hasse`	Generate a Hasse diagram (PNG image)

All tools are stateless: knowledge structures and fit results are passed as JSON between calls. The LLM orchestrates multi-step workflows by chaining tool calls.

Documentation Resources (13)¶

The server exposes the full library documentation as MCP resources. The LLM can read any documentation page on demand using docs://{topic}:

docs://getting-started — Quick start guide
docs://guide-structures — Knowledge structures
docs://guide-assessment — Student assessment
docs://guide-estimation — Parameter estimation
docs://guide-derivation — CB-KST derivation
docs://guide-query — QUERY algorithm
docs://guide-io — CSV and JSON I/O
docs://guide-metrics — Comparison metrics
docs://guide-cli — Command-line interface
docs://theory-foundations — KST foundations
docs://theory-blim — BLIM theory
docs://theory-query-algorithm — QUERY algorithm theory
docs://api — API reference

This means the LLM always has access to up-to-date documentation, making it useful both for executing KST operations and for development assistance (writing code that uses the library).

Prompt Templates (4)¶

Pre-built workflows for common tasks:

Prompt	Description
`kst_tutorial`	Full step-by-step KST tutorial with a custom domain
`assess_student_workflow`	Guided student assessment pipeline
`design_structure`	Design a knowledge structure for a course
`adaptive_assessment`	Interactive adaptive assessment session

Installation¶

1. Create a dedicated environment¶

python3 -m venv ~/.knowledgespaces-mcp
~/.knowledgespaces-mcp/bin/pip install fastmcp

2. Install knowledgespaces¶

From source (until published on PyPI):

~/.knowledgespaces-mcp/bin/pip install -e /path/to/knowledgespaces[viz]

From PyPI (when available):

~/.knowledgespaces-mcp/bin/pip install knowledgespaces[viz]

3. Verify¶

~/.knowledgespaces-mcp/bin/python3 -c "import knowledgespaces; from fastmcp import FastMCP; print('OK')"

Configuration¶

Claude Desktop¶

Open Settings > Developer > Edit Config and add:

{
  "mcpServers": {
    "knowledgespaces": {
      "command": "~/.knowledgespaces-mcp/bin/python3",
      "args": ["/path/to/knowledgespaces/mcp/server.py"]
    }
  }
}

Restart Claude Desktop. You should see the hammer icon with 7 tools.

Claude Code (CLI / VS Code)¶

Add to .mcp.json in your project root:

{
  "mcpServers": {
    "knowledgespaces": {
      "command": "~/.knowledgespaces-mcp/bin/python3",
      "args": ["/path/to/knowledgespaces/mcp/server.py"]
    }
  }
}

Testing with FastMCP Inspector¶

For development and debugging, use the interactive inspector:

fastmcp dev mcp/server.py

This opens a browser UI where you can call tools, read resources, and test prompts interactively.

Usage examples¶

Once configured, interact naturally with the LLM:

Build a structure:

“Build a knowledge structure for arithmetic with items: addition, subtraction, multiplication, division. Addition is prerequisite for subtraction, subtraction for multiplication, multiplication for division.”

Assess a student:

“Assess a student who got addition and subtraction correct but multiplication and division wrong.”

Adaptive assessment:

“Run an adaptive assessment — ask me one question at a time and converge on the student’s knowledge state.”

Consult documentation:

“Read the BLIM theory documentation and explain how slip and guess parameters work.”

Use a prompt template:

“Use the kst_tutorial prompt to walk me through KST with a programming skills example.”

Architecture¶

LLM  <-->  MCP Protocol  <-->  server.py  <-->  knowledgespaces
                                   |
                                   |-- Tools (7): execute KST operations
                                   |-- Resources (13): library documentation
                                   '-- Prompts (4): workflow templates

The server uses FastMCP and communicates via stdio transport. All tool inputs and outputs are JSON-serializable.

Knowledge structures are represented as:

{
  "domain": ["add", "sub", "mul"],
  "states": [[], ["add"], ["add", "sub"], ["add", "sub", "mul"]]
}

This JSON travels between tool calls, keeping the server completely stateless. The LLM manages the conversation state.