# 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

```bash
npm install
npm run build
```

### Run the Server

```bash
npm start
```

Or for development:

```bash
npm run dev
```

### Configure with Claude Desktop

Add to your `claude_desktop_config.json`:

```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