Omniscience

Omniscience is a highly optimized Model Context Protocol (MCP) server designed to give Large Language Models (LLMs) token-efficient, surgical access to massive codebases. Instead of flooding the LLM's context window with entire repositories, Omniscience uses a sophisticated Dual-Brain architecture to find exactly what the LLM needs—and absolutely nothing more.

🧠 The Dual-Brain Architecture

graph TD
    A[Codebase] -->|Real-time watcher| B(Omniscience Scanner)
    B -->|Code| C{Dual-Brain Parser}
    
    subgraph Structural Brain
    C -->|AST Parsing| D[Tree-Sitter]
    D -->|Function Definitions & Calls| E[(SQLite Graph DB)]
    end
    
    subgraph Semantic Brain
    C -->|Text/Code| F[Voyage-4-nano]
    F -->|Local Embeddings| G[(LanceDB Vector DB)]
    end
    
    E -.->|Graph Query| H[MCP Client]
    G -.->|Semantic Search| H

1. Structural Brain (Tree-sitter)

Parses the AST (Abstract Syntax Tree) of your codebase in real-time. It maps out exact file locations, boundary lines for functions/classes, and automatically generates a complete Call-Graph (Caller -> Callee relationships) stored in a local SQLite database.

2. Semantic Brain (LanceDB & Voyage-4-nano)

Generates and stores high-quality semantic embeddings of every code symbol completely locally. Allows the LLM to search for abstract concepts ("how does the auth routing work?") using lightning-fast hybrid search.

Related MCP server: MCP Context Manager

🛠️ Exposed MCP Tools

The server exposes powerful tools to the AI, allowing it to navigate your project like a senior engineer.

🚀 Installation & Setup

Omniscience is designed to be ridiculously fast. We use uv for lightning-fast dependency resolution.

# 1. Clone the repository
# git clone <repo-url>
cd mcp-omniscience

# 2. Run the Initialization Script (Downloads model, syncs env)
./init.sh

IDE Integration

Add Omniscience to your MCP client configuration (mcp_config.json, claude_desktop_config.json, etc.):

{
  "mcpServers": {
    "omniscience": {
      "command": "/path/to/mcp-omniscience/run_server.sh",
      "args": []
    }
  }
}

💰 Token Cost Analysis

Why use Omniscience over traditional whole-file reading?

• Full File Read (server.py): ~911 Tokens

• Omniscience Surgical Read (1 function): ~117 Tokens

• Context Window Saved: 87.16% per interaction!

By isolating exactly what is needed, the LLM hallucinates less, replies faster, and drastically reduces API costs.