🧠 Knowledge MCP Server

The High-Performance, Local-First Second Brain & Knowledge Base for AI Agents

English • Tiếng Việt • Roadmap • Setup Guide

💡 What is Knowledge MCP?

Knowledge MCP Server is a blazing-fast, local-first Knowledge Management & Retrieval-Augmented Generation (RAG) system exposed via the open Model Context Protocol (MCP) standard.

It empowers AI coding assistants and autonomous agents (Antigravity IDE / CLI, Claude Code, Cursor, ChatGPT / Codex, Windsurf) to seamlessly search, read, create, and maintain your personal or enterprise knowledge vault with zero cloud dependencies and zero data leakage.

┌─────────────────┐       Streamable HTTP       ┌──────────────────────────────────────┐
│  AI Assistants  │ ──────────────────────────> │        Knowledge MCP Server          │
│ (Antigravity /  │                             │ ┌──────────────────────────────────┐ │
│  Claude / Cursor│ <────────────────────────── │ │ Hybrid Search (BM25 + Vector)    │ │
└─────────────────┘                             │ │ Anthropic Contextual Retrieval   │ │
                                                │ │ Heading-Aware Markdown Chunker   │ │
                                                │ │ Native SQLite FTS5 (Zero C++ bld)│ │
                                                │ └──────────────────────────────────┘ │
                                                └──────────────────────────────────────┘

Related MCP server: RAGDown

✨ Key Highlights

• ⚡ Native SQLite & FTS5 (Zero C++ Build Hell): Built on Node.js native node:sqlite (DatabaseSync). Starts in milliseconds without compilation errors on Windows, macOS, or Linux.

• 🎯 Hybrid Search with RRF (k=60): Combines exact keyword matching (SQLite FTS5 BM25) with semantic understanding (Dense Vector Cosine Similarity) using Reciprocal Rank Fusion for pinpoint technical accuracy.

• 🧩 Heading-Aware Markdown Chunking: Intelligently parses document structure along H1 > H2 > H3 hierarchy, preserving YAML Frontmatter metadata (gray-matter) without breaking context.

• 🧬 Anthropic Contextual Retrieval: Generates succinct context annotations for each chunk before embedding, drastically reducing ambiguity and retrieval hallucinations.

• 🔄 Incremental Ingestion (SHA256 Diffing): Reindexes only modified chunks, saving computing power and embedding latency.

• ⚡ 1-Click All-in-One Setup (setup-and-run.bat): Automated setup script that prepares environment, builds, indexes, configures Antigravity rules, and starts the server in 30 seconds.

• 🛡️ Autonomous Agent Policy: Built-in rules and tool descriptions that prompt agents to automatically search your knowledge vault before answering technical queries.

📊 Feature Comparison Matrix

🏗️ System Architecture

graph TD
    subgraph "AI Clients"
        AG[Antigravity IDE / CLI]
        CC[Claude Code / Desktop]
        CX[Codex / Cursor / Others]
    end

    subgraph "Knowledge MCP Server (:3900)"
        AUTH[Bearer Auth Middleware]
        HTTP[Streamable HTTP Transport - /mcp]
        TOOLS[MCP Tools Registry - 8 Tools]
        
        subgraph "Core Intelligence Engines"
            HYBRID[Hybrid Search Engine - RRF k=60]
            INGEST[Incremental Ingestion Pipeline]
            CHUNKER[Heading-Aware Markdown Chunker]
            EMBED[Vector Embedder - 9router / Ollama / OpenAI]
            CTX[Anthropic Contextualizer]
        end

        subgraph "Local Storage Layer"
            DB[(SQLite Database - knowledge.db)]
            FTS[FTS5 BM25 Full-Text Index]
            VEC[Float32 Vector BLOBs]
            VAULT[Vault Files - data/raw/*.md]
        end
    end

    AG -->|HTTP POST /mcp| AUTH
    CC -->|HTTP POST /mcp| AUTH
    CX -->|HTTP POST /mcp| AUTH

    AUTH --> HTTP --> TOOLS
    TOOLS --> HYBRID
    TOOLS --> INGEST
    
    HYBRID --> FTS
    HYBRID --> VEC
    
    INGEST --> CHUNKER --> CTX --> EMBED
    INGEST --> DB
    INGEST --> VAULT

🚀 Quick Start (30 Seconds)

Option 1: 1-Click All-in-One Launcher (Windows)

Double-click setup-and-run.bat at the root of the project:

.\setup-and-run.bat

The script automatically verifies Node.js, connects to your embedding gateway (e.g. 9router/Ollama), builds TypeScript, indexes your vault, registers Antigravity MCP configs, and launches the server!

Option 2: Manual Step-by-Step Setup

1. Clone the repository:

   git clone https://github.com/your-username/knowledge-mcp.git
   cd knowledge-mcp

2. Install dependencies:

   npm install

3. Configure environment (.env):

   cp .env.example .env

   Sample .env configuration:

   VAULT_DIR=./data/raw
   DB_PATH=./db/knowledge.db
   PORT=3900
   
   # Embedding (Ollama or 9router OpenAI-compatible endpoint)
   EMBEDDING_BASE_URL=http://localhost:11434/v1
   EMBEDDING_MODEL=nomic-embed-text
   EMBEDDING_API_KEY=ollama
   EMBEDDING_DIM=768
   
   # Anthropic Contextual Retrieval (Optional)
   CONTEXTUAL_RETRIEVAL_ENABLED=false
   CHAT_BASE_URL=https://api.openai.com/v1
   CHAT_MODEL=gpt-4o-mini
   CHAT_API_KEY=your-key
   
   # Authentication (Optional for remote deployments)
   MCP_AUTH_TOKEN=

4. Index your knowledge documents: Drop your Markdown files into data/raw/ and run:

   npm run reindex

5. Start the MCP server:

   npm run build
   npm start

   Server endpoint: http://localhost:3900/mcp | Health check: http://localhost:3900/health.

🛠️ MCP Tool Reference

Knowledge MCP exposes 8 production-ready tools:

🔌 Connecting to AI Clients

1. Antigravity IDE / CLI

Add to ~/.gemini/config/mcp_config.json:

{
  "mcpServers": {
    "knowledge-vault": {
      "serverUrl": "http://localhost:3900/mcp"
    }
  }
}

2. Claude Code & Claude Desktop

Add to .mcp.json or claude_desktop_config.json:

{
  "mcpServers": {
    "knowledge-vault": {
      "type": "streamable-http",
      "url": "http://localhost:3900/mcp"
    }
  }
}

3. Cursor & VS Code

Under IDE Settings > Features > MCP:

• Name: knowledge-vault

• Type: Streamable HTTP / SSE

• URL: http://localhost:3900/mcp

🧪 Testing

Run comprehensive unit and integration tests:

# Run all test suites (DB, Chunker, Search, MCP Server)
npm run test:all

🗺️ Roadmap

Check out our ROADMAP.md for upcoming milestones:

• ⚡ Phase 1: Real-Time Live File Watcher (chokidar).

• ✂️ Phase 2: Surgical Note Editing (update_section, patch_frontmatter).

• 📄 Phase 3: Multi-Format Parsing (PDF, Word, Excel).

• 🎯 Phase 4: Cross-Encoder Re-Ranking Pipeline.

• 🖥️ Phase 5: Local Web Dashboard & RAG Playground.

📜 License & Contribution

Distributed under the MIT License. Contributions, issues, and feature requests are welcome!