KB-MCP Server

A local-first Knowledge Base with Model Context Protocol (MCP) support. Give your AI a reliable memory. Run it locally. Stream answers in real time.

---

What is This?

A Knowledge Base (KB) is a structured collection of facts, documents, and embeddings stored in machine-readable form, with interfaces to:

• Add knowledge
• Query knowledge (semantic + keyword search)
• Update/Delete knowledge

This MCP server exposes your KB to any MCP-compatible AI client (Claude, custom agents, etc.).

---

Why Local-First?

Benefit	Description
Privacy	No cloud leaks — your data stays on your machine
Zero latency	No network round-trips
Offline support	Works without internet
Full control	You own the data and the logic
No vendor lock-in	Swap components freely

---

Quick Start

Installation

npm install
npm run build

Run the Server

npm start

Or for development:

npm run dev

Configure with Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "knowledge-base": {
      "command": "node",
      "args": ["/path/to/kb-mcp-server/dist/index.js"],
      "env": {
        "KB_DATA_DIR": "/path/to/your/data"
      }
    }
  }
}

---

Available Tools

Tool	Description
ingest_document	Add a document with title, content, and metadata
query_knowledge	Semantic search across all documents
list_documents	List documents with pagination
get_document	Get full document by ID
update_document	Update existing document
delete_document	Remove document from KB
kb_stats	Get knowledge base statistics

---

How It Works

1. User asks a question
       ↓
2. AI sends MCP query → KB-MCP Server
       ↓
3. KB retrieves relevant facts (semantic search)
       ↓
4. AI grounds the answer with real data
       ↓
5. Response streams to user
       ↓
6. (Optional) New insights stored back

Result: AI answers correctly. Knowledge compounds. No hallucinations.

---

Architecture

┌─────────────────┐
│   AI Client     │
│ (Claude, Agent) │
└────────┬────────┘
         │ MCP Protocol
         ↓
┌─────────────────┐
│  KB-MCP Server  │  ← stdio transport
│  ┌───────────┐  │
│  │  Tools    │  │  ingest | query | list | delete
│  └─────┬─────┘  │
│        ↓        │
│  ┌───────────┐  │
│  │  Engine   │  │  Embeddings + Similarity Search
│  └─────┬─────┘  │
│        ↓        │
│  ┌───────────┐  │
│  │   Store   │  │  JSON file (swap with Chroma/pgvector)
│  └───────────┘  │
└─────────────────┘

---

Configuration

Environment Variable	Default	Description
KB_DATA_DIR	./.kb-data	Directory for storing knowledge base data

---

Production Enhancements

For production use, consider:

1. Real embeddings: Replace hash-based embeddings with OpenAI, Cohere, or local models (Ollama)
2. Vector database: Swap JSON store with Chroma, Qdrant, or pgvector
3. Chunking: Split large documents into chunks for better retrieval
4. Hybrid search: Combine semantic + BM25 keyword search
5. Access control: Add authentication for multi-user setups

---

License

MIT — Use freely.

---

Author

Matrix Agent