CodeCortXMCP Server

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.

2. get_symbol

Retrieve symbol information by name with optional source code inclusion.

3. get_symbol_references

Find all references to a symbol across the codebase.

4. find_symbols

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

5. code_search 🎯

BM25 statistical search through all indexed code content.

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.

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.

Perfect for:

• Project structure understanding

• API surface discovery

• Architecture overview

• Code navigation

🛠️ Installation & Setup

Prerequisites

• Rust 1.70+ with Cargo

• Git

Building from Source

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

🔧 Usage

With Amazon Q CLI

1. Add to Amazon Q CLI Configuration

   Add the following to your Amazon Q CLI MCP configuration:

   { "mcpServers": { "codecortx": { "command": "/path/to/codecortx-mcp/target/release/codecortx-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/codecortx-mcp # In another terminal, run MCP Inspector npx @modelcontextprotocol/inspector ./target/release/codecortx-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:

⚡ Performance Benchmarks

Run the included benchmarks to validate performance on your system:

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:

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/codecortext-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:

⚙️ Configuration

Environment Variables

🤝 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

📚 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