Cocos 游戏项目的 Claude Code 配置实践(5)：MCP

Cocos 游戏项目的 Claude Code 配置实践(5)：MCP

系列文章目录：总览 → CLAUDE.md → Rules → Skills → [MCP] → Hooks → Agents

朋友们大家好，我是 bit老宫 呀，一个拥有12年一线开发经验的CocosCreator游戏开发者，代表作 《比特小队》 《宫爆老奶奶家族篇》

前三层解决的是「规范问题」——告诉 AI 项目用什么、怎么写。但还有一类问题它们解决不了：AI 不认识你的框架 API。

你可以在 Rules 里写「用 AssetLoader 加载资源」，但 AI 不知道 AssetLoader.start() 的参数是什么类型、返回值是什么、有哪些生命周期回调。它只能凭印象猜——猜对了是运气，猜错了你要花时间纠正。

MCP 就是为了解决这个问题。

为什么需要 MCP

Claude 的训练数据有截止日期，对主流框架（React、Vue、Node.js）覆盖得不错，但对小众框架和私有框架基本是空白。我用的 bit-framework 是自研框架，Claude 从来没见过。

不用 MCP 之前的日常：

我：用 AssetLoader 加载一批资源 AI：（写了一段代码，loader.load([...]) 这样的调用） 我：不对，方法名是 start，参数是 IAssetConfig[] 类型 AI：抱歉，请问 IAssetConfig 的字段有哪些？ 我：（贴文档……）

每次涉及框架 API 都要来这么一轮，效率很低。

MCP 是什么

MCP（Model Context Protocol）是一套标准协议，让 AI 能够调用外部工具。它本身不提供任何能力，只是定义了 AI 和工具之间的通信方式——就像 HTTP 协议本身不提供网页内容，但让浏览器能访问服务器一样。

在我的项目里，真正提供「查 API」能力的是我构建的本地向量数据库。我把自有框架和 Cocos Creator 的 .d.ts 文件解析、向量化，存成可搜索的索引。Claude Code 通过 MCP 协议连接到这个数据库，用自然语言查询 API 签名。

Claude Code 原生支持 MCP Server 配置，你只需要在项目的 .claude/mcp.json 里声明 Server 地址，启动后 AI 就能使用你暴露的工具。

做法：把 .d.ts 变成可搜索的语义库

框架的类型声明文件（.d.ts）是最好的 API 文档——包含所有类、方法、参数、返回值的完整定义，而且是机器可读的结构化数据。

我的方案是：

1. 收集 .d.ts 文件：把私有框架和 Cocos Creator 3.8.8 的 .d.ts 放到指定目录
2. 解析并拆分：将 .d.ts 按类/接口/模块拆分成独立的文档片段
3. 向量化建索引：用 @huggingface/transformers 对每个片段做 embedding，存成本地向量索引
4. 包装成 MCP Server：用 @modelcontextprotocol/sdk 暴露查询工具

目录结构：

.claude/mcp/
├── dts/
│   ├── framework/     # bit-framework 的 .d.ts 文件
│   └── cocos/         # Cocos Creator 3.8.8 的 .d.ts 文件
├── index/             # 构建好的向量索引
├── src/
│   ├── server.js      # MCP Server 入口
│   ├── searcher.js    # 语义搜索逻辑
│   └── build-index.js # 索引构建脚本
└── package.json

为什么选 @huggingface/transformers

几个原因：

1. 纯本地运行：不依赖外部 API，不用联网，不泄露代码
2. 免费：不需要 OpenAI 或其他服务的 API Key
3. 轻量：模型首次下载后缓存在本地，后续启动很快
4. 质量够用：对 API 文档的语义搜索来说，开源 embedding 模型的效果完全够

当然也有缺点：首次构建索引时需要下载模型（几百 MB），在国内网络环境下可能需要配镜像源。我用的是 HF_ENDPOINT=https://hf-mirror.com 环境变量。

对外暴露的四个工具

工具	用途	适用场景
search_api(query, source?)	语义搜索，支持中英文	不确定用什么 API 时，用自然语言搜索
get_module(moduleName)	查看模块所有类	了解一个模块有哪些可用的类
get_class(className)	查看类完整定义	查看某个类的所有属性和方法
get_method(className, methodName)	查看方法签名	确认方法的参数类型和返回值

source 参数支持 "framework" / "cocos" / "all"，可以限定搜索范围。

实际使用场景

场景一：AI 不确定方法签名

AI 需要调用 Window.onShow() 但不确定参数类型。它会自动调用：

get_method("Window", "onShow")

返回：protected onShow(userdata?: unknown): void —— 参数是可选的 unknown 类型。AI 拿到准确签名后写出正确代码，不需要人工介入。

场景二：用自然语言查 API

用户说「我需要延迟执行一个操作」。AI 不确定用哪个 API，调用：

search_api("延迟执行")

返回 GlobalTimer.startTimer(callback, interval, loop) 的定义和说明。中文搜索也能命中英文 API 名称——这就是语义搜索的价值。

场景三：探索一个模块

AI 需要了解 bit-ui 模块有什么可用的东西：

get_module("bit-ui")

返回模块下所有类和接口的列表：Window、WindowManager、WindowType、AdapterType……

效果对比

配置前：AI 写私有框架的调用代码，参数顺序经常错、方法名拼错、返回值类型猜错。每次都要人工纠正。

配置后：AI 遇到不确定的 API，直接调用 MCP 工具查签名，然后写出完全正确的调用代码。整个过程在后台自动完成，你甚至不需要知道 AI 查了什么。

这种感觉就像：以前 AI 是个「背过一些文档但记忆模糊」的实习生，现在变成了「手边随时有文档可以查阅」的正式员工。

索引维护

MCP 不是配一次就完事的，需要持续维护：

• 框架更新：框架发了新版本、新增了 API，需要更新 .d.ts 文件并重建索引
• 重建命令：cd .claude/mcp && npm run sync
• 索引大小：我的项目（私有框架 + Cocos 3.8.8 完整 API）索引大约 20MB，构建时间 1-2 分钟

踩坑经验

坑一：大文件拆分不当

Cocos Creator 的 .d.ts 文件巨大（单文件几万行）。直接整文件做 embedding 效果很差——向量化后语义信息被稀释了。必须按类/接口拆分成独立片段，每个片段控制在合理长度内。

坑二：搜索结果太多

语义搜索返回的结果如果太多，AI 的上下文被塞满，反而影响代码生成质量。我限制了每次搜索最多返回 5 条结果，够用且不干扰。

坑三：模型选择

不同 embedding 模型对中英文混合内容的支持差异很大。测试了几个后，选了一个对中英文都表现不错的多语言模型。具体模型选择建议根据实际效果测试决定。

这层值不值得做？

说实话，MCP 是六层里投入最高的。如果你用的是 React、Vue、Express 这类主流框架，Claude 本身就懂，不需要 MCP。

但如果你满足以下条件之一，MCP 的投入就值得：

• 使用私有框架或团队内部封装的 SDK
• 使用小众引擎或框架，Claude 训练数据覆盖不足
• 框架 API 变化频繁，AI 的知识经常过时
• 团队多人使用 Claude Code，需要统一的 API 知识库

对我的游戏项目来说，私有框架 + Cocos Creator（文档质量堪忧），MCP 的价值非常明显。

下一篇

前四层都是「告诉 AI 应该怎么做」——靠 AI 自觉遵守。但 AI 有时候会「忘记」规范，尤其是在长对话里。下一篇聊 Hooks——在系统层面强制执行，无论 AI 做了什么都会触发检查。