火山口记录仪
一个MCP（模型上下文协议）工具，用于索引和分析Rust代码，以便与Q-cli和Kiro等AI代理无缝协作。
概述
Cratographer解决了AI代理处理复杂Rust代码库时的一个关键问题： 无需昂贵的搜索即可快速定位代码元素当用户说“让我们修改DurableFlags”时，AI代理可以立即找到结构定义的确切位置，而不是运行多个grep命令或bash脚本来查找它。
AI优先发展
火山口记录仪是使用 AI优先的开发实践，Claude Code和Amazon Q等人工智能代理生成代码。人类开发人员审查人工智能生成的代码，并最终对代码质量、架构决策和正确性负责。
值得注意的是，Cratographer在开发过程中将自己用作自己的MCP工具之一——构建Cratograph的AI代理利用Cratographr的符号搜索功能来导航和修改自己的代码库。这种“狗粮”方法确保了该工具对于现实世界的人工智能辅助开发工作流程是实用和有用的。
目标
主要目标
- 快速代码定位：为Rust代码元素（结构、枚举、函数、特征、模块等）提供即时查找
- 元数据：索引不仅包括位置，还包括：
- 类型信息 - 文档注释 - 特质实施 - 模块层次结构 - 代码元素之间的依赖关系
- MCP集成：通过模型上下文协议公开索引，实现无缝的AI代理集成
- 增量更新：在文件更改时高效更新索引，无需完全重建
次要目标
- 交叉板条箱分析：处理工作区并理解多个板条箱之间的关系
- IDE质量分析：利用锈蚀分析器进行准确的语义理解
- 可扩展架构：支持锈蚀分析仪之外的其他索引工具和数据源
- 低开销：性能影响最小，适用于大型代码库
建筑
Cratographer使用rust analyzer的IDE API进行语义代码分析：
- 锈蚀分析仪集成：用途
ra_ap_idecrate用于全面理解Rust代码的语义
- 加载带有完整项目元数据的Cargo工作区 - 维护虚拟文件系统（VFS）以实现高效的文件访问 - 利用锈蚀分析器的符号搜索和代码结构API
- MCP服务器：基于
rmcp支持模型上下文协议的SDK
- 异步/等待Tokio运行时 - 工具参数的JSON模式验证 - 用于AI代理集成的标准传输
该实现包括使用增量索引更新进行实时文件监视。当源文件在磁盘上发生更改时，索引会自动更新，而无需重新启动服务器，从而通过rust-analyzer的ChangeWithProcMacros API提供高效的重新索引。
用例
- 人工智能辅助开发：使AI代理能够以手术精度导航和修改代码
- 代码导航：快速查找开发人员和工具
- 重构支持：了解代码库中更改的影响
- 文档生成：提取和组织代码文档
需求
- 锈1.70或更高版本
- 货物（带有铁锈）
- 一个Rust项目
Cargo.toml要分析的文件
当前实施情况
Cratographer使用官方Rust SDK实现为MCP服务器(rmcp)与rust分析器集成，用于语义代码分析。服务器提供两个功能齐全的工具：
工具
find_symbol
按名称查找Rust符号（结构、枚举、特征、函数、方法）的所有出现。
特征：
- 搜索模式：精确、模糊（默认）或前缀匹配
- 图书馆包容性：可选择在依赖关系和标准库中搜索
- 类型筛选：仅将结果筛选为类型符号（结构、枚举、特征、类型别名）
- 元数据：返回符号名称、种类、文件路径、行号和文档
示例用法：
{
"name": "HashMap",
"mode": "exact",
"include_library": true,
"types_only": true
}枚举文件
列出特定文件中定义的所有符号。
特征：
- 返回所有函数、方法、结构、枚举、特征、常量等
- 提供符号名称、种类和行号范围
- 自动过滤掉不相关的符号类型
示例用法：
{
"file_path": "/path/to/file.rs"
}实现细节
- 语义分析：使用锈蚀分析仪的IDE API(
ra_ap_ide)获取准确的类型信息 - 项目加载：自动加载包含所有目标的Cargo工作区
- VFS集成：维护虚拟文件系统以实现高效的文件访问
- 文件监视：监视源文件的更改并增量更新索引
- 实时更新：自动重新索引更改的文件，而无需重新启动服务器
- 符号种类：支持Const、枚举、函数、Impl、方法、模块、静态、结构、特性和TypeAlias
- 错误处理：具有清晰信息的全面错误类型
运行服务器
# Build in release mode
cargo build --release
# Run the server (communicates via stdio)
cargo run --release服务器通过stdio进行通信，并遵循MCP协议规范。它可以通过MCP配置与Claude Code或Kiro等AI代理集成。
测试
# Run all tests
cargo test
# Run specific test
cargo test test_find_symbol与AI代理集成
要将Cratographer与MCP兼容的AI代理一起使用，请将其添加到MCP配置中。例如，使用Claude Code：
{
"mcpServers": {
"cratographer": {
"command": "/path/to/cratographer/target/release/cratographer",
"args": []
}
}
}配置后，AI代理将可以访问 find_symbol 和 enumerate_file 用于浏览Rust代码库的工具。
状态
第一阶段-MCP服务器基础: ✅ 完成
- 使用rmcp SDK实现的MCP服务器结构
- 定义并记录两个核心工具
- 正确配置服务器信息和功能
第2阶段-工具实施: ✅ 完成
- 用于语义分析的全锈分析器集成
- 实现了具有精确/模糊/前缀搜索模式的find_symbol
- 实现了用于列出文件符号的enumerate_file
- 全面的测试套件，所有测试均已通过
- 支持库符号搜索和类型过滤
- 实时增量索引更新与文件监视
第3阶段-高级功能: 📋 计划的
- 增强的跨机箱分析和关系映射
- 大型工作空间的性能优化
- 附加符号元数据（特征实现、引用）
许可证
麻省理工学院