Serena MCP 完整使用教程（适配你的 Cocos+Oops TS游戏项目，解决一次性读大量源码耗token问题）

Serena核心作用：符号级代码检索，AI不再一次性读取整个文件/整个仓库；需要哪个函数、哪个类，才单独拉取那一小段代码，大幅削减token消耗，刚好解决你之前Cursor索引Oops框架直接把额度耗尽的痛点。
原理：基于LSP语言服务器，识别TS的类、函数、接口，而不是把文件当纯文本全文读取。
项目地址：https://github.com/oraios/serena

一、前置依赖安装（Windows/Mac通用）

Serena推荐用uv包管理器（比pip简单很多）

1. 安装 uv

   # Windows（PowerShell）
   powershell -ExecutionPolicy ByPass -c "irm [https://astral.sh/uv/install.ps1](https://astral.sh/uv/install.ps1) | iex"
   
   # Mac
   curl -LsSf [https://astral.sh/uv/install.sh](https://astral.sh/uv/install.sh) | sh

   安装完成重启终端，让环境变量生效。

2. 安装 Serena-agent

   uv tool install -p 3.13 serena-agent@latest --prerelease=allow

3. 初始化Serena（下载语言服务依赖，只需要跑一次）

   serena init

   执行完输入 serena --help，能正常输出帮助就代表安装成功。

二、接入到 Trae（推荐，你准备切换的免费AI编辑器）

Trae支持MCP，直接配置项目级MCP服务：

1. 打开你的Cocos游戏项目（根目录）

2. 在项目根新建文件夹 .trae，里面新建 mcp.json

   {
     "servers": [
    {
      "name": "serena",
      "transport": "stdio",
      "command": "serena",
      "args": [
        "start-mcp-server",
        "--context=ide",
        "--project",
        "${workspaceFolder}"
      ]
    }
     ]
   }

3. 重启Trae，进入项目，打开AI聊天面板 → 设置 → MCP，看到serena状态绿色就是成功。

   ${workspaceFolder} 自动读取当前项目根目录，也就是你的Cocos项目根，Serena会自动索引。

接入Cursor的配置（如果你后续还要用Cursor）

在项目根新建 .cursor/mcp.json

{
  "mcpServers": {
    "serena": {
      "command": "serena",
      "args": [
        "start-mcp-server",
        "--context=ide",
        "--project-from-cwd"
      ]
    }
  }
}

保存，重启Cursor。

三、针对你的《弹力幻境》项目，Serena的配置优化（重点）

Serena会读取项目文件，你需要过滤不需要索引的目录，避免它扫描library、缓存、demo，和.traeignore配合：

1. 在项目根新建 .serenaignore，内容：

   # Cocos编译缓存
   library/
   temp/
   build/
   dist/
   node_modules/
   
   # Oops示例代码，不需要让serena索引demo
   oops/demo/
   oops/example/
   
   # 只保留 code/业务代码 + oops核心源码
   *.log
   .DS_Store

   Serena会读取这个忽略清单，不会去索引缓存文件，只解析code/下面你的TS业务脚本 + oops框架核心代码，极大减少索引体积。

四、使用方式（对话指令，直接复制丢给AI）

激活成功之后，在AI聊天框直接发指令，Serena会自动调用符号检索工具：

使用serena：查找code/下所有弹力相变相关函数，只读取函数签名和实现，不要读取整个文件。

使用serena：查找oops.message的on和off方法，查看定义。

使用serena：找到GameManager类，分析依赖，新增小球对象池逻辑。

✅ Serena能做到：

• 查找函数、类、接口定义，按需读取片段，不加载完整文件，省大量token
• 查找函数调用关系，找到哪里调用了某个方法
• 重命名类/函数，跨文件批量修改符号（TS类型安全）
• 查看类型继承关系

❌ Serena不做：写完整大段业务代码、运行游戏、调试Cocos引擎物理。它是代码检索工具，用来减少AI读代码时的token开销。

五、使用工作流（适配你的游戏开发）

1. 打开Trae，加载Cocos项目，serena自动后台索引（首次索引会慢几十秒，后续走缓存很快）
2. 写代码时，直接让AI调用serena检索code/目录里的类/函数
3. AI不再@整个项目，只通过serena符号检索按需拉取代码片段
4. 配合 .traeignore + .serenaignore 双重过滤缓存目录，从根源解决一次性加载海量源码耗尽额度

六、坑点提醒（必看）

1. Serena依赖TypeScript语言服务，本地需要安装Node+TS，否则TS解析会失败
2. 第一次索引会扫描项目，一定要配置.serenaignore，否则还是会扫描library、node_modules，索引慢、耗资源
3. Serena免费版使用LSP后端，足够TS项目使用；JetBrains后端是付费，你不需要
4. 它不能替代.traeignore，两者搭配：.traeignore控制Trae内置索引，.serenaignore控制Serena符号索引

备选简化方案：不想装Serena，用Repomix

如果你觉得Serena配置略复杂，Repomix是命令行一次性打包精简代码，适合一次性给AI看架构，不用常驻后台。

repomix --include "code/**/*,oops/**/*" --exclude "oops/demo/**/*,library/**/*,temp/**/*,build/**/*,node_modules/**/*" --compress

--compress AST精简，只保留函数签名，砍掉函数内部实现，token大幅压缩。

推荐你当前的组合方案

Trae + Serena MCP + .traeignore + .serenaignore

• Trae免费SOLO Agent无硬限额
• Serena按需读取代码片段，避免一次性读大量源码
• 双重ignore过滤缓存、demo目录，杜绝爆token的问题
• 适配 Cocos3.8.8 + Oops + TS微信小游戏

版权属于：Joyber

本文链接：https://blog.qqvbc.com/default/Serena-MCP-token.html

转载时须注明出处及本声明