罗伯托-mcp

Name: 罗伯托-mcp
Author: kensave

作者：kensave3 星标更新：2025-10-06

安装使用来源：spider==github.com

项目介绍

Roberto MCP

一个用 Rust 编写的高性能、语言无关的代码分析 MCP（模型上下文协议）服务器。它提供即时符号查找、引用跟踪以及针对大型代码库的语义代码搜索，性能是其首要考虑因素。

🚀 特性

⚡ 高性能：符号查找 <1ms，索引速度 >100 文件/秒
🔒 无锁并发：无阻塞操作，高效处理并发请求
🧠 智能缓存：二进制持久化，已索引仓库启动时间 <1 秒
📊 内存管理：自动 LRU 踢出机制，可配置内存限制
🔄 增量更新：文件监控，SHA-256 变更检测
🌍 多语言支持：支持 15+ 种语言，架构可扩展
🛡️ 错误容错：优雅处理畸形代码和 I/O 错误
🔍 全文搜索：通过 BM25 统计搜索所有代码内容

🏗️ 架构

语言：Rust（性能 + 安全）
解析器：Tree-sitter（一致且增量的解析）
存储：内存中的 DashMap + 二进制持久化
并发：无锁数据结构
协议：基于 JSON-RPC 标准输入输出的 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"
}

返回组织视图：

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

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 结合使用

添加到 Amazon Q CLI 配置

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

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

重启 Amazon Q CLI
开始使用

在 Amazon Q CLI 中，您可以提问如下问题：
- "索引我的项目目录中的代码"
- "查找所有名称中包含 'parse' 的函数"
- "显示对 SymbolStore 结构的所有引用"
- "获取 extract_symbols 函数的实现"
- "搜索斐波那契算法的实现"
- "在代码库中查找错误处理模式"
- "显示此文件的结构大纲，包括所有函数及其签名"
- "获取此目录中所有类和方法的概述"

使用 MCP Inspector 测试

MCP Inspector 是一个测试和调试 MCP 服务器的好工具。

安装 MCP Inspector
```
npx @modelcontextprotocol/inspector
```

测试服务器

# 运行服务器
./target/release/roberto-mcp

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

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

通过命令行手动测试

您也可以通过标准输入输出手动测试服务器：

# 启动服务器
./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"]}}}

⚡ 性能基准测试

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

# 运行所有基准测试
cargo bench

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

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

预期性能目标：

符号查找：<1ms 平均
索引速度：>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+ 种语言：

Rust (.rs)：函数、结构体、枚举、特征、实现、常量、模块
Python (.py)：函数、类、方法、变量、导入
JavaScript (.js)：函数、类、方法、常量、变量
TypeScript (.ts)：函数、类、接口、类型、枚举
Java (.java)：类、方法、接口、枚举、常量
Go (.go)：函数、结构体、接口、常量、变量
C (.c)：函数、结构体、枚举、typedefs、变量
C++ (.cpp, .hpp)：类、函数、命名空间、模板
Ruby (.rb)：类、模块、方法、常量
PHP (.php)：类、函数、方法、常量
C# (.cs)：类、方法、接口、枚举、属性
Kotlin (.kt)：类、函数、接口、对象
Scala (.scala)：类、对象、特征、函数
Swift (.swift)：类、结构体、协议、函数
Objective-C (.m, .h)：类、方法、协议、类别

添加新语言： 架构设计易于扩展。要添加新语言：

添加 Tree-sitter 语法依赖
在 queries/ 目录创建查询文件
更新 Language 枚举和语言检测
添加到支持的扩展名

💾 缓存与持久化

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

🛡️ 错误处理

服务器设计具有鲁棒性：

解析错误：继续索引其他文件，记录问题
文件系统错误：部分结果的优雅降级
内存压力：自动清理和踢出
畸形请求：适当的 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

🤝 贡献

分叉仓库
创建功能分支 (git checkout -b feature/amazing-feature)
运行测试套件 (cargo test)
运行基准测试以确保没有性能退化 (cargo bench)
提交更改 (git commit -m 'Add amazing feature')
推送到分支 (git push origin feature/amazing-feature)
打开拉取请求

📝 许可证

本项目根据 Apache 许可证 2.0 许可 - 详情见 LICENSE 文件。

🔧 故障排除

常见问题

编译期间出现“未找到符号”错误
- 确保您有最新的 Rust 工具链：rustup update
- 清理并重新构建：cargo clean && cargo build
Amazon Q CLI 中服务器无响应
- 检查配置文件路径和语法
- 验证二进制路径正确且可执行
- 检查 Amazon Q CLI 日志中的错误消息
高内存使用
- 通过环境变量配置内存限制
- 服务器将自动踢出最近最少使用的文件
- 考虑为非常大的仓库索引较小的子目录
索引性能慢
- 检查磁盘 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

📚 文档

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

用 Rust 构建，用于闪电般快速的代码分析