# Naviscope

> Unified Code Knowledge Graph Engine for AI Agents & Developers

- **Type:** MCP server
- **Install:** `agentstack add mcp-biuld-naviscope`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [biuld](https://agentstack.voostack.com/s/biuld)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [biuld](https://github.com/biuld)
- **Source:** https://github.com/biuld/naviscope

## Install

```sh
agentstack add mcp-biuld-naviscope
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Naviscope

**Unified Code Knowledge Graph Engine for AI Agents & Developers**

Naviscope bridges the gap between AI and IDEs. It builds a comprehensive, graph-based representation of your codebase (connecting micro-level semantics like type relationships and inheritance with macro-level structures) that powers both **LLM agents** (via MCP) and **code editors** (via LSP).

Unlike traditional tools that maintain separate indexes for different purposes, Naviscope provides a **single, unified knowledge graph**, ensuring that what AI agents see is exactly what developers navigate.

## 💡 Why Naviscope?

| Feature | Traditional Tools | Naviscope |
| :--- | :--- | :--- |
| **Context** | Text-based (regex/grep) | **Graph-based** (structural/semantic) |
| **Performance** | High latency (JVM based) | **Instant** (Rust native, Zero-JVM overhead) |
| **Consistency** | Fragmented (Agent vs IDE) | **Unified** (Same graph for both) |
| **Resilience** | Blocks on errors/missing deps | **Robust** (Works with partial/broken code) |

## 🌟 Capabilities

### 🤖 For AI Agents (MCP Support)
Naviscope implements the [Model Context Protocol](https://modelcontextprotocol.io/), giving LLMs "X-ray vision" into your code structure.

- **`get_guide`**: Call this first! Get a comprehensive guide on how to use Naviscope tools.
- **`ls`**: Hierarchical exploration of packages, modules, and fields.
- **`find`**: Precise symbol search (find "Class definitions", not just string matches).
- **`cat`**: Retrieve definition, source code, and metadata for any symbol.
- **`deps`**: Analyze incoming/outgoing dependencies and relationships (inheritance, type usage, etc.).

### 👨‍💻 For Developers (LSP Support)
A lightweight, lightning-fast alternative to standard language servers (like JDTLS).

- **Navigation**: Go to Definition, Find References, Go to Implementation.
- **Understanding**: Hover documentation, Document Highlights.
- **Hierarchy**: Call Hierarchy, Type Hierarchy.
- **Speed**: Works immediately on large projects without long indexing pauses.

## 🏗️ Architecture

```mermaid
graph TD
    %% Styles
    classDef interface fill:#e3f2fd,stroke:#1565c0,stroke-width:2px,rx:5,ry:5
    classDef runtime fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,rx:5,ry:5
    classDef language fill:#e8f5e9,stroke:#2e7d32,stroke-width:2px,rx:5,ry:5
    classDef plugin fill:#fff9c4,stroke:#fbc02d,stroke-width:2px,rx:5,ry:5
    classDef core fill:#fff3e0,stroke:#ef6c00,stroke-width:2px,rx:5,ry:5
    classDef api fill:#fafafa,stroke:#616161,stroke-width:2px,rx:5,ry:5

    subgraph Interfaces [Interface Layer]
        CLI["naviscope-cli(Shell & Main)"]:::interface
        LSP["naviscope-lsp(LSP Server)"]:::interface
        MCP["naviscope-mcp(MCP Server)"]:::interface
    end

    subgraph Orchestration [Runtime Layer]
        Runtime["naviscope-runtime(Engine Orchestrator)"]:::runtime
    end

    subgraph Strategies [Language Layer]
        Java["naviscope-java(Java Analysis)"]:::language
        Gradle["naviscope-gradle(Gradle Analysis)"]:::language
    end

    subgraph Abstraction [Plugin Layer]
        Plugin["naviscope-plugin(Traits & Contracts)"]:::plugin
    end

    subgraph Engine [Core Layer]
        Core["naviscope-core(Graph, Index & IO)"]:::core
    end

    subgraph Foundation [API Layer]
        API["naviscope-api(Common Traits & Models)"]:::api
    end

    %% Crate Dependencies
    CLI --> LSP
    CLI --> MCP
    CLI --> Runtime
    CLI --> API

    LSP --> MCP
    LSP --> API

    MCP --> API

    Runtime --> Java
    Runtime --> Gradle
    Runtime --> Core
    Runtime --> API

    Java --> Plugin
    Java --> API

    Gradle --> Plugin
    Gradle --> API

    Core --> Plugin
    Core --> API

    Plugin --> API
```

Naviscope is built on a **layered crate architecture** that separates concerns across multiple Rust crates:

- **Interface Layer** (`naviscope-cli`, `naviscope-lsp`, `naviscope-mcp`): Entry points for different use cases (CLI shell, LSP for editors, MCP for AI agents).
- **Runtime Layer** (`naviscope-runtime`): Orchestrates the engine assembly, registering language plugins and providing a unified factory.
- **Language Layer** (`naviscope-java`, `naviscope-gradle`): Language-specific implementations that implement the standard plugin contracts.
- **Plugin Layer** (`naviscope-plugin`): Defines capability traits (parse/indexing/runtime/asset/presentation/metadata) that decouple Core from language-specific implementations.
- **Core Layer** (`naviscope-core`): The heart of the system - graph storage, indexing, file scanning, and persistence. It consumes the plugin traits to process files.
- **API Layer** (`naviscope-api`): Common traits and models shared across all crates, ensuring a consistent interface.

The core is a language-agnostic graph structure populated by language-specific strategies (currently Java/Gradle via Tree-sitter), exposing a unified query engine to both AI agents and developer tools.

### Trait Organization

Naviscope's trait design is split into two layers: engine-facing API traits (`naviscope-api`) and language capability traits (`naviscope-plugin`).

```mermaid
graph TB
    subgraph A["Layer 1: Engine API (`naviscope-api`)"]
        APIComposite["API CompositeNaviscopeEngine"]
        APIServices["API ServicesGraphService | NavigationServiceSymbolNavigator | ReferenceAnalyzerCallHierarchyAnalyzer | SymbolInfoProviderEngineLifecycle | StubCacheManager"]
    end

    subgraph B["Layer 2: Runtime Semantics (`naviscope-plugin`)"]
        RuntimeSemantic["Runtime Semantic CapSemanticCap"]
        RuntimeServices["Semantic ServicesSymbolResolveService | SymbolQueryServiceLspSyntaxService | ReferenceCheckService"]
    end

    subgraph C["Layer 3: Parse & Index (`naviscope-plugin`)"]
        ParseCap["Parse CapFileMatcherCap | LanguageParseCap | BuildParseCap"]
        IndexCap["Index CapSourceIndexCap | BuildIndexCap | ProjectContext"]
    end

    subgraph D["Layer 4: Asset & Output (`naviscope-plugin`)"]
        AssetCap["Asset Cap"]
        PresentationCap["Presentation Cap"]
        MetadataCodecCap["Metadata Codec Cap"]
    end

    APIComposite --> APIServices
    APIServices --> RuntimeSemantic
    RuntimeSemantic --> RuntimeServices

    RuntimeServices --> ParseCap
    RuntimeServices --> IndexCap
    ParseCap --> IndexCap

    IndexCap --> AssetCap
    RuntimeServices --> PresentationCap
    RuntimeServices --> MetadataCodecCap
```

#### `naviscope-api` service traits

- `GraphService`: graph query, stats, and node display retrieval.
- `NavigationService`: CLI-style path resolution and completion.
- `SymbolNavigator`: resolve/go-to-definition/type-definition/implementation/highlights.
- `ReferenceAnalyzer`: find references.
- `CallHierarchyAnalyzer`: incoming/outgoing calls.
- `SymbolInfoProvider`: symbol info, document symbols, language detection.
- `EngineLifecycle`: rebuild/load/save/refresh/watch/clear.
- `StubCacheManager`: cache stats/scan/inspect/clear.
- `NaviscopeEngine`: composite trait that bundles all service traits above.

#### `naviscope-plugin` capability traits

- File routing and parsing: `FileMatcherCap`, `LanguageParseCap`, `BuildParseCap`.
- Indexing: `SourceIndexCap`, `BuildIndexCap`.
- Runtime semantics: `SymbolResolveService`, `SymbolQueryService`, `LspSyntaxService`, `ReferenceCheckService` (grouped by `SemanticCap`).
- Asset integration: `AssetCap` (discover/index/source-locate/stub-generate).
- Output shaping: `PresentationCap`, `MetadataCodecCap`.

This split keeps runtime interfaces stable for clients while allowing per-language capability composition internally.

### 🔍 Reference Discovery Strategy

Naviscope uses a **two-phase reference discovery** approach for optimal performance:

1. **Meso-level (Coarse Filtering)**: Uses an inverted `reference_index` (token → files) to quickly identify candidate files that likely contain references to a symbol. This index is built during parsing by extracting all identifier tokens from source files.

2. **Micro-level (Precise Analysis)**: For each candidate file, uses Tree-sitter to parse and verify actual symbol occurrences, ensuring accurate reference locations.

This hybrid approach combines the speed of inverted indexing with the precision of syntax-aware parsing, enabling fast reference discovery even in large codebases.

## 🚀 Quick Start

### Prerequisites
- Rust (2024 edition)

### Installation from source code

```bash
# 1. Clone
git clone https://github.com/biuld/naviscope.git
cd naviscope

# 2. Install the Naviscope CLI
cargo install --path crates/cli

# 3. (Optional) Build the VS Code Extension
cd editors/vscode
npm install
npm run package
# Then install the generated .vsix file in VS Code
```

### Usage

#### CLI Commands
- `naviscope index `: Build a persistent index for a project.
- `naviscope shell [PATH]`: Start an interactive shell to query the graph.
- `naviscope watch `: Start a background service to keep the index updated.
- `naviscope clear [PATH]`: Clear built indices (or all indices if path omitted).
- `naviscope mcp`: Start the MCP server.
- `naviscope lsp`: Start the LSP server.

#### Configure in Cursor (for AI Agents)
1.  Open **Cursor Settings** (Cmd + Shift + J) -> **Features** -> **MCP**.
2.  Click **+ Add New MCP Server**.
3.  Configure:
    - **Name**: `Naviscope`
    - **Type**: `command`
    - **Command**: `naviscope mcp`

#### Configure in VS Code / NeoVim (for LSP)
- **VS Code**: Install the extension built in step 3.
- **Other Clients**: Point your LSP client to run `naviscope lsp`.

## 🛠️ Query DSL (Interactive Shell)

The `naviscope shell` provides a Unix-like experience for exploring the Code Knowledge Graph:

```bash
# Change current context to a package or class
cd "com.example.service"

# List members in current context
ls

# List with detailed information
ls -l

# Find all classes named 'UserService'
find "UserService" --kind class

# Inspect full details of a symbol (source code, metadata)
cat "UserService"

# Find who references current symbol?
deps --rev

# Print current FQN context
pwd

# Clear screen
clear
```

## 🔗 Graph Relationships

Naviscope tracks the following relationship types in the knowledge graph:

- **Structural**: `Contains` (package → class, class → method, etc.)
- **Inheritance**: `InheritsFrom`, `Implements`
- **Type Usage**: `TypedAs` (field/variable → type)
- **Annotations**: `DecoratedBy` (class/method → annotation)
- **Build System**: `UsesDependency` (project → dependency)

Reference discovery (method calls, instantiations) is handled efficiently through the `reference_index` + Tree-sitter two-phase approach, avoiding the need to store explicit call edges for every reference.

## 📈 Roadmap

- [x] **Core**: Graph Storage (`petgraph`), Parallel Indexing, Real-time Updates (`notify`).
- [x] **Languages**: Java & Gradle (Tree-sitter driven).
- [x] **Interfaces**: CLI Shell, MCP Server, LSP Server.
- [x] **Editors**: VS Code Extension.
- [x] **Reference Discovery**: Two-phase approach (reference_index + Tree-sitter).
- [ ] **Upcoming**: Maven Support, Python/Rust Language Strategies.

## 📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [biuld](https://github.com/biuld)
- **Source:** [biuld/naviscope](https://github.com/biuld/naviscope)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-biuld-naviscope
- Seller: https://agentstack.voostack.com/s/biuld
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.