CodeCraft

---

为什么要做它

在 Bedrock 中，稍微记错字段名，就会生成无法正常运行的内容，而且不会有任何提示。 没有错误消息，也没有红色波浪线。直到将包加载进游戏，一切看起来都正常。

一个真实示例——两行都通过了架构验证，其中一行却永远无法加载：

  "modules": [
-   { "type": "javascript", "entry": "scripts/main.js" }
+   { "type": "script", "language": "javascript", "entry": "scripts/main.js" }
  ]

使用第一行时，包根本不会出现在行为包列表中。 甚至连错误都不会报。javascript 类型是 1.16 之前遗留下来的内容；为了向后兼容，架构仍然保留了它，但它无法与 @minecraft/server 2.x 一起加载。架构说“类型有效”，游戏却说“无法加载此类型”。

这行内容已在真实游戏中验证（30-08-2026）。还有七类类似情况，均列于 docs/VALIDATION-LIMITS.md，并附有 ContentLog 证据。

CodeCraft 填补了这一空白：**所有值都来自固定版本的数据，**输出则会根据官方架构和真实的 tsc 进行验证。

九种工具

九种工具全部为只读。服务不会写入任何内容，不会向任何地方发送数据，也不会保留用户数据。

工具	返回内容	使用时机
check_feasibility	Bedrock 是否能实现该功能；如果不能，原因是什么，以及有哪些替代方案	生成任何内容之前
get_version_info	版本号应写在哪里、使用哪些模块、哪些 format_version 有效	编写文件之前
get_schema	必填字段，以及该节点的字段列表	编写文件之前
lookup_id	标识符是否存在、属于什么类型、有哪些方块状态	查询每个凭记忆写出的标识符
validate_json	携带 JSON 指针的架构错误	验证生成的每个 JSON 文件
validate_command	命令、参数数量、选择器、方块状态	提交命令之前
validate_script	真实 tsc 诊断信息，包含行、列和 TS 代码	验证每次 API 调用
validate_python	语法、嵌入的命令，以及 /connect 信封	验证游戏外自动化脚本
review_pack	每个文件，以及架构在结构上无法检查的内容	提交任何内容之前的最后一步

排列顺序不是按字母排序，而是按使用顺序排列，且 tools/list 会保留此顺序。

配置

端点	https://codecraft-ashy-seven.vercel.app/mcp
使用网站	codecraft-ashy-seven.vercel.app — 共四个页面：主页、配置、工具、限制
传输方式	无状态 Streamable HTTP，仅支持 POST
身份验证	无——端点为只读，不会返回任何私密内容

在 Claude 中，打开自定义 → 连接器（*不要选“设置”；较早的指南会指向那里，而且该界面没有自定义连接器选项）：

1. 自定义 → 连接器 → 添加自定义连接器
2. 粘贴端点地址
3. 保存

连接后，你应该能看到以下三项——只看到一条“已连接”提示还不够：

• 工具数量为 9，且完整无缺
• 客户端将它们归类为**“只读工具”**——这是单独的权限类别
• 能看到我们自己的标题，例如 “Can Bedrock do this”——工具界面使用英文

更多信息：docs/MCP.md

验证的边界

这张表不是宣传，而是在说明限制。“通过验证”和“在游戏中可用”并不是一回事——有八类错误能通过验证，却会在游戏中导致问题，而且每一类错误都在实际游戏中测量过。

类别	架构是否能发现	CodeCraft 的处理方式
A · 身份引用	不能，但可以解析	checkIdentities 会找到它
A′ · 路径 / 声音引用	不能	checkReferences、checkSounds — 警告；游戏本身不会给出任何提示
B · 文件名 ↔ 标识符	从结构上无法发现	checkFileNames 会告诉你正确的名称
C · 纹理 / 资源引用	不能	checkAssets 会根据原版图集进行检查
D · 有效但并非预期	从结构上无法发现	checkPatterns 会衡量已知模式
E · 永远不会加载的清单	不能 — 过时的类型仍在列表中	checkManifest 会指出正确的类型
F · Molang	不能 — 没有任何东西会检查字符串内部	checkMolang；unknown-query 是错误，已在游戏中测量
G · 组件名称	不能 — 两种架构来源都允许它通过	checkComponents，仍是警告（见下文）
H · 依赖版本的必填字段	从结构上无法发现 — 必填要求取决于 format_version	checkRecipes — 错误，配方永远不会加载

F 和 G 值得再读一遍。 游戏对二者的拒绝方式完全一样 — 整个方块定义都会被丢弃。F 被提升为错误，而 G 没有，因为我们自己的组件 索引存在已测得的 126 个名称的缺口。严重程度不仅取决于“游戏会怎么做”，还取决于“我们的 列表有多完整” — 这是两个独立的问题，不进行测量就无法回答其中任何一个。

这些工具只负责查找和报告，不会写入 — 该端点为只读，修复工作由调用方负责。尚未解决的部分也记录在这里： docs/VALIDATION-LIMITS.md

Bedrock 有五种独立的版本号

混淆在这里造成的影响最大，这也是该工具存在的部分原因：

版本号	示例	使用位置
市场宣传版本号	26.40	仅用于公告。绝不会写入任何文件
游戏 / 数据版本	1.26.40.5	data/ 文件夹名称、数据索引
min_engine_version	[1, 26, 40]	manifest.json — 一个三段式数组
@minecraft/server 模块版本	2.9.0	manifest.json → dependencies
format_version	1.21.100、1.13.0、2	内容文件

**format_version 是独立的维度，与游戏版本无关：**它是该文件类型的架构版本。方块为 1.21.100，功能规则为 1.13.0，生成规则为 1.8.0，清单为 2。游戏版本变化时，它不会改变。

模块版本本身也是个陷阱 — 游戏版本会嵌入在预发布标签中：

2.9.0                              stable module version (npm "latest")
2.11.0-beta.1.26.50-preview.27     module 2.11.0, game 1.26.50-preview.27

正确的值不是靠回忆，而是从架构中读取 — 这正是 get_schema 和 get_version_info 的用途。

架构

flowchart LR
    C["Claude<br/>you bring the model"] -->|MCP / HTTP| M["packages/mcp<br/>9 read-only tools"]
    M --> V["packages/validator<br/>ajv · tsc · commands · python"]
    V --> K["packages/knowledge<br/>lookup · version resolution"]
    K --> D[("data/<br/>indexes per version")]
    P["pipeline/<br/>daily cron"] -->|produces| D
    U["Mojang · Blockception<br/>npm · MicrosoftDocs"] -->|fetches| P

依赖关系只朝一个方向：mcp → validator → knowledge → data。没有任何反向导入。

无需构建步骤。 Node 会直接运行 .ts 文件；tsc 仅用于类型检查，以及作为子进程供 validate_script 使用。

数据

data/ 不是数据库，而是一组存放在 git 中并在其中进行版本管理的索引。八个采集器从四个上游来源生成这些索引。

来源	提供内容	许可证
Mojang/bedrock-samples	方块／物品／实体标识符、命令语法、纹理图集	Minecraft EULA — 仅衍生事实
Blockception/…json-schemas	验证所依据的架构	BSD-3-Clause
npm @minecraft/*	脚本类型定义	MIT
MicrosoftDocs/minecraft-creator	发行说明	CC-BY-4.0

GitHub Action 会按计划刷新这些数据，数据新鲜度检查会在数据过期时发出报告。Cron 设定为 UTC 05:00——但它不会在那时运行。 2026-03-09 测量的全部五次计划运行都延迟启动，最短延迟 4 小时 24 分钟，平均约 5 小时；GitHub 会将计划任务排入队列，并在负载较高时延迟运行。因此，索引可能最多过期 1 天 + 约 5 小时。

上游原始数据绝不会进入仓库。 索引中只包含衍生事实：某个标识符是否存在、字段名称、版本号。推理和测量记录见：docs/SOURCES.md

不变条件

1. 验证层绝不会调用大模型。 本仓库中的任何软件包都不依赖大模型 SDK。这条规则不只是一句话，而是一项测量：packages/mcp/test/no-llm.test.ts
2. 端点为只读。 九个工具都带有 readOnlyHint
3. data/ 存放在 git 中。 没有数据库
4. 免费层是必需条件，而非限制
5. 上游原始数据绝不会进入仓库

如何记录测量结果

在本仓库中，“它能用”和“它经过测量”是两回事。 只有经过测量后才会写下声明，并在其旁注明测量方式和日期。后来证明有误的测量不会删除；它会被删除线标记，并记录其后续情况。

这就是代码中“已测量（日期）”注释的含义：每一条都记录了一次确实发生过的问题。

文档

以下文档使用土耳其语编写，是开发者的工作笔记。产品面向用户的内容使用英语：工具、服务说明、所有发现和错误消息，以及网站。

CLAUDE.md	架构、不变条件、版本维度
docs/MCP.md	端点、设置、工具约定
docs/mcp-kullanim.md	工具的实际使用情况、测量记录
docs/site-icerik.md	使用网站的内容和测量记录
docs/SOURCES.md	数据来源及其许可证
docs/VALIDATION-LIMITS.md	验证无法捕获的问题
docs/COMMANDS.md	命令验证及其范围
docs/WEBSOCKET.md	WebSocket 桥接及其测量结果

许可证

代码采用 Apache-2.0 许可证。本仓库包含采用三种不同许可证的第三方内容，并生成基于第四种许可证内容衍生的数据——THIRD-PARTY-NOTICES.md 说明了各自的许可证。

---