Skip to main content
Glama

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: codegraph-mcp

πŸ“– How to talk to your AI?

If you're wondering how exactly you should prompt your AI (Claude, Antigravity, Cursor) to make use of these superpowers, check out our Prompt Library (PROMPTS.md) for copy-pasteable examples!


πŸ› οΈ Exposed MCP Tools

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

Tool

Description

Token Impact

πŸ” semantic_search

Finds relevant code symbols based on a natural language query or keywords.

Low

πŸ•ΈοΈ graph_query

Returns the blast radius of a specific symbol based on the AST Call-Graph.

Low

πŸ“– surgical_read

Extracts only the exact code snippet for a single function or class.

Massive Savings

πŸ—οΈ apply_surgical_patch

Replaces an exact code symbol with new code and triggers a background re-index.

Low

πŸ”„ rebuild_index

Manually triggers a complete re-indexing of the entire workspace.

None


πŸš€ Installation & Setup

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

# 1. Clone the repository
git clone https://github.com/FreakyLetsFail/mcp-omniscience.git
cd mcp-omniscience

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

πŸ“¦ Standalone CLI Indexer (For Large Repositories)

To prevent your IDE and OS from freezing when opening a massive repository for the first time, Omniscience comes with a standalone CLI tool. It builds the AST Call-Graph and Semantic Vector Database efficiently in the background before you even start your AI.

./index.sh index /path/to/your/large/project

This creates a .omniscience folder directly inside your project containing the LanceDB and SQLite databases.

πŸ”Œ 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": []
    }
  }
}
TIP

No initialization prompt required! When the MCP server starts in a new WORKSPACE_DIR, it automatically builds the vector and graph databases in the background.


πŸ’° 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.


Available Tools

6 tools
apply_surgical_patchA

Replace an existing symbol with entirely new code. Re-indexing is automatic.

Inputs: new_code (required), symbol_id (required). Returns: result

get_index_statusB

Check the status of the background indexing process.

Inputs: no named parameters. Returns: result

graph_queryA

Find the blast radius (which functions call this symbol).

Inputs: symbol_id (required). Returns: result

rebuild_indexC

Manually trigger a complete re-indexing. Provide a 'path' to change the workspace directory.

Inputs: path. Returns: result

surgical_readA

Read only the exact code lines of a specific symbol_id (e.g. 'src/app.py::main').

Inputs: symbol_id (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: indexing status, hybrid search, dependency graph, reading specific symbols, patching symbols, and index rebuild. There is no overlap or ambiguity between them.

    Naming Consistency3/5

    Tool names follow a mix of noun_noun (semantic_search, graph_query) and verb_noun (get_index_status, apply_surgical_patch, rebuild_index) patterns, with inconsistent use of adjectives (surgical_read). While clear, they lack a uniform convention.

    Tool Count5/5

    With 6 tools, the server is well-scoped for codebase analysis and modification. Each tool serves a necessary function without being overly numerous or sparse.

    Completeness4/5

    The tools cover key workflows: indexing, searching, dependency analysis, reading, and patching. A minor gap is the lack of a direct way to list all symbols or navigate the codebase beyond search, but this is manageable.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables LLM agents to efficiently understand and navigate a codebase by providing semantic search over symbols and a reference graph, replacing expensive grep/glob calls with structured tools like definition lookup, caller/callee queries, and change-impact analysis.
      19 PyPI
      4
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables symbol-level codebase retrieval, providing definitions and usages of symbols to agents without reading whole files.
      7 npm
      ISC
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to retrieve precise symbol definitions and usages from codebases, eliminating the need to fetch entire files.
      7 npm
      2
      ISC