Roberto MCP

A lightning-fast, language-agnostic code analysis MCP (Model Context Protocol) server built in Rust. Provides instant symbol lookups, reference tracking, and semantic code search for large codebases with performance as a first-class citizen.

🚀 Features

⚡ High Performance: <1ms symbol lookups, >100 files/sec indexing
🔒 Lock-free Concurrency: No blocking operations, handles concurrent requests efficiently
🧠 Smart Caching: Binary persistence with <1s startup for previously indexed repositories
📊 Memory Management: Automatic LRU eviction with configurable memory limits
🔄 Incremental Updates: File watching with SHA-256 change detection
🌍 Multi-language: 15+ languages supported with extensible architecture
🛡️ Error Resilient: Graceful handling of malformed code and I/O errors
🔍 Full-text Search: BM25 statistical search through all code content

🏗️ Architecture

Language: Rust (performance + safety)
Parser: Tree-sitter (consistent, incremental parsing)
Storage: In-memory DashMap + binary persistence
Concurrency: Lock-free data structures
Protocol: MCP over JSON-RPC stdio

📋 MCP Tools

The server provides 7 MCP tools for comprehensive code analysis:

1. `index_code`

Index source code files to build symbol table for fast lookups.

{
  "path": "/path/to/project"
}

2. `get_symbol`

Retrieve symbol information by name with optional source code inclusion.

{
  "name": "function_name",
  "include_source": true
}

3. `get_symbol_references`

Find all references to a symbol across the codebase.

{
  "name": "symbol_name"
}

4. `find_symbols`

Search symbols by query using exact match or fuzzy search with optional type filtering.

{
  "query": "test_",
  "symbol_type": "function"
}

5. `code_search` 🎯

BM25 statistical search through all indexed code content.

{
  "query": "fibonacci algorithm",
  "max_results": 10
}

Perfect for finding:

Algorithm implementations: "binary search algorithm"
Error handling patterns: "error handling try catch"
Database code: "database connection pool"
Specific functionality: "file upload validation"

6. `get_file_outline` 📄

Get structured outline of symbols in a specific file.

{
  "file_path": "/path/to/file.rs"
}

Returns organized view of:

Classes/Structs with signatures
Functions/Methods with full signatures and parameters
Constants, Enums, Interfaces, Modules, Imports, Variables
Line numbers and visibility (pub/priv)

7. `get_directory_outline` 📁

Get high-level overview of symbols across a directory.

{
  "directory_path": "/path/to/project",
  "includes": ["functions", "methods", "constants"]
}

Perfect for:

Project structure understanding
API surface discovery
Architecture overview
Code navigation

🛠️ Installation & Setup

Prerequisites

Rust 1.70+ with Cargo
Git

Building from Source

git clone https://github.com/kensave/roberto-mcp.git
cd roberto-mcp
cargo build --release

The binary will be available at target/release/roberto-mcp.

🔧 Usage

With Amazon Q CLI

Add to Amazon Q CLI Configuration

Add the following to your Amazon Q CLI MCP configuration:

{
  "mcpServers": {
    "roberto": {
      "command": "/path/to/roberto-mcp/target/release/roberto-mcp",
      "args": []
    }
  }
}

Restart Amazon Q CLI
Start Using

In Amazon Q CLI, you can now ask questions like:
- "Index the code in my project directory"
- "Find all functions that contain 'parse' in their name"
- "Show me all references to the SymbolStore struct"
- "Get the implementation of the extract_symbols function"
- "Search for fibonacci algorithm implementations"
- "Find error handling patterns in the codebase"
- "Show me the outline of this file with all functions and their signatures"
- "Get an overview of all classes and methods in this directory"

Testing with MCP Inspector

MCP Inspector is a great tool for testing and debugging MCP servers.

Install MCP Inspector
```
npx @modelcontextprotocol/inspector
```

Test the Server

# Run the server
./target/release/roberto-mcp

# In another terminal, run MCP Inspector
npx @modelcontextprotocol/inspector ./target/release/roberto-mcp

Explore the Tools
- View available tools and their schemas
- Test tool calls with sample data
- Inspect request/response cycles
- Debug any integration issues

Manual Testing via Command Line

You can also test the server manually using stdio:

# Start the server
./target/release/roberto-mcp

# Send MCP initialization (paste this JSON)
{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "test-client", "version": "1.0.0"}}}

# Send initialized notification
{"jsonrpc": "2.0", "method": "notifications/initialized"}

# List available tools
{"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}}

# Index a directory
{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "index_code", "arguments": {"path": "/path/to/your/project"}}}

# Search for symbols
{"jsonrpc": "2.0", "id": 4, "method": "tools/call", "params": {"name": "find_symbols", "arguments": {"query": "main", "symbol_type": "function"}}}

# Search code content with BM25
{"jsonrpc": "2.0", "id": 5, "method": "tools/call", "params": {"name": "code_search", "arguments": {"query": "error handling", "max_results": 5}}}

# Get file outline with signatures
{"jsonrpc": "2.0", "id": 6, "method": "tools/call", "params": {"name": "get_file_outline", "arguments": {"file_path": "/path/to/file.rs"}}}

# Get directory overview
{"jsonrpc": "2.0", "id": 7, "method": "tools/call", "params": {"name": "get_directory_outline", "arguments": {"directory_path": "/path/to/project", "includes": ["functions", "classes"]}}}

⚡ Performance Benchmarks

Run the included benchmarks to validate performance on your system:

# Run all benchmarks
cargo bench

# Run specific benchmark
cargo bench -- symbol_lookup

# Run performance validation tests
cargo test --test performance_validation -- --nocapture

Expected Performance Targets:

Symbol lookups: <1ms average
Indexing speed: >100 files/second
Concurrent access: >50k lookups/second
Memory usage: <1GB for large repositories

🧪 Testing

The project includes comprehensive test coverage:

# Run all tests
cargo test

# Run unit tests only
cargo test --lib

# Run integration tests
cargo test --test integration_test

# Run performance validation
cargo test --test performance_validation

# Run with output for debugging
cargo test -- --nocapture

Test Coverage:

54 unit tests covering all core modules
5 integration tests for end-to-end workflows
5 performance tests validating requirements
15 language-specific tests
4 outline tool tests

Total: 83 tests passing

🔍 Supported Languages

Currently supports 15+ languages:

Rust (.rs): Functions, structs, enums, traits, implementations, constants, modules
Python (.py): Functions, classes, methods, variables, imports
JavaScript (.js): Functions, classes, methods, constants, variables
TypeScript (.ts): Functions, classes, interfaces, types, enums
Java (.java): Classes, methods, interfaces, enums, constants
Go (.go): Functions, structs, interfaces, constants, variables
C (.c): Functions, structs, enums, typedefs, variables
C++ (.cpp, .hpp): Classes, functions, namespaces, templates
Ruby (.rb): Classes, modules, methods, constants
PHP (.php): Classes, functions, methods, constants
C# (.cs): Classes, methods, interfaces, enums, properties
Kotlin (.kt): Classes, functions, interfaces, objects
Scala (.scala): Classes, objects, traits, functions
Swift (.swift): Classes, structs, protocols, functions
Objective-C (.m, .h): Classes, methods, protocols, categories

Adding New Languages: The architecture is designed for easy extension. To add a new language:

Add Tree-sitter grammar dependency
Create query files in queries/ directory
Update Language enum and language detection
Add to supported extensions

💾 Caching & Persistence

Cache Location: Uses system cache directory (~/.cache/roberto-mcp/ on Unix)
Cache Format: Custom binary format with bincode serialization
Cache Key: Based on repository path and last modification times
Cache Validation: Automatic validation on startup with incremental updates
Memory Management: LRU eviction when memory pressure detected (configurable)

🛡️ Error Handling

The server is designed for robustness:

Parse Errors: Continues indexing other files, logs issues
File System Errors: Graceful degradation with partial results
Memory Pressure: Automatic cleanup and eviction
Malformed Requests: Proper MCP error responses
Concurrent Access: Lock-free structures prevent deadlocks

📊 Monitoring & Logging

The server uses structured logging with different levels:

# Enable debug logging
RUST_LOG=debug ./target/release/roberto-mcp

# Enable trace logging for specific modules
RUST_LOG=roberto_mcp::indexer=trace ./target/release/roberto-mcp

⚙️ Configuration

Environment Variables

# Memory management
export ROBERTO_MAX_MEMORY_MB=1024
export ROBERTO_EVICTION_THRESHOLD=0.8

# Cache location
export ROBERTO_CACHE_DIR=~/.cache/roberto-mcp

# Logging
export RUST_LOG=roberto_mcp=info

🤝 Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Run the test suite (cargo test)
Run benchmarks to ensure no performance regression (cargo bench)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📝 License

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

🔧 Troubleshooting

Common Issues

"Symbol not found" errors during compilation
- Ensure you have the latest Rust toolchain: rustup update
- Clean and rebuild: cargo clean && cargo build
Server not responding in Amazon Q CLI
- Check the config file path and syntax
- Verify the binary path is correct and executable
- Check Amazon Q CLI logs for error messages
High memory usage
- Configure memory limits via environment variables
- The server will automatically evict least-recently-used files
- Consider indexing smaller subdirectories for very large repositories
Slow indexing performance
- Check disk I/O performance
- Ensure no antivirus is scanning files during indexing
- Use SSD storage for better performance

Debug Commands

# Check server version and capabilities
./target/release/roberto-mcp --version

# Test basic functionality
cargo test --test integration_test -- test_end_to_end_rust_indexing

# Benchmark performance
cargo test --test performance_validation -- --nocapture

📚 Documentation

Architecture Guide - Detailed system architecture
Development Guide - Setup and development workflow
API Reference - Complete MCP tool documentation

Built with ❤️ in Rust for lightning-fast code analysis

roberto-mcp