内容
# rust-mcp-server
**MCP（模型上下文协议）服务器，用于详尽的 Rust 代码分析。**
MCP服务器，用Rust编写，通过[`syn`](https://github.com/dtolnay/syn) + `toml`和[`rust-analyzer`](https://github.com/rust-lang/rust-analyzer)（`ra_ap_*`作为语义ASG）分析Rust项目。公开**37种工具**，返回**确定性Markdown**，可供LLM消费。
它是`cobol-mcp-server`、`java-mcp-server`和`python-mcp-server`的Rust对应版本：相同的哲学（“真理”，没有幻觉），不同的领域和不同的解析器（syn/toml/ra_ap_*而不是ProLeap/Spoon/LibCST）。
---
## 快速开始
### 先决条件
- **Rust 1.85+**（测试版本为1.96.0，通过brew和rustup）
- **macOS / Linux**（Windows未测试）
- 可选，用于交叉编译到musl：`zig` + `cargo-zigbuild` + `rustup`，目标为`x86_64-unknown-linux-musl`和`aarch64-unknown-linux-musl`
### 原生构建
```bash
cargo build --release
```
二进制文件：`target/release/rust-mcp-server`（~13 MB，arm64/x86_64）。
### 运行
MCP服务器使用**标准输入输出传输** - 作为OpenCode、Claude Desktop、Visual Studio Code等的子进程启动：
```bash
./target/release/rust-mcp-server
```
### 日志记录
默认为`/tmp/rust_mcp_server.log`。可通过环境变量配置：
| 变量 | 默认值 | 描述 |
|---|---|---|
| `RUST_MCP_LOG_FILE` | `/tmp/rust_mcp_server.log` | 日志文件路径 |
| `RUST_MCP_LOG_LEVEL` | `info` | `debug`, `info`, `warn`, `error` |
### 测试
```bash
cargo test # 78 tests: 33 unit + 45 golden snapshots
cargo test --release # same but optimized
INSTA_UPDATE=always cargo test # generate snapshots
```
### 端到端烟雾测试
```bash
cargo build --release
python3 scripts/smoke_test.py
```
该脚本执行完整的JSON-RPC握手：`initialize` → `tools/list` → 加载fixture → 调用11种工具 → 验证输出 → `exit`。验证服务器与真实的MCP客户端端到端工作。
---
## CI和容器
该项目在`.github/workflows/ci.yml`有一个GitHub Actions工作流，包含3个作业：
- `test-native`：`cargo test`在Ubuntu上。
- `cross-compile-musl`：`cargo zigbuild` + 使用`docker run alpine`验证。
- `lint`：`cargo fmt --check` + `cargo clippy`（无`-D warnings`，由于minor doc list warnings）。
以及生成`rust-mcp-server:test`镜像（~42 MB）的多阶段`Dockerfile`：
```bash
podman build -t rust-mcp-server:test -f Dockerfile .
podman run --rm -i rust-mcp-server:test
```
## 测试fixtures
该项目在`tests/fixtures/`中包含两个示例Rust crates，设计用于让工具拥有真实的材料来处理（而不是空fixtures）：
**`sample_crate/`** - 主要fixture。具有3个**真实**和**已使用**的依赖：
- `cfg-if = "1"`（普通）- 在`is_release()`中使用`cfg_if!`宏（验证`cfg-if`被正确处理）。
- `once_cell = "1"`（普通）- 在`cached_value()`中使用（验证sync::OnceCell）。
- `pretty_assertions = "1"`（dev-dep）- 在测试中使用（验证dev-deps）。
该fixture有4个通过测试：`test_add`、`test_multiply`、`test_is_release`、`test_cached_value`。
**`sample_crate_with_deps/`** - `find_unused_dependencies`的fixture。具有3个未使用的依赖（serde，unused_dep，unused_dev_dep），工具必须报告这些依赖。
---
`rust-mcp-server`可以通过[`zig`](https://ziglang.org/)作为链接器（通过`cargo-zigbuild`）编译为**静态Linux二进制文件**。生成的二进制文件不依赖于glibc，可以在任何现代Linux发行版（Alpine，Ubuntu，RHEL等）上运行，而无需外部依赖。
### 先决条件
```bash
# zig — cargo-zigbuild使用的链接器
brew install zig
# rustup — Rust工具链管理器
brew install rustup-init
rustup-init -y --default-toolchain stable
rustup target add x86_64-unknown-linux-musl
rustup target add aarch64-unknown-linux-musl
# cargo-zigbuild — 调用zig作为链接器的包装器
cargo install cargo-zigbuild
```
> **关于双工具链的说明**：如果您通过Homebrew安装了Rust（`brew install rust`），则`rustup target add`仅影响rustup工具链。默认`cargo`解析为Homebrew二进制文件，**不**看到musl目标。**解决方案**（推荐）：`brew uninstall rust`以拥有单个工具链。如果您不想卸载，则需要手动创建rustup shims（下一节）。
#### 如果您有工具链冲突，请设置shims
如果在`brew install rustup-init`之后，默认`cargo`不是来自rustup，则需要创建shims：
```bash
RUSTUP_REAL=$(find /Users/alejandro.ferreira/homebrew/Cellar/rustup -name rustup -type f 2>/dev/null | head -1)
for cmd in cargo rustc rustup rustdoc rustfmt cargo-clippy clippy-driver; do
cp "$RUSTUP_REAL" "$HOME/.cargo/bin/$cmd"
done
chmod +x "$HOME/.cargo/bin/"{cargo,rustc,rustup,rustdoc,rustfmt,cargo-clippy,clippy-driver}
cargo --version
```
> **为什么使用`cp`而不是`ln -s`**：rustup二进制文件通过`argv[0]`检测其名称。符号链接保留`argv[0]`指向`rustup`，而不是`cargo`，因此调度失败。`cp`打破链接，为每个shim提供其自己的`argv[0]`。
### 构建
```bash
cargo zigbuild --release --target x86_64-unknown-linux-musl
cargo zigbuild --release --target aarch64-unknown-linux-musl
```
输出：
- `target/x86_64-unknown-linux-musl/release/rust-mcp-server`（~16 MB，静态链接）
- `target/aarch64-unknown-linux-musl/release/rust-mcp-server`（~14 MB，静态链接）
> **冷构建时间**：~4分钟每目标。增量构建是秒（musl目标缓存在`target/`）。
### 在podman中测试（Docker替代品）
```bash
podman machine start
podman run --rm -v $(pwd):/app:ro -w /app alpine sh -c "
{
echo '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2025-11-25\",\"capabilities\":{},\"clientInfo\":{\"name\":\"x\",\"version\":\"1\"}}}'
echo '{\"jsonrpc\":\"2.0\",\"method\":\"notifications/initialized\",\"params\":{}}'
echo '{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/list\",\"params\":{}}'
sleep 1
} | /app/target/x86_64-unknown-linux-musl/release/rust-mcp-server 2>&1 | head -c 500
"
```
### 使用6种工具进行端到端验证
```bash
podman run --rm -v $(pwd):/app:ro -w /app alpine sh -c "
{
echo '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2025-11-25\",\"capabilities\":{},\"clientInfo\":{\"name\":\"musl-test\",\"version\":\"1.0\"}}}'
echo '{\"jsonrpc\":\"2.0\",\"method\":\"notifications/initialized\",\"params\":{}}'
echo '{\"jsonrpc\":\"2.0\",\"id\":2,\"method\":\"tools/call\",\"params\":{\"name\":\"load_rust_project\",\"arguments\":{\"source\":\"/app/tests/fixtures/sample_crate\",\"alias\":\"sample\"}}}'
sleep 1
echo '{\"jsonrpc\":\"2.0\",\"id\":3,\"method\":\"tools/call\",\"params\":{\"name\":\"program_summary\",\"arguments\":{\"name\":\"sample\"}}}'
sleep 1
echo '{\"jsonrpc\":\"2.0\",\"id\":4,\"method\":\"tools/call\",\"params\":{\"name\":\"resolve_type\",\"arguments\":{\"name\":\"sample\",\"symbol\":\"add\"}}}'
sleep 1
echo '{\"jsonrpc\":\"2.0\",\"id\":5,\"method\":\"tools/call\",\"params\":{\"name\":\"find_dead_code\",\"arguments\":{\"name\":\"sample\"}}}'
sleep 1
echo '{\"jsonrpc\":\"2.0\",\"id\":6,\"method\":\"tools/call\",\"params\":{\"name\":\"analysis_summary\",\"arguments\":{\"name\":\"sample\"}}}'
sleep 2
} | /app/target/x86_64-unknown-linux-musl/release/rust-mcp-server 2>&1
"
```
预期输出（摘要）：
- `ID 2: # Project Loaded`
- `ID 3: # Program Summary: 'sample_crate'`
- `ID 4: # Definition of 'add' (1)`
- `ID 5: # Dead code (semantic) (0)`
- `ID 6: # ASG Summary: 'sample_crate'`
### musl限制
- `ureq`（HTTP客户端）可能不适用于某些URL（TLS）在musl上。我们不将其用于实际I/O，因此它无关紧要。
- `gix`已包含，但`resolve_git`使用`git`CLI（不是`gix::clone`），因此它需要在目标系统上安装`git`（对我们的用例来说不是问题）。
- `cargo-zigbuild`在构建期间发出警告：`linker stderr: ignoring deprecated linker optimization setting '1'`。来自与`zig 0.16`的交互。**不影响二进制文件** - 它正确构建并工作。
---
## MCP工具参考（37种工具）
### 源代码管理（5）
- `load_rust_project` - 加载本地路径、Git URL或存档URL
- `unload_rust_project` - 从缓存中删除
- `project_metadata` - 名称、别名、类型、路径、包信息
- `inspect_build_config` - 显示`Cargo.toml`
- `list_crates` - 工作区成员
### Cargo/TOML（3）
- `list_dependencies` - `[dependencies]`、 `[dev-dependencies]`、 `[build-dependencies]`
- `list_cargo_features` - `[features]`
- `program_summary` - 高级计数（文件、函数、结构体等）
### 文件操作（2）
- `get_file_content` - 读取文件（带有路径遍历保护）
- `search_source` - 文本搜索
### 使用`syn`的源代码列表（7）
- `list_functions`、`list_structs`、`list_enums`、`list_traits`、`list_impls`、`list_modules`、`list_macros`
### 使用`syn`的检查（4）
- `inspect_function`（带有主体）、 `inspect_struct`（带有字段）、 `inspect_enum`（带有变体）、 `inspect_trait`（带有方法）
### 使用`ra_ap_*`的语义交叉引用（6）
- `analysis_summary` - 验证ASG加载
- `resolve_type` - 来自rust-analyzer的`goto_definition`
- `find_implementations` - `goto_implementation`（特征→实现）
- `get_type_hierarchy` - 类型层次结构
- `function_call_graph` - 调用图入口点（调用者）
- `struct_field_xref` - 字段的引用
### 基于文本的引用（2）
- `find_references` - grep整个单词
- `function_callers` - 基于文本的调用图
### 验证（1）
- `validate_code_reference` - 存在/未找到顶级符号
### Bug-hunt（6）
- `find_unsafe_blocks` - `unsafe { ... }`块
- `find_unwrap_patterns` - `.unwrap()`、`.expect()`调用
- `find_unchecked_patterns` - `mem::transmute`、原始指针操作
- `find_panic_sites` - `panic!`、`unreachable!`、`todo!`
- `find_dead_code` - 未引用的项目（跳过`#[test]`、`#[cfg]`、`#[derive]`、`#[no_mangle]`)
- `find_unused_dependencies` - 在`Cargo.toml`中声明的依赖项未在`.rs`中使用
### 加载（1）
- `list_loaded_projects` - 列出已加载的项目
---
## AI代理配置
### OpenCode / Claude Desktop / VS Code / Cline
添加到`opencode.json` / `claude_desktop_config.json` / 等效：
```json
{
"mcpServers": {
"rust-mcp-server": {
"command": "/path/to/target/release/rust-mcp-server"
}
}
}
```
### Linux（musl二进制文件）
```json
{
"mcpServers": {
"rust-mcp-server": {
"command": "/path/to/target/x86_64-unknown-linux-musl/release/rust-mcp-server"
}
}
}
```
---
## 架构
与其他三个AMS MCP（`cobol-mcp-server`、`java-mcp-server`、`python-mcp-server`）的1:1镜像：
```
rust-mcp-server/
├── src/
│ ├── main.rs / lib.rs / server.rs — 入口点 + 工具注册
│ ├── project_manager.rs — RwLock<HashMap> + 过期
│ ├── project_loader.rs — 路径 / Git CLI / 存档解析器
│ ├── model/ — ProjectEntry, ProjectLoadError, Finding
│ ├── analysis/ — BugPatternAnalyzer（5次扫描）
│ │ ├── analysis_host.rs — ra_ap_ide AnalysisHost包装器
│ │ ├── symbol_resolver.rs — name → SymbolLocation
│ │ ├── syntax.rs — syn包装器（用于静态扫描）
│ │ ├── cargo_manifest.rs — toml包装器
│ │ └── rust_analyzer_utils.rs — ProLeapAnalyzerUtils风格的门面
│ └── tools/ — 36种工具（每种一个结构体）
│ ├── mcp_tool.rs — McpTool trait
│ ├── base_rust_tool.rs — 共享帮助程序
│ └── <tool_name>_tool.rs — 每个工具
└── tests/
├── fixtures/sample_crate/ — 用于测试的最小Rust crate
└── snapshots_test.rs — 43个黄金快照
```
**设计决策**（参见`AGENTS.md` §7了解详情）：
- **详细工具模式**：每个工具一个结构体，`RustMcpServer::build_tools()`中的显式注册。灵感来自`BaseCobolTool` / `BaseJavaTool`。
- **稳定的`McpTool` trait**：工具契约。不要在不审查所有工具的情况下更改。
- **线程安全的ProjectManager**：`tokio::sync::RwLock<HashMap>`，10分钟过期，与`java-mcp-server`相同形状。
- **确定性Markdown**：字节对字节输出，无时间戳。 `tests/snapshots/`中的黄金快照。
- **版本来自`version.txt`**：`build.rs`将其注入`OUT_DIR/version.rs`，`lib.rs`使用`include!`包含它。等效于Java中`version.properties`的Maven过滤。
- **双引擎bug-hunt**：4次扫描使用`syn`（静态，仅解析），1次扫描使用`ra_ap_*`（语义，使用`find_all_refs`）。`SymbolLocation`包括`implicit_references: { test, derive, no_mangle, cfg, allow }`以避免假阳性。
---
## 路线图
| 迭代 | 什么 | 状态 |
|------|------|--------|
| 1 | 骨架：`rmcp` + 工具模式 + `ProjectManager` + 1种工具 + 快照 | ✅ |
| 2 | 本地加载 + 存档（zip/tar.gz/tar.zst/tar.xz）+ 使用`syn` + `toml`的分析 | ✅ |
| 3 | 集成`ra_ap_*` 0.0.343，`analysis_summary` | ✅ |
| 3.5 | `SymbolResolver`，语义`resolve_type` | ✅ |
| 3.6 | 4种语义工具：`find_implementations`、`get_type_hierarchy`、`function_call_graph`、`struct_field_xref` | ✅ |
| 4 | 具有5次扫描的`BugPatternAnalyzer`（4次syn + 1次启发式） | ✅ |
| 4.5 | 语义`find_dead_code`（通过`ra_ap_*`） | ✅ |
| **5** | **使用`cargo-zigbuild` + `zig`交叉编译为musl，并在podman/Alpine中验证** | ✅ |
| 6+ | `find_unused_dependencies`（扫描6）；`SymbolLocation.implicit_references`（跳过`#[test]`/`#[cfg]`）；路径遍历修复；真正的Git clone via `git` CLI；合并的`text_utils::count_whole_word_matches`；用于macOS的rustup shims | ✅ |
| 7+ | `cargo zigbuild --tests`验证；Git clone流程验证；重构扫描到`ra_ap_syntax`延迟（无`Visit` trait） | ✅ |
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器