AGZ Rust MCP

AGZ Rust MCP

English | Türkçe

AGZ Yazılım 出品。 agz-rust-mcp 是一个独立的 stdio MCP 服务，面向基于 Cargo 和 rustc 的通用 Rust 开发。可离线发现项目、收集精简的源码上下文和编译器诊断、选择单个测试，以及运行二进制文件和示例。精确版本的依赖文档、Rust Analyzer 导航，以及不写入文件的变更／重构方案可支持更深入的工作。

日常工作流

同一工作流适用于库、CLI、服务或多包 Cargo 工作区。无需特定框架的项目结构，也不要求使用特定 MCP 客户端。

需求	工具调用
无需编译即可梳理包、声明的目标、功能和依赖项	workspace(action="inspect")
定位代码并读取有限范围内带行号的源码	workspace(action="search", query="parse_record")，然后运行 workspace(action="read", path="src/lib.rs", line=1, lineCount=80)
获取最新的编译器诊断	check(target="check", options={"packages":["my_crate"]})
查找实际的测试名称	test(action="list", packages=["my_crate"])
按完整名称运行一个库测试	test(action="run", packages=["my_crate"], cargoTarget={"kind":"lib"}, filter="tests::parses_record", exact=true)
编译测试但不执行	test(action="compile", packages=["my_crate"])
执行二进制文件或示例	run(package="my_crate", target={"kind":"example","name":"demo"}, args=["input.json"], timeoutMs=30000)
弄清不熟悉的依赖项 API	使用精确版本调用 docs；进行更深入的解析／探测时使用 api

如果客户端从其他位置启动，请为当前项目传入绝对路径 dir。通过测试或可执行示例来运行函数。run 是类型化的 Cargo 运行器；程序参数会按原样传递，包括空格和 shell 元字符。测试和应用程序会执行项目代码，并产生通常的副作用。空选择会返回 NO_TESTS，而不会判定测试通过。

使用 agz-rust-mcp --toolset core 可获取由六个日常工具组成的精简目录：workspace、check、test、run、docs 和 crate_lookup。默认的 --toolset full 会保留所有现有工具以及新增工具。还可通过单独的 --tools-<name> false 开关进一步禁用工具。有关限制和结果状态，请参阅完整参考。

安装

# installer script (Linux x86_64): download install.sh and SHA256SUMS from the
# latest release, verify the script, then run it
bash install.sh

# crates.io (requires Rust 1.88.0 or newer)
cargo install agz-rust-mcp --locked
agz-rust-mcp --version

Linux x86_64、macOS arm64 和 Windows x86_64 提供预编译的 .tar.gz 压缩包及对应的 .sha256 文件。0.2.0 及更早版本使用旧版 agz-rust-coder-* 资源名称；从 0.3.0 起，名称为 agz-rust-mcp-*。

分步说明、各操作系统注意事项、校验和验证及故障排除：docs/install.md · Türkçe。

MCP 客户端设置

当前源码还捆绑了四个离线技能：agz-rust-workflow、 agz-rust-repair、agz-rust-refactor 和 agz-rust-performance。一个可执行文件 通过 MCP 提示词／资源提供工具及其工作流；无需第二个 MCP。 基于文件系统的客户端可以使用 agz-rust-mcp skills export。 参见捆绑技能。 捆绑技能从 0.4.0 开始提供；0.3.0 二进制文件不包含这些技能。

客户端	配置	指南
ZCode	~/.zcode/cli/config.json → mcp.servers.rust	ZCode
OpenCode	opencode.jsonc → mcp.rust	OpenCode
OpenCode2	opencode.jsonc → mcp.servers.rust	OpenCode2
Codex	~/.codex/config.toml → mcp_servers.rust	Codex

请使用适用于你所用客户端的示例；OpenCode 和 OpenCode2 的配置布局不同。 它们都会启动已安装的 agz-rust-mcp 二进制文件。连接前运行一次 agz-rust-mcp --version， 如果客户端的 PATH 不同，请使用绝对路径。

当前目录是默认的授权根目录。如果客户端从其他位置启动，请通过重复使用 --allow-root 参数添加明确的根目录；客户端提供的 MCP 根目录可以缩小已配置的访问范围，但绝不能扩大范围。有关各客户端的设置，请参见 docs/install.md。

文档

请按以下顺序阅读文档：

1. 安装与客户端设置 - 所有安装方式和 客户端配置。
2. 工具与配置参考 - 工具、操作、结果 语义以及所有配置键。
3. 架构 - 进程模型、协议生命周期 和权限边界。
4. 验证与基准测试协议 - 冒烟测试、门槛和 证据。
5. 安全策略 和贡献指南。

包含完整阅读路径的双语索引见 docs/README.md / docs/README.tr.md。

标识信息

合约	值
Crate、二进制文件、服务	agz-rust-mcp
MCP Registry	io.github.agzyazilim/rust-mcp
源码版本	0.5.0
首次发布	0.1.0
发布标签	agz-rust-mcp-v<version>
Rust 版本／MSRV	2024 / 1.88.0
Rust MCP SDK	rmcp 3.1.4
默认／发现的协议	2025-11-25 / 2026-07-28

MCP 软件包所有权标记：mcp-name: io.github.agzyazilim/rust-mcp。

工具

MCP 客户端可能会为工具名称添加前缀（例如 rust_*）；请使用已连接服务工具目录中的名称。

MCP 工具	带前缀名称示例	默认状态	用途
workspace	rust_workspace	enabled	检查清单/锁定文件、搜索源代码，并在离线状态下读取代码片段，无需 Cargo 或 Rust Analyzer。
test	rust_test	enabled	按精确名称发现、编译或运行选定的测试，并支持控制忽略的测试和限制执行范围。
run	rust_run	enabled	运行指定的 Cargo 二进制文件/示例，支持字面参数、截止时间和输出限制。
check	rust_check	enabled	运行有界的 Cargo 检查、Clippy、测试、文档构建或完整门禁。
profile	rust_profile	enabled	分析观察到的 Cargo 重建行为，并比较有界构建证据，不声称未经测量的提速效果。
audit	rust_audit	enabled	扫描 Rust 源代码，查找有界的静态分析结果。
crate_lookup	rust_crate_lookup	enabled	在 crates.io 上验证 crate 及其可选的精确版本。
docs	rust_docs	enabled	从缓存、本地源代码或 docs.rs 中解析指定版本的文档。
context	rust_context	enabled	准备、扩展或生成绑定到修订版本的语义上下文胶囊，并说明每个条目的原因。
api	rust_api	enabled	根据有界分析器证据解析 API 签名，或在工作区配置的隔离副本中对候选代码片段进行类型检查。
explain	rust_explain	enabled	说明宏展开来源、trait 约束或 cfg 启用情况。
verify	rust_verify	enabled	规划或运行有界的功能、目标、工具链和阶段矩阵。
symbol	rust_symbol	enabled	读取单个符号的 Rust Analyzer 悬停数据。
references	rust_references	enabled	查找有界的引用。
definition	rust_definition	enabled	查找所选定义。
symbols	rust_symbols	enabled	列出单个 Rust 文件中的符号。
implementations	rust_implementations	enabled	查找实现。
hierarchy	rust_hierarchy	enabled	追踪有界的调用层次结构。
rename	rust_rename	enabled	生成经过验证的重命名编辑包，但不应用更改。
refactor	rust_refactor	enabled	生成经过验证的重构编辑包，但不应用更改。
change	rust_change	enabled	在服务端管理的临时环境中创建、暂存、迁移并验证绑定到修订版本的变更集，不写入工作区。
repair	rust_repair	enabled	分析、尝试、比较并精简针对失败变更修订版本的编译器驱动修复候选方案，不写入工作区。
work	rust_work	enabled	通过 change/validate 流程处理类型化意图，使用显式门禁和预算，返回如实的门禁证据或有界的单次使用交接。

每个工具都会返回确定性的结构化数据，以及等效的有界文本回退结果。外部数据保留在 untrustedData 下。编译器失败、缺少 crate 或文档不可用等预期领域结果会以类型化结果表示；无效输入、授权失败、资源耗尽和语义基础设施不可用则属于协议错误。

配置

优先级依次为 CLI、AGZ_RUST_MCP_* 环境变量、显式指定的 --config TOML 文件，最后是默认值。环境变量键在各区段之间使用 __，例如 AGZ_RUST_MCP_GATE__HARD_TIMEOUT_MS=600000。

键	默认值	含义
server.allow_roots	canonical CWD	工作区读取/命令边界。
server.allow_dependency_roots	空	显式指定的外部路径依赖根目录。
gate.hard_timeout_ms	600000	Cargo 操作截止时间。
gate.scope	shadow	验证目标：workspace、shadow 或 affected。
gate.cache	auto	缓存策略：auto、project 或 isolated。
rust_analyzer.workspace_code	deny	除非禁用工作区代码，否则拒绝启动 RA。
docs.fallback	auto	文档来源策略。
profile.max_report_bytes	4194304	单个 Cargo 计时产物的读取/存储上限。
profile.max_runs	4	一次 profile 调用可执行的全新 Cargo 运行次数。
profile.compare_samples	3	在提出任何速度结论前，每侧所需的样本数。
limits.tool_output_bytes	49152	序列化工具结果的最大大小。
change.max_bytes	268435456	每个变更集可捕获的候选内容最大字节数。
repair.max_candidates	4	一次 repair 操作可尝试的候选项数。
repair.max_compiles	4	一次 repair 操作可运行的 Cargo 验证次数。
repair.wall_time_ms	120000	一次 repair 操作的墙钟时间预算。
repair.minimize_max_candidates	32	一次 repair(action=minimize) 可尝试的编译评估缩减次数。
repair.minimize_max_compiles	16	一次 repair(action=minimize) 可执行的 Cargo 运行次数，包括复现和导出验证。
work.max_candidates	4	一个工作项可暂存的主机候选修订数。
work.max_compiles	12	一个工作项可运行的门禁验证次数。
work.wall_time_ms	600000	一个工作项的墙钟时间预算。
telemetry.enabled	true	记录有界的本地活动信息，不包含提示词或源代码。

profile 证据有存储上限：最新的 64 条记录保留在内存中；服务器管理的 profile-evidence 目录下的持久化计时产物会在 24 小时后或文件数超过 64 个时清理。profile 结果会报告此保留策略，因此过期证据会明确显示，而不会被悄然重复使用。

运行 agz-rust-mcp --help 可查看所有 CLI 字段。完整行为说明和默认值表见 docs/tools.md。

安全

该服务不会修改工作区源代码，但它不是操作系统沙箱。Cargo 构建脚本、测试、过程宏、本地 rustdoc，以及已选择启用的 Rust Analyzer 工作区代码，都以服务运行用户的权限执行。如果需要此类隔离，请使用容器或操作系统沙箱。工作区、依赖项、缓存、租约、日志、文档和遥测路径都会经过规范化和范围限制，并采用失败时默认拒绝的策略；标准输出仅用于 MCP 帧传输。请按照 SECURITY.md 中的说明，私下报告漏洞。

链接

• 仓库：https://github.com/agzyazilim/rust-mcp
• Crate：https://crates.io/crates/agz-rust-mcp
• SDK 文档：https://docs.rs/rmcp/3.1.4/rmcp/
• MCP 2025-11-25：https://modelcontextprotocol.io/specification/2025-11-25
• MCP 2026-07-28：https://modelcontextprotocol.io/specification/2026-07-28

许可证

MIT，版权所有 (c) 2026 Ugur Murat Altintas。