Bevy Manual MCP

bevy-manual-mcp

此 MCP 由人类设计，并借助 AI 工具构建，以提高开发速度。

Bevy 是一个快速发展的项目，每次发布都会有所变化。它的文档规模庞大且分散，因此要找到真正适用于你所用版本的答案，往往需要翻查 rustdoc 签名、Bevy Book、迁移指南、发行说明和可运行示例——最后找到的内容仍可能是针对其他版本编写的。此服务会尽力消除这种阻碍。

你向 Agent 提出问题，它便会根据与你的项目所用 Bevy 版本完全匹配的知识作答。

要点：

• MCP Registry 名称：mcp-name: io.github.kinkirill/bevy-manual-mcp

• 原生。 Rust、stdio MCP，用户的路径中无需 Node 或 npm。（此 MCP 的初始版本使用 JS 编写，之后改用 TS 编写。）

• 轻量。 每个 Bevy 版本的包为 33 MB（125 MB 语料库 + 15 MB tantivy 索引，采用 zstd 压缩）。

• 快速。 冷启动约 10 ms，概念查询耗时 22–30 ms，精确查找不到 1 ms。

• 坦诚。 每个工具都会说明自身的能力边界：bevy_validate_systems 是语法级代码检查器，兼容性可能为 "unknown"，缺失的元数据会报告为缺失。

安装

cargo install bevy-manual-mcp

需要 Rust 工具链。没有预编译二进制文件矩阵，也没有 npm 垫片。

服务会立即开始响应。如果检测到的 Bevy 版本没有已安装的索引，它会在后台下载预构建包（进度显示在 stderr），并在安装完成后重新加载索引。若要在启动服务前显式安装：

bevy-manual-mcp fetch-index 0.20.1
bevy-manual-mcp status

索引发布按 Bevy 次版本划分（v0.20）；如果存在精确补丁版本的语料库，就会使用该语料库，否则该次版本中最新的语料库会为此补丁版本提供答案。状态、搜索结果和资源都会报告项目版本，以及实际提供数据的语料库版本。BEVY_MCP_OFFLINE=1 会禁用所有下载，包括后台获取。

使用

裸命令就是 MCP 服务（stdio），与 MCP 客户端启动它的方式完全一致。

bevy-manual-mcp                 # serve MCP over stdio
bevy-manual-mcp serve           # explicit form
bevy-manual-mcp --help
bevy-manual-mcp status          # detected version, corpus state, paths
bevy-manual-mcp versions        # installed corpora
bevy-manual-mcp search "system ordering"
bevy-manual-mcp lookup Query::iter --json

MCP 客户端配置

大多数客户端只需要一个命令：

{
  "mcpServers": {
    "bevy-manual-mcp": {
      "type": "stdio",
      "command": "bevy-manual-mcp",
      "env": {
        "BEVY_PROJECT_ROOT": "/path/to/your/bevy/game"
      }
    }
  }
}

如果客户端的工作目录就是 Cargo 项目，则 BEVY_PROJECT_ROOT 为可选项；版本会优先从 Cargo.lock 读取，其次从 Cargo.toml 读取。

工具

工具	解答内容
bevy_search	混合 API + 文本搜索：签名、Book、指南、示例
bevy_api	精确查询符号，提供真实签名、文档和相关条目
bevy_examples	针对任务可运行的引擎/Book 示例
bevy_migration	两个 Bevy 版本之间的破坏性变更
bevy_api_diff	查询你指定的已编译版本中的某个符号
bevy_check_version	最新发布的 Bevy 版本、补丁版本还是破坏性变更、预发布版本
bevy_indexed_versions	此安装能够回答哪些 Bevy 版本的问题
bevy_index_status	自我诊断：活动版本、语料库、路径
bevy_mcp_check_release_index	此服务的 GitHub 索引发布版是否有更新的语料库/修订版
bevy_check_manifest	已启用的 Cargo 功能，以及符号是否可用
bevy_validate_systems	语法级 B0001/B0002 lint（识别元组、过滤器）
bevy_explain_error	解释粘贴的 panic/警告，并检查版本
bevy_ecosystem_search	在 Bevy 语料库和已安装的插件语料库中扇出搜索
bevy_ecosystem_compat	根据 vendored 快照检查插件 ↔ Bevy 兼容性
bevy_generate_plugin	独立的插件脚手架，使用 syn 解析
bevy_perf_advisor	性能主题，以及 is_changed/is_added 检测

bevy_validate_systems 不会进行类型检查，也无法判断 Bevy 运行时 panic；它能识别 B0001/B0002 访问模式，并会说明分析何时不完整。由于不会运行编译器，bevy_generate_plugin 会报告 compile_verified: false。bevy_ecosystem_compat 仅支持离线使用；对于它不会评估的需求运算符，会返回 compatible: "unknown"。

资源

该服务还会公开 bevy:// 资源和模板：

bevy://index/versions
bevy://api/<version>/<full::path>
bevy://kind/<version>/<kind>
bevy://module/<version>/<module>
bevy://crate/<version>/<subcrate>
bevy://owner/<version>/<Type>
bevy://doc/<version>/<rustdoc file>

列表页面每页显示 50 项，并使用绑定查询的游标；读取时会按需打开请求的版本。

配置

文件（bevy-mcp.config.json）、环境和默认值按此顺序合并；环境变量优先。

变量	含义
BEVY_PROJECT_ROOT	用于检测版本的 Cargo 项目
BEVY_VERSION	显式版本覆盖，例如 0.20.0
BEVY_MCP_DATA_DIR	持久化语料库目录（默认值为 ~/.cache/bevy-mcp/data）
BEVY_MCP_OFFLINE	1 表示禁用下载
BEVY_MCP_INDEX_BASE_URL	fetch-index 发布版的镜像
BEVY_DOC_DIR	用于 build --doc-dir 的本地 rustdoc 树
BEVY_WEBSITE_DIR / BEVY_EXAMPLES_DIR	用于重建的本地文本/示例源
BEVY_META_DIR	vendored bevy-meta 根目录（功能图、错误代码）
BEVY_MCP_COMPAT_PATH	显式的 compat.json 路径
BEVY_MCP_MAX_RESULTS	默认结果数量，1–20
BEVY_MCP_DEBUG	1 表示输出计时/进度诊断信息

配置文件还接受用于插件语料库的 corpora 数组：

{
  "corpora": [
    { "crate": "bevy_egui", "version": "0.43.1" },
    { "crate": "bevy_rapier3d", "auto": true }
  ]
}

插件语料库位于 data/corpora/<crate>/<version>/ 下，并通过常规 build 命令构建。

重建索引

# From a local `cargo doc` tree (or a docs.rs mirror)
bevy-manual-mcp build --doc-dir target/doc

# Canonical NDJSON input
bevy-manual-mcp build --records records.ndjson --out data/versions/0.20.0

# Release bundle + manifest
bevy-manual-mcp build --doc-dir ~/.cache/bevy-mcp/bevy-0.20.0 \
  --pack dist/bevy-0.20.0-fmt1.tar.zst \
  --manifest dist/index-manifest.json

在 release 模式下，从 8,665 个 rustdoc 页面完整重建 0.20.0 版本约需 30 秒，并会生成完全符合规范的语料库：253,196 条记录、653,264 个符号键、15.2 MB tantivy 索引。请参阅 GETTING-API-DOCS.md 和 HOW-IT-WORKS.md。

开发

有关目录结构、测试、索引重建和发布流程，请参阅 docs/DEVELOPING.md。

许可证

MIT。Vendored Bevy 元数据和网站文本的许可信息请参阅 docs/THIRD-PARTY-NOTICES.md。