MCP Knowledge Viz

A knowledge-base chatbot with semantic search and interactive embedding visualisation, built as a hybrid of REST microservices (browser UI) and a proper MCP stdio server (Claude Desktop / Cursor integration).

Store facts in natural language, ask questions, and explore the embedding space in 2D (matplotlib) or interactive 3D (Plotly) — all backed by ChromaDB and SentenceTransformers.

Architecture Overview

Service architecture

The system has two independent access paths that share the same business logic:

Both layers delegate to `kb_core.py` — the single module that owns the ChromaDB client and the SentenceTransformer embedder. Neither layer duplicates data-access logic.

Key Design Principles

• Single source of truth for data access — only kb_core.py talks to ChromaDB. REST endpoints and MCP tools are thin wrappers.
• No HTTP for MCP — mcp_tools.py calls kb_core directly; the REST servers do not need to be running for an MCP client to use the tools.
• SOLID / Pydantic structure — the Visualization package uses typed Pydantic models at every boundary (EmbeddingPayload, VisualizationRequest, ReducedEmbeddings).

Diagrams

Module Structure

Module structure

QnA Request Flow (REST)

QnA request flow

Visualization Flow (2D + 3D)

Visualization flow

MCP Tools Flow (stdio)

MCP tools flow

Regenerating diagrams

plantuml -tsvg docs/architecture/uml/*.puml -o ../images
plantuml -tpng docs/architecture/uml/*.puml -o ../images

REST API Reference

Knowledge Base Server — port 8000

Central data service. Also serves the chatbot browser UI.

QnA Server — port 8001

Thin HTTP wrapper. Calls the KB server; no direct DB access.

Visualization Server — port 8002

Generates embedding plots via PCA dimensionality reduction.

MCP Tools Reference

mcp_tools.py is a FastMCP stdio server. Configure it in your MCP client and the three tools below appear automatically — no REST servers needed.

Connecting to Claude Desktop / Cursor

Copy mcp.json.example to mcp.json, fill in your absolute paths, then copy the mcpServers block into your client's config file:

• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json
• Cursor: ~/.cursor/mcp.json

// mcp.json.example — fill in your local paths
{
  "mcpServers": {
    "knowledge-viz": {
      "command": "/path/to/your/project/.venv/bin/python",
      "args": ["-m", "mcp_servers.mcp_tools"],
      "cwd": "/path/to/your/project"
    }
  }
}

mcp.json is gitignored because it contains absolute local paths. Always edit mcp.json.example for committed changes.

Getting Started

Prerequisites

• Python 3.11+
• PlantUML (optional, only to regenerate diagrams)

Setup

git clone <repository-url>
cd mcp-knowledge-viz

python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate

pip install -r requirements.txt

Run the REST + browser UI stack

chmod +x run_all.sh
./run_all.sh

Starts three servers:

Open http://127.0.0.1:8000/chatbot in your browser.

Visualisation tuning parameters

Project Structure

mcp-knowledge-viz/
├── app/
│   ├── static/
│   │   ├── chatbot.css        # Two-column layout, vis viewport
│   │   └── chatbot.js         # Fetch facts/QnA, Plotly 3D, spinner
│   └── templates/
│       └── chatbot.html       # Bootstrap 5 two-column UI
├── docs/
│   └── architecture/
│       ├── images/            # Generated SVG + PNG diagrams
│       └── uml/               # PlantUML sources
├── mcp_servers/
│   ├── kb_core.py             # ★ Shared ChromaDB + embedder logic
│   ├── knowledge_base_server.py  # REST :8000 — delegates to kb_core
│   ├── qna_server.py             # REST :8001 — HTTP wrapper
│   ├── visualization_server.py   # REST :8002 — delegates to visualization/
│   ├── mcp_tools.py           # ★ MCP stdio server (add_fact, ask, visualize)
│   └── visualization/
│       ├── models.py          # Pydantic models
│       ├── kb_client.py       # HTTP client → KB server
│       ├── reducer.py         # PCA 2D/3D
│       ├── renderer.py        # matplotlib (2D/3D static PNG)
│       ├── plotly_renderer.py # Plotly interactive 3D JSON
│       └── service.py         # Orchestrator
├── chroma_db/                 # Persistent vector store (gitignored)
├── mcp.json                   # Local MCP config (gitignored)
├── mcp.json.example           # Template — commit this, not mcp.json
├── run_all.sh                 # Start all three REST servers
└── requirements.txt

Tech Stack