game-knowledge MCP Server
为 Cocos Creator 3.8.8 + bit-framework 提供 AI 知识库查询服务。
索引文件（index/）和 .d.ts 文件（dts/）已预构建并提交到仓库，clone 后即可直接使用。
目录
快速安装
要求：Node.js >= 22
git clone ~/tools/bit-framework-mcp
cd ~/tools/bit-framework-mcp
npm install安装完成后无需启动，AI 编辑器会在需要时自动拉起 MCP Server。
配置 AI 编辑器
Claude Code
在游戏项目目录的 .claude/settings.json（或全局 ~/.claude/settings.json）中添加：
{
"mcpServers": {
"game-knowledge": {
"command": "node",
"args": ["/你实际clone的路径/bit-framework-mcp/src/server.js"]
}
}
}配置后重启 Claude Code，运行 /mcp 命令确认 game-knowledge 状态为 connected。
Cursor
在游戏项目根目录的 .cursor/mcp.json 中添加：
{
"mcpServers": {
"game-knowledge": {
"command": "node",
"args": ["/你实际clone的路径/bit-framework-mcp/src/server.js"]
}
}
}新游戏项目接入
每个游戏项目需要完成以下两步，让 AI 具备框架规范感知能力。
第一步：复制 CLAUDE.md 和代码模板
# 在游戏项目根目录执行
MCP_PATH=/你实际clone的路径/bit-framework-mcp
GAME_PATH=/你的游戏项目路径
# 复制 AI 规范文件（告诉 AI 如何写代码）
cp $MCP_PATH/CLAUDE.md $GAME_PATH/CLAUDE.md
# 复制代码模板（供 AI 参考的标准写法）
cp -r $MCP_PATH/bit-templates $GAME_PATH/bit-templates第二步：在游戏项目中扩展 CLAUDE.md（可选）
游戏项目有自己特有的规范时，在复制来的 CLAUDE.md 底部追加项目专属内容：
## 项目特有规范
### 场景结构
- 主场景入口：`assets/scenes/Game.scene`
- UI 预制体统一放在：`assets/ui/`
### 事件命名
| 事件名 | 说明 |
|--------|------|
| GAME_START | 游戏开始 |
| PLAYER_DEAD | 玩家死亡 |注意：Claude Code 的 CLAUDE.md 不支持跨文件@引用（即不能在 CLAUDE.md 里写@其他文件路径来自动加载）。 目前最可靠的方案是把通用框架规范复制到游戏项目的 CLAUDE.md，再追加项目专属内容。 如果框架规范有更新，重新执行第一步覆盖，再补回项目专属部分。
bit-templates 说明
复制到游戏项目后，AI 在新建组件时会自动参考这些模板：
| 模板文件 | 用途 |
|---|---|
ExampleWindow.ts | UI 窗口（继承 Window + @uiclass 装饰器） |
ExampleManager.ts | 单例 Manager（继承 Module + GlobalEvent 通信） |
ExampleECSComponent.ts | ECS 组件（@ecsclass + @ecsprop 装饰器） |
ExampleECSSystem.ts | ECS 系统（@ecsystem + World.iterate 查询） |
可用工具
MCP Server 启动后，AI 可直接调用以下工具查询 API：
| 工具 | 说明 | 示例 |
|---|---|---|
search_api | 语义搜索（支持中英文互搜） | search_api("延迟执行") |
get_module | 查询模块包含的所有类/接口 | get_module("bit-ui") |
get_class | 查询类的完整属性和方法 | get_class("Window") |
get_method | 查询特定方法签名 | get_method("Window", "onShow") |
search_api 支持的 source 参数：
all（默认）：同时搜索框架和 Cocos 引擎 APIframework：只搜索 bit-framework 模块cocos：只搜索 Cocos Creator 3.8.8 API
框架更新后同步索引（框架维护者操作）
普通成员不需要执行此步骤，git pull 拉取最新索引后重启编辑器即可。# 1. 手动复制有变动的模块 .d.ts（以 bit-ui 为例）
cp /path/to/bit-framework/bit-ui/dist/bit-ui.d.ts dts/framework/bit-ui.d.ts
# 2. 重建索引（首次运行需下载向量模型 ~120MB，存入 models/ 目录）
npm run sync
# 3. 提交并推送（不需要提交 models/ 目录，已在 .gitignore 中）
git add dts/ index/
git commit -m "chore: 同步框架索引 vX.X.X"
git push国内网络若下载模型超时，npm run sync 默认已启用 hf-mirror.com 镜像，也可手动指定：
HF_ENDPOINT=https://hf-mirror.com npm run sync首次构建索引
仓库已包含预构建索引，以下步骤仅在完全重建时需要。
# 1. 放入 Cocos 3.8.8 类型定义
cp /path/to/cc.d.ts dts/cocos/cc.d.ts
# 2. 放入框架 .d.ts（每个模块一个文件）
cp /path/to/bit-ui.d.ts dts/framework/bit-ui.d.ts
cp /path/to/bit-ecs.d.ts dts/framework/bit-ecs.d.ts
# ... 其余模块同理
# 3. 构建索引（Cocos 类较多，向量化需要几分钟）
npm run sync
# 4. 提交
git add dts/ index/
git commit -m "feat: 初始化框架索引"
git push项目结构说明
bit-framework-mcp/
├── src/
│ ├── server.js # MCP Server 入口，定义 4 个查询工具
│ ├── searcher.js # 索引查询逻辑（关键词 + 向量语义搜索）
│ └── build-index.js # 索引构建脚本（解析 .d.ts → JSON + 向量）
├── dts/
│ ├── framework/ # bit-framework 各模块 .d.ts（已预置）
│ └── cocos/ # cc.d.ts（Cocos 3.8.8，已预置）
├── index/ # 构建产物（已预置，勿手动修改）
│ ├── framework.json # 框架类索引
│ ├── framework-vectors.json # 框架语义向量
│ ├── cocos.json # Cocos 类索引
│ └── cocos-vectors.json # Cocos 语义向量
├── bit-templates/ # 代码模板（供 AI 参考，需复制到游戏项目）
│ ├── ExampleWindow.ts
│ ├── ExampleManager.ts
│ ├── ExampleECSComponent.ts
│ └── ExampleECSSystem.ts
├── models/ # 向量模型缓存（.gitignore，本地自动生成）
├── CLAUDE.md # AI 编码规范（需复制到游戏项目）
└── package.json