Roberto MCP

🚀 Roberto MCP

Roberto MCP 是一个用 Rust 构建的超快速、与语言无关的代码分析 MCP（模型上下文协议）服务器。它能够为大型代码库提供即时符号查找、引用跟踪和语义代码搜索功能，将性能作为首要考量因素。

🚀 快速开始

你可以通过以下步骤安装和使用 Roberto MCP：

安装依赖

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

2. 重启 Amazon Q CLI
3. 开始使用：在 Amazon Q CLI 中，你可以提出如下问题：
   • "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"

使用 MCP Inspector 进行测试

MCP Inspector 是测试和调试 MCP 服务器的优秀工具。

1. 安装 MCP Inspector

npx @modelcontextprotocol/inspector

2. 测试服务器

# 启动服务器
./target/release/roberto-mcp

# 在另一个终端中，运行 MCP Inspector
npx @modelcontextprotocol/inspector ./target/release/roberto-mcp

3. 探索工具
   • 查看可用工具及其架构
   • 使用示例数据测试工具调用
   • 检查请求/响应周期
   • 调试任何集成问题

通过命令行手动测试

你也可以使用标准输入输出手动测试服务器：

# 启动服务器
./target/release/roberto-mcp

# 发送 MCP 初始化请求（粘贴此 JSON）
{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "test-client", "version": "1.0.0"}}}

# 发送初始化通知
{"jsonrpc": "2.0", "method": "notifications/initialized"}

# 列出可用工具
{"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}}

# 索引一个目录
{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "index_code", "arguments": {"path": "/path/to/your/project"}}}

# 搜索符号
{"jsonrpc": "2.0", "id": 4, "method": "tools/call", "params": {"name": "find_symbols", "arguments": {"query": "main", "symbol_type": "function"}}}

# 使用 BM25 搜索代码内容
{"jsonrpc": "2.0", "id": 5, "method": "tools/call", "params": {"name": "code_search", "arguments": {"query": "error handling", "max_results": 5}}}

# 获取带有签名的文件大纲
{"jsonrpc": "2.0", "id": 6, "method": "tools/call", "params": {"name": "get_file_outline", "arguments": {"file_path": "/path/to/file.rs"}}}

# 获取目录概述
{"jsonrpc": "2.0", "id": 7, "method": "tools/call", "params": {"name": "get_directory_outline", "arguments": {"directory_path": "/path/to/project", "includes": ["functions", "classes"]}}}

✨ 主要特性

• ⚡ 高性能：符号查找时间小于 1 毫秒，索引速度超过 100 个文件/秒
• 🔒 无锁并发：无阻塞操作，高效处理并发请求
• 🧠 智能缓存：采用自定义二进制格式进行持久化存储，已索引的仓库启动时间小于 1 秒
• 📊 内存管理：自动进行 LRU 缓存淘汰，支持配置内存限制
• 🔄 增量更新：通过文件监控和 SHA - 256 变更检测实现增量更新
• 🌍 多语言支持：支持 15 种以上语言，架构可扩展
• 🛡️ 错误恢复：能够优雅处理格式错误的代码和 I/O 错误
• 🔍 全文搜索：通过 BM25 统计方法对所有代码内容进行搜索

📦 安装指南

前提条件

• 安装 Rust 1.70+ 及 Cargo
• 安装 Git

从源代码构建

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

生成的二进制文件位于 target/release/roberto-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"
}

返回以下内容的结构化视图：

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

7. get_directory_outline 📁

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

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

适用于以下场景：

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

📚 详细文档

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

🔧 技术细节

架构

• 语言：Rust（兼顾性能与安全性）
• 解析器：Tree - sitter（一致的增量解析）
• 存储：内存中的 DashMap + 二进制持久化
• 并发：无锁数据结构
• 协议：基于 JSON - RPC 标准输入输出的 MCP

性能基准

运行包含的基准测试，以验证系统性能：

# 运行所有基准测试
cargo bench

# 运行特定基准测试
cargo bench -- symbol_lookup

# 运行性能验证测试
cargo test --test performance_validation -- --nocapture

预期性能目标：

• 符号查找：平均小于 1 毫秒
• 索引速度：超过 100 个文件/秒
• 并发访问：超过 50k 次查找/秒
• 内存使用：大型仓库小于 1GB

测试

项目包含全面的测试覆盖：

# 运行所有测试
cargo test

# 仅运行单元测试
cargo test --lib

# 运行集成测试
cargo test --test integration_test

# 运行性能验证测试
cargo test --test performance_validation

# 运行并输出调试信息
cargo test -- --nocapture

测试覆盖情况：

• 54 个单元测试，覆盖所有核心模块
• 5 个集成测试，用于端到端工作流
• 5 个性能测试，验证性能要求
• 15 个特定语言测试
• 4 个大纲工具测试 总计：83 个测试通过

支持的语言

目前支持 15 种以上语言：

添加新语言： 该架构设计便于扩展。若要添加新语言，可按以下步骤操作：

1. 添加 Tree - sitter 语法依赖
2. 在 queries/ 目录中创建查询文件
3. 更新 Language 枚举和语言检测逻辑
4. 添加到支持的文件扩展名列表中

缓存与持久化

• 缓存位置：使用系统缓存目录（Unix 系统为 ~/.cache/roberto-mcp/）
• 缓存格式：采用自定义二进制格式，使用 bincode 进行序列化
• 缓存键：基于仓库路径和最后修改时间
• 缓存验证：启动时自动验证，支持增量更新
• 内存管理：检测到内存压力时自动进行 LRU 缓存淘汰（可配置）

错误处理

服务器设计具备强大的健壮性：

• 解析错误：继续索引其他文件，并记录问题
• 文件系统错误：优雅降级，返回部分结果
• 内存压力：自动清理和淘汰缓存
• 格式错误的请求：返回适当的 MCP 错误响应
• 并发访问：使用无锁数据结构防止死锁

监控与日志

服务器使用结构化日志，支持不同日志级别：

# 启用调试日志
RUST_LOG=debug ./target/release/roberto-mcp

# 为特定模块启用跟踪日志
RUST_LOG=roberto_mcp::indexer=trace ./target/release/roberto-mcp

配置

可通过环境变量进行配置：

# 内存管理
export ROBERTO_MAX_MEMORY_MB=1024
export ROBERTO_EVICTION_THRESHOLD=0.8

# 缓存位置
export ROBERTO_CACHE_DIR=~/.cache/roberto-mcp

# 日志记录
export RUST_LOG=roberto_mcp=info

📄 许可证

本项目采用 Apache 2.0 许可证，详情请参阅 LICENSE 文件。

🔍 故障排除

常见问题

1. 编译时出现 "Symbol not found" 错误
   • 确保安装了最新的 Rust 工具链：rustup update
   • 清理并重新构建：cargo clean && cargo build
2. 在 Amazon Q CLI 中服务器无响应
   • 检查配置文件路径和语法
   • 验证二进制文件路径是否正确且可执行
   • 查看 Amazon Q CLI 日志以查找错误信息
3. 内存使用过高
   • 通过环境变量配置内存限制
   • 服务器将自动淘汰最近最少使用的文件
   • 对于大型仓库，可考虑索引较小的子目录
4. 索引性能较慢
   • 检查磁盘 I/O 性能
   • 确保索引期间没有杀毒软件扫描文件
   • 使用 SSD 存储以提高性能

调试命令

# 检查服务器版本和功能
./target/release/roberto-mcp --version

# 测试基本功能
cargo test --test integration_test -- test_end_to_end_rust_indexing

# 进行性能基准测试
cargo test --test performance_validation -- --nocapture

用 Rust 精心打造，实现超快速代码分析