BeyondSight

The best friend of the modern developer pocket!

Why BeyondSight?

Stop forcing your AI to guess. Start giving it answers.

When you ask an AI assistant ("What happens if I change this method?"), it kicks off a slow, expensive, and unreliable process. The LLM uses a brute-force grep search, burning thousands of API tokens 💸 to read files and guess your code's structure. This leads to high API bills and missed dependencies.

BeyondSight is a precision-guided context provider for AI-driven development. It acts as the "impact analysis brain" for your AI.

It fundamentally changes the economics and reliability of AI-assisted coding by replacing this blind, expensive search with a single, intelligent query.

👎 The Old Way (Blind & Expensive)

1. AI Assistant makes a blizzard of grep calls.
2. It burns thousands of tokens reading entire files.
3. It tries to guess relationships, often missing transitive dependencies.
4. Result: Slow, expensive, and inaccurate.

👍 The BeyondSight Way (Precise & Cheap)

1. AI Assistant makes one single MCP tool call.
2. BeyondSight traverses its graph database and returns a perfect, pre-analyzed impact report (all files, exact line numbers, and all transitive dependencies).
3. Result: Instant, cheap, and 100% accurate.

This approach provides clear, immediate benefits:

• 💰 Massive Cost Savings: Slashes your LLM API bills by replacing token-heavy searches with a single, lightweight tool call.
• ⚡ Blazing Speed: The AI gets a complete dependency map instantly, eliminating search, read, and parse latency.
• 🎯 Sniper-Like Accuracy: Delivers a graph-verified impact report with zero false positives and complete transitive dependencies, enabling safe, reliable AI-powered refactoring.

Real-World Use Cases

BeyondSight is designed to be the "code memory" for your AI assistant.

• AI-Assisted Refactoring: Ask, "AI, rename this UserService class." The AI queries BeyondSight and gets a complete list of every file and line number to change.
• Assessing API Evolution: Ask, "What's the impact of changing this method signature?" The AI instantly provides a full, transitive impact report, warning you of downstream breakages.
• AI-Powered Code Review: Ask, "Could this PR change break anything?" The AI uses BeyondSight to perform an instant, comprehensive impact analysis that's impossible to do manually.
• Understanding Architecture: Ask, "Show me all services that depend on our PaymentModule." The AI queries the graph to reveal hidden dependencies in seconds.

Overview

BeyondSight is a code analysis server that acts as a high-speed "code intelligence layer" for AI assistants.

Its process is simple:

1. Parses your entire Java project into its core components.
2. Models all code relationships (classes, methods, fields) in a high-performance Neo4j graph database.
3. Exposes this complete dependency graph to LLMs via the Model Context Protocol (MCP).

When you ask, "What happens if I change this?", your AI doesn't search—it asks BeyondSight and gets an instant, perfect, and graph-verified answer.

While the primary focus is serving LLMs via MCP, the powerful graph queries are also accessible via a traditional REST API for custom tooling or manual inspection.

Features

• Primary MCP Server for LLMs: The core of the project. Provides a high-speed Model Context Protocol (MCP) server that allows AI assistants (like Cursor) to ask questions and receive instant impact analysis.
• Pre-configured AI Tools: Ships with ready-to-use MCP tools (getClassImpact, getMethodImpact, getFieldImpact) so the AI can immediately perform analysis without complex setup.
• Deep Graph Database Analysis: Automatically parses all Java source code using Eclipse JDT-based parsing (via Spoon) for enhanced accuracy and stores the entire codebase structure (classes, methods, fields, and their relationships) in a Neo4j graph database.
• Full Transitive Dependency Tracking: The graph model allows for instant discovery of all affected code paths, including multi-level "hidden" dependencies that primitive, file-based searches would miss.
• Precise, Hierarchical Impact Reports: Queries return structured, hierarchical reports of all affected classes and methods—with exact line numbers—in a format that is perfect for an AI to parse and act upon.
• Secondary REST API Access: Includes a comprehensive REST API for programmatic access to the impact analysis engine, allowing integration with non-MCP tools or custom developer scripts.

For detailed API documentation, see API.md.

Tech Stack

• Spring Boot 4.0.0-RC1
• Java 25
• Neo4j Graph Database
• Spoon 11.2.1 (Eclipse JDT-based) for Java code parsing
• Gradle Build System
• Docker Compose for Neo4j setup

Prerequisites

• Java 25
• Docker & Docker Compose
• Gradle (or use the included Gradle wrapper)

Getting Started

1. Clone the Repository

git clone git@github.com:felipestanzani/beyondsight.git
cd beyondsight

2. Start Neo4j Database

docker-compose up -d

This will start Neo4j on:

• Bolt port: 7687
• HTTP port: 7474
• Username: neo4j
• Password: notverysecret

3. Build and Run the Application

./gradlew bootRun

The application will start on http://localhost:321

4. Configure MCP Server in Cursor (Optional)

To use BeyondSight's impact analysis tools directly within Cursor AI, you can configure the MCP server:

Step 1: Ensure the Application is Running

Make sure BeyondSight is running on http://localhost:321 (see step 3 above).

Step 2: Configure Cursor MCP Settings

1. Open Cursor and go to Settings → Features → Model Context Protocol
2. Add the following configuration to your MCP settings file (usually located at ~/.cursor/mcp.json):

{
    "mcpServers": {
        "beyondsight-mcp-server": {
            "transport": "sse",
            "url": "http://localhost:321/sse",
            "capabilities": {
                "tool": true
            },
            "name": "beyondsight-mcp-server"
        }
    }
}

Note: This configuration uses Server-Sent Events (SSE) to communicate with the BeyondSight server.

Step 3: Restart Cursor

After adding the configuration, restart Cursor for the changes to take effect.

Step 4: Verify MCP Integration

Once configured, you can use the MCP tools directly in Cursor's AI assistant.

For detailed information about available MCP tools, see MCP.md.

Using MCP Tools in Cursor

After configuration, you can ask Cursor questions like:

• "What would be impacted if I change the UserService class?"
• "Show me the impact analysis for the calculateTotal() method"
• "Which methods would be affected if I modify the userName field?"

These tools will automatically be available in Cursor's AI assistant and can analyze your Java codebase for impact analysis.

Development

Building the Project

./gradlew build

Running Tests

./gradlew test

Configuration

The application configuration is in src/main/resources/application.yml:

server:
  port: 321

spring:
  application:
    name: beyondsight
  neo4j:
    uri: bolt://localhost:7687
    authentication:
      username: neo4j
      password: notverysecret

License

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

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Author

Felipe Cesar Stanzani Fonseca

---

For more information about Neo4j and graph databases, visit neo4j.com.