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

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

⚡ 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

🤝 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

📝 License

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

🔧 Troubleshooting

Common Issues

1. "Symbol not found" errors during compilation

   • Ensure you have the latest Rust toolchain: rustup update
   • Clean and rebuild: cargo clean && cargo build

2. 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

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

4. 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