Roberto MCP

🚀 Roberto MCP

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

🚀 Quick Start

Roberto MCP is a high - performance code analysis server. To start using it, you first need to install and set it up. The following sections will guide you through the installation, configuration, and usage steps.

✨ 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

💻 Usage Examples

Basic Usage

The server provides 7 MCP tools for comprehensive code analysis. Here are some basic usage examples:

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
}

Advanced Usage

3. 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"

📦 Installation

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.

📚 Documentation

With Amazon Q CLI

1. 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": []
       }
     }
   }
   

2. Restart Amazon Q CLI
3. 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.

1. Install MCP Inspector

   npx @modelcontextprotocol/inspector
   

2. Test the Server

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

3. 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"]}}}

🔧 Technical Details

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:

1. Add Tree - sitter grammar dependency
2. Create query files in queries/ directory
3. Update Language enum and language detection
4. 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

📄 License

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

🤝 Contributing

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

🔧 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