Code Cort X MCP

罗伯托 MCP

一个用Rust构建的超高速、与语言无关的代码分析MCP（模型上下文协议）服务器。它为大型代码库提供即时符号查找、引用追踪和语义代码搜索功能，性能优先。

  

🚀 特性

• ⚡ 高性能\100个文件/秒的索引速度
• 无锁并发无阻塞操作，高效处理并发请求
• 🧠 智能缓存对于之前已索引的仓库，实现小于1秒的启动时间的二进制持久化
• 📊 内存管理自动LRU（最近最少使用）驱逐机制，支持可配置的内存限制
• 🔄 增量更新使用SHA-256变更检测进行文件监控
• 🌍 多语言支持15+种语言，架构可扩展
• 🛡️ 容错能力优雅地处理格式错误代码和输入/输出错误
• 🔍 全文搜索BM25统计搜索所有代码内容

🏗️ 建筑学

• 语言Rust（性能+安全性）
• 解析器Tree-sitter（一致、增量解析）
• 存储内存中的DashMap + 二进制持久化
• 并发性无锁数据结构
• 协议通过JSON-RPC stdio的MCP（可能是指某种通信协议或接口，具体需根据上下文确定，此处直译为“MCP”）

📋 MCP 工具

该服务器提供了7种MCP工具，用于全面的代码分析：

1. index_code

为源代码文件建立索引以构建符号表，以便快速查找。

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

2. get_symbol

通过名称检索符号信息，可选择性地包含源代码。

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

3. get_symbol_references

在代码库中查找所有对该符号的引用。

{
  "name": "symbol_name"
}

4. find_symbols

通过精确匹配或模糊搜索查询符号，并可选择类型过滤。

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

5. code_search 🎯（目标）

通过BM25算法统计搜索所有已索引的代码内容。

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

非常适合寻找：

• 算法实现： "binary search algorithm"
• 错误处理模式： "error handling try catch"
• 数据库代码： "database connection pool"
• 特定功能： "file upload validation"

6. get_file_outline 📄（文件/纸张的象征）

获取特定文件中符号的结构化大纲。

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

返回有组织的视图：

• 带有签名的类/结构体
• 带有完整签名和参数的函数/方法
• 常量、枚举、接口、模块、导入、变量
• 行号和可见性（公有/私有）

7. get_directory_outline 📁 文件夹

获取目录中符号的高级概览。

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

非常适合：

• 项目结构理解
• API表面发现
• 架构概述
• 代码导航

🛠️ 安装与设置

先决条件

• Rust 1.70+ 配合 Cargo 使用
• Git（一种分布式版本控制系统）

从源代码构建

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

该二进制文件将在以下位置提供： target/release/roberto-mcp。

🔧 使用方法

使用 Amazon Q CLI

1. 添加到 Amazon Q CLI 配置

在您的Amazon Q CLI MCP配置中添加以下内容：

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

1. 重启 Amazon Q CLI

1. 开始使用

在 Amazon Q CLI 中，您现在可以提出诸如以下问题：

- “为我的项目目录中的代码建立索引” - “查找所有名称中包含‘parse’的函数” - “给我显示所有关于……的引用 SymbolStore "struct" 翻译成中文是“结构体” - “获取实施的 extract_symbols 函数 - “搜索斐波那契算法的实现” - “在代码库中查找错误处理模式” - “给我展示这个文件的概要，包括所有函数及其签名” - “查看此目录中的所有类和方法的概览”

使用MCP Inspector进行测试

MCP Inspector 是一个用于测试和调试 MCP 服务器的强大工具。

1. 安装MCP Inspector

   npx @modelcontextprotocol/inspector

1. 测试服务器

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

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

1. 探索工具

- 查看可用工具及其模式 - 使用示例数据测试工具调用 - 检查请求/响应周期 - 调试任何集成问题

通过命令行进行手动测试

你也可以使用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"]}}}

⚡ 性能基准测试

运行随附的基准测试以验证您系统上的性能：

# Run all benchmarks
cargo bench

# Run specific benchmark
cargo bench -- symbol_lookup

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

预期绩效目标：

• 符号查找：平均\100个文件/秒
• 并发访问：>50,000次查找/秒
• 内存使用：大型仓库时小于1GB

🧪 测试

该项目涵盖了全面的测试范围：

# 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

测试覆盖率：

• 54个单元测试，涵盖所有核心模块
• 5项端到端工作流程的集成测试
• 5项性能测试验证需求
• 15项语言专项测试
• 4个轮廓工具测试

总计：83个测试通过

🔍 支持的语言

目前支持15种以上语言：

• Rust（一种系统编程语言） (.rs): 函数、结构体、枚举、特性、实现、常量、模块
• python (.py)：函数、类、方法、变量、导入
• JavaScript（注：这是一个专有名词，直接翻译为“JavaScript”即可，无需额外解释其含义） (.js): 函数、类、方法、常量、变量
• TypeScript (.ts): 函数、类、接口、类型、枚举
• Java (.java): 类、方法、接口、枚举、常量
• 去（行动起来） (.go): 函数、结构体、接口、常量、变量
• C (.c): 函数、结构体、枚举、类型定义、变量
• C (.cpp, .hpp)：类、函数、命名空间、模板
• Ruby（罗比/鲁比，根据语境可灵活翻译，Ruby为常见英文名） (.rb)：类、模块、方法、常量
• PHP (.php)：类、函数、方法、常量
• C (.cs)：类、方法、接口、枚举、属性
• Kotlin（一种编程语言） (.kt)：类、函数、接口、对象
• Scala（斯卡拉，一种编程语言） (.scala): 类、对象、特质、函数
• Swift（编程语言） (.swift): 类、结构体、协议、函数
• Objective-C (.m, .h)：类、方法、协议、分类

添加新语言： 该架构设计便于扩展。要添加一种新语言：

1. 添加 Tree-sitter 语法依赖
2. 在（指定位置）创建查询文件 queries/ 目录
3. 更新 Language 枚举和语言检测
4. 添加到支持的扩展中

💾 缓存与持久化

• 缓存位置使用系统缓存目录（~/.cache/roberto-mcp/ （在Unix系统上）
• 缓存格式使用bincode序列化的自定义二进制格式
• 缓存键基于存储库路径和最后修改时间
• 缓存验证启动时自动验证并进行增量更新
• 内存管理当检测到内存压力时，执行LRU（最近最少使用）驱逐（可配置）

🛡️ 错误处理

该服务器设计具有高可靠性：

• 解析错误继续索引其他文件，记录问题
• 文件系统错误优雅降级，部分结果可用
• 内存压力自动清理和驱逐
• 格式错误的请求适当的MCP错误响应
• 并发访问无锁结构避免死锁

📊 监控与日志记录

服务器使用具有不同级别的结构化日志记录：

# 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

⚙️ 配置

环境变量

# 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

🤝 贡献（或“参与贡献”）

1. 为仓库创建分支（或：克隆仓库）
2. 创建一个特性分支（git checkout -b feature/amazing-feature）
3. 运行测试套件（cargo test)
4. 运行基准测试以确保没有性能退化cargo bench）
5. 提交您的更改（git commit -m 'Add amazing feature')
6. 推送到分支（git push origin feature/amazing-feature)
7. 提交一个拉取请求

📝 许可证

这个项目根据Apache License 2.0授权 - 请参阅 许可证 文件中详述。

🔧 故障排除

常见问题

1. 编译时出现“符号未找到”错误

- 确保您已安装最新的Rust工具链： rustup update - 清理并重建： cargo clean && cargo build

1. Amazon Q CLI 中的服务器无响应

- 检查配置文件的路径和语法 - 验证二进制路径是否正确且可执行 - 检查 Amazon Q CLI 日志中的错误信息

1. 内存使用率高

- 通过环境变量配置内存限制 - 服务器将自动移除最近最少使用的文件 - 对于非常大的仓库，考虑为较小的子目录建立索引

1. 索引性能缓慢

- 检查磁盘I/O性能 - 确保在索引过程中没有防病毒软件扫描文件 - 使用SSD存储以获得更佳性能

调试命令

# 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

📚 文档

• 建筑指南 - 详细的系统架构
• 开发指南 - 设置和开发工作流程
• API 参考文档 - 完整的MCP工具文档

______________________________________________________________________

用Rust语言精心打造，实现闪电般的代码分析速度