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 精心打造，實現超快速代碼分析