MCP协议实战——用Serena让AI真正读懂代码

AI 编程助手已经成为开发者的日常工具，但一个普遍的问题是：AI 虽然能生成代码，但对项目的理解往往停留在表面。想让它改个 bug，结果发现它得把整个文件读一遍；让它找个函数调用，又要在一堆代码里盲目搜索。这种体验的根源在于：传统 AI 代码工具把代码当成纯文本处理，缺乏真正的语义理解能力。

Serena 是一个基于 MCP 协议的开源工具，通过引入语言服务器协议（LSP），让 AI 获得了类似 IDE 的代码理解能力。

本文以 Claude Code 为例，详细介绍 MCP 协议的作用、Serena 的工作原理，以及完整的安装使用流程。

1. MCP 协议：给 AI 装上 "USB-C 接口 "

MCP 的全称是 Model Context Protocol（模型上下文协议），是 Anthropic 在 2024 年 11 月推出的一个开放标准。如果要用一句话解释它，那就是：让 AI 能够标准化地连接各种数据源和工具。

Anthropic 的比喻很形象——MCP 就像是 "AI 应用的 USB-C 接口 "。以前我们连接各种设备需要一堆不同的线缆，现在有了 USB-C，一根线搞定。
MCP 也是这个思路：与其让每个 AI 工具都去单独对接各种数据源（Google Drive、Slack、GitHub 什么的），不如搞一个统一的协议，大家都按这个标准来。

从技术角度看，MCP 其实就是基于 HTTP 的 JSON-RPC 协议，轻量、简单、好用。开发者可以写一个 MCP 服务器来暴露数据，AI 应用（MCP 客户端）就能通过标准方式连接上去。

到了 2025 年，这个协议已经不是小打小闹了。

  • OpenAI 在今年 3 月把它整合进了 ChatGPT 桌面版和 Agent SDK；
  • 谷歌的 Gemini 也宣布支持；
  • 微软在 Build 2025 大会上更是把 MCP 当作 Windows 11 AI 功能的基础层。
    可以说，MCP 已经成了行业标准。

2. Serena：把 IDE 的智能搬给 AI

说完 MCP 的大背景，再来看 Serena 就容易理解了。Serena 是一个基于 MCP 协议的开源工具包，专门用来增强 AI 对代码的理解能力。它的核心思路是：让 AI 像 IDE 一样理解代码，而不是当成纯文本来处理。

2.1. 双协议组合拳

Serena 厉害的地方在于它同时用了两个协议：

  • MCP（Model Context Protocol）：
    • 负责 AI 和 Serena 之间的通信。AI 想要查代码、改代码，都通过 MCP 协议来调用 Serena 的工具。
  • LSP（Language Server Protocol）：
    • 这个协议你可能听说过，VS Code、JetBrains 那些 IDE 里 " 跳转到定义 “、” 查找引用 " 这些功能都是靠它实现的。Serena 把 LSP 集成进来，让 AI 也能享受到 IDE 级别的代码理解能力。

这两个协议配合起来是什么效果呢？简单说就是：AI 不再需要把整个文件读一遍才能找到一个函数，它可以直接 " 跳转 " 到目标代码。就像你在 IDE 里按 Ctrl+ 点击一样精准。

2.2. 解决了什么问题？

传统的 AI 代码工具基本都是基于 RAG（检索增强生成）或者纯文本搜索。这种方式有几个致命问题：

  • 理解能力差：AI 把代码当成普通文本，不知道哪个是类定义、哪个是方法调用、哪个变量在哪个作用域
  • 查找不准：想找 "UserService 这个类的所有子类 "，只能靠正则表达式瞎猜，经常漏掉或误判
  • 修改容易出错：改个函数签名，所有调用这个函数的地方可能忘了一起改
  • token 浪费严重：每次都要把整个文件甚至多个文件塞进上下文，才能勉强理解代码关系

Serena 通过 LSP 解决了这些问题。

2.3. LSP 的工作原理

LSP（Language Server Protocol）是微软在 2016 年推出的协议，目的是让各种编辑器都能复用同一套代码分析引擎。

传统 IDE 的困境：以前每个 IDE 都要自己实现代码补全、跳转定义这些功能。想支持 10 种语言？就得写 10 套分析引擎。换个 IDE？又得重新实现一遍。

LSP 的解决方案：把代码分析的逻辑独立出来，做成一个 " 语言服务器 "（Language Server）。IDE 只需要通过 LSP 协议和这个服务器通信就行。你在 IDE 里按 " 跳转到定义 "，IDE 发个请求给语言服务器，服务器分析代码后告诉 IDE 跳到哪一行。

Serena 的妙用：Serena 把 LSP 接到了 AI 这边。当 AI 需要理解代码时，不是自己去读文本、猜语法，而是直接问语言服务器：

  • “UserService 这个类定义在哪？” → 精确定位到文件和行号
  • “login 方法被哪些地方调用了？” → 返回所有引用位置
  • " 这个类有哪些子类？" → 基于继承关系图直接给出答案

这就像是给 AI 配了个编译器级别的 " 显微镜 "，能看到代码的抽象语法树（AST）、符号表、类型信息、依赖关系，而不是盲目地处理文本。

实际效果举例：

  • 传统 AI：读整个文件（2000 行），从第 1 行扫到最后，找到 login 方法定义，消耗大量 token
  • Serena+LSP：直接问语言服务器 "UserService.login 在哪 "，瞬间定位到第 456 行，只读这一个方法，token 消耗降低 70%

目前 Serena 支持 30 多种编程语言，包括 Python、JavaScript/TypeScript、Java、C/C++、C#、Go、Rust、PHP 等等。只要有 LSP 实现的语言，Serena 就能支持。

3. Serena 在 Claude Code 中的完整配置流程

完整的部署流程分为四个步骤：安装与配置、Dashboard 监控、项目激活与 Onboarding、索引加速。

以下以 Claude Code 为例，演示具体操作（其他支持 MCP 的客户端流程类似）。

3.1. 第一步：安装与配置

3.2. 安装 uv 包管理器

Serena 依赖 uv（Python 包管理器），需要先安装：macOS：

brew install uv

Windows（PowerShell 管理员权限）：

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

3.3. 安装 Serena MCP 服务器

在项目根目录下执行：

claude mcp add serena -- uvx --from git+https://github.com/oraios/serena serena start-mcp-server --context ide-assistant --project $(pwd)

命令参数说明：

  • uvx --from git+https://github.com/oraios/serena：从 GitHub 拉取最新版本
  • serena start-mcp-server：启动 MCP 服务器
  • –context ide-assistant：使用 IDE 助手上下文（针对 IDE 环境优化的工具集）
  • –project $(pwd)：指定项目路径为当前目录
    关于项目绑定：--project $(pwd)参数会让 Serena 只在当前项目目录下自动启动，在其他目录运行 Claude Code 时不会加载 Serena。这样可以避免不同项目之间互相干扰。如果需要全局生效，可以去掉该参数，但按项目配置是更推荐的做法。

3.4. 配置文件

安装完成后，Serena 会自动生成两个配置文件：

  • ~/.serena/serena_config.yml：全局配置，包含所有已注册项目列表
  • /.serena/project.yml：项目级配置，包含该项目的特定设置

3.5. 第二步：Dashboard 监控界面

Serena 启动后会默认开启一个 Web Dashboard，用于监控运行状态和查看日志，访问地址：

http://localhost:24282/dashboard/index.html

（如果 24282 端口被占用，会自动使用更高的端口号）

3.6. Dashboard 功能

  • 实时日志流：显示 Serena 调用的工具、LSP 通信细节、错误信息等
  • 运行状态监控：查看当前激活的项目、正在执行的操作
  • 手动关闭服务：部分 MCP 客户端在退出时不会正确清理进程，造成 " 僵尸进程 "，Dashboard 提供手动关闭按钮解决这个问题
  • 配置概览：查看当前生效的配置参数

3.7. 使用建议

首次使用时建议打开 Dashboard 观察 Serena 的工作流程，有助于理解工具调用机制和调试问题。如果不需要 Dashboard，可以在 serena_config.yml 中设置：

web_dashboard: false

3.8. 第三步：项目激活（每次使用都需要）

重要概念：Serena 采用项目管理机制，每次启动 Claude Code 时都需要激活要工作的项目。这不是 bug，而是设计特性——可以避免 Serena 在错误的项目上运行工具。

3.9. 自动激活 vs 手动激活

如果安装时使用了 --project $(pwd) 参数，Serena 会在当前目录下自动激活项目。但如果没有指定，或者切换到其他项目，就需要手动激活：

"激活项目 /path/to/your/project"

或者使用已注册的项目名：

"激活项目 my-app"

激活后，Serena 会在项目根目录创建 .serena/ 文件夹，包含：

  • project.yml：项目级配置文件
  • memories/：记忆文件目录（首次激活后生成）
  • 语言服务器的缓存和索引文件

3.10. Onboarding 过程（仅首次激活）

第一次激活项目时，Serena 会自动触发 onboarding 流程。这个过程的目标是：让 Serena 像新入职的开发者一样，先熟悉项目的整体结构和架构规范。

Onboarding 的具体步骤：

  • 扫描目录结构：识别 src、test、config 等关键目录
  • 分析技术栈：通过 package.json、pom.xml 等文件判断使用的框架和依赖
  • 理解代码组织：找出主要的模块、层次划分（controller、service、dao 等）
  • 提取编码规范：观察命名风格、注释习惯、文件组织方式
  • 生成记忆文件：把上述理解总结成 markdown 文档，保存在 .serena/memories/
    典型的记忆文件示例：
.serena/memories/
├── architecture.md      # 项目整体架构：前后端分离、微服务等
├── modules.md          # 各模块职责：用户模块、订单模块等
├── coding_style.md     # 代码风格：驼峰命名、注释规范等
├── tech_stack.md       # 技术栈：Spring Boot、React、MySQL等
└── directory_structure.md # 目录说明：/api放接口、/utils放工具类等

3.11. 记忆文件的作用

后续每次对话，AI 可以快速读取这些记忆文件，立即进入项目上下文，无需重新分析整个代码库。这类似于新同事入职时的知识交接，后续工作时直接查阅文档即可，不用每次都重新讲解项目架构。

3.12. Onboarding 注意事项

  • 只执行一次：除非手动删除 .serena/ 文件夹，否则不会重复 onboarding
  • Token 消耗：中型项目 onboarding 可能消耗 1000-3000 tokens，建议完成后重启对话避免上下文过长
  • 人工审查：onboarding 完成后，建议检查 .serena/memories/ 内容，如果 AI 理解有偏差（如将测试代码误认为主代码），可直接编辑 markdown 文件纠正
  • 手动补充：如果存在 AI 未发现的项目约定（如 " 所有 DTO 类必须以 DTO 结尾 "），可手动在记忆文件中添加

3.13. 后续使用流程

从第二次开始，工作流程简化为：

  • 启动 Claude Code → 激活项目（若配置了 --project 参数则自动激活）
  • Serena 自动读取 .serena/memories/ 中的记忆文件
  • AI 已具备项目背景知识，直接开始对话

3.14. 第四步：索引加速（大项目必备）

对于大型项目（几万行代码以上），强烈建议做一次索引。索引的作用是：让语言服务器预先分析整个项目，建立符号表和依赖关系图。

不索引的话，第一次调用 Serena 的工具时，LSP 需要临时分析整个项目，可能要等好几分钟。索引之后，这些分析结果会被缓存，查找速度飞快。

索引命令（在项目根目录执行）：

uvx --from git+https://github.com/oraios/serena serena project index

索引过程的耗时取决于项目规模，几万行代码可能需要 1-2 分钟，几十万行可能要 5-10 分钟。但这是一次性投入，后续使用会快很多。

索引时机：

  • 首次 onboarding 后立即索引
  • 项目结构发生大变动后重新索引
  • 感觉 Serena 响应变慢时重新索引

4. 实际使用效果

4.1. 性能提升

配置完成后，AI 编程助手的表现会有显著改善：

  • Token 消耗降低 70%：传统方式需要读取整个文件（2000 行）才能修改一个函数，Serena 可以直接定位到具体函数（20 行），大幅减少上下文消耗
  • 理解精度提升：指令 " 把 UserService 里的 login 方法改成异步 "，AI 能精确定位到目标方法，不会误修改同名的其他方法
  • 响应速度加快：索引建立后，符号查找几乎瞬时完成，无需每次重新分析代码结构

4.2. 适用场景

  • 最佳场景：大型代码库（1 万行以上），特别是多模块、多层次架构的项目
  • 不适合场景：小型脚本项目（几百行代码），Serena 的优势无法体现
  • 禁用场景：CI/CD 流程。Serena 设计用于本地交互式开发，不应集成到自动化流水线中，静态分析工具更适合这类场景

4.3. 安全性说明

所有代码分析均在本地进行，不会上传到外部服务器。.serena/ 文件夹中的配置和记忆文件也都存储在本地，不存在数据泄露风险。

5. 进阶配置技巧

5.1. 只读模式

初次使用时可以开启只读模式，避免 AI 意外修改代码。在 project.yml 中配置：

read_only: true

该模式下 Serena 仅提供代码分析和查询功能，禁用所有编辑工具。熟悉后可关闭该选项。

5.2. Slash 命令集成

可以在 Claude Code 中创建自定义 slash 命令，组合使用 Serena 和其他工具。示例：

Always use serena for semantic code retrieval and editing tools, context7 for up to date documentation on third party code

这样可以让 AI 同时利用 Serena 的语义分析能力和 Context7 的文档检索能力。

5.3. 版本更新

Serena 不会每次启动时自动更新（避免意外引入不兼容版本）。需要更新时，重新执行安装命令：

claude mcp add serena -- uvx --from git+https://github.com/oraios/serena serena start-mcp-server --context ide-assistant --project $(pwd)

5.4. 记忆文件维护

定期检查 .serena/memories/ 内容，确保 AI 对项目的理解准确。可以：

  • 修正 AI 的错误理解
  • 补充项目特有的约定和规范
  • 删除过时的架构描述

6. 总结

MCP 协议和 Serena 代表了 AI 辅助编程的一个重要发展方向：从文本层面的处理提升到语义层面的理解。

传统 AI 代码助手本质上是 " 高级自动补全工具 "，能够根据上下文生成代码，但对项目整体架构的理解停留在表面。MCP 协议提供了标准化的工具连接机制，Serena 通过集成 LSP，让 AI 获得了类似 IDE 的 " 认知能力 "：

  • 理解代码的符号关系（类、方法、变量等）
  • 掌握模块间的依赖关系
  • 精确定位和修改目标代码
    不过需要明确的是，工具的进步并不意味着 AI 能够取代开发者。编程的核心价值在于需求理解、架构设计和技术决策，而不是代码编写本身。AI 的作用是承担重复性和机械性的工作，释放开发者的时间和精力去解决更复杂的问题。

对于使用 Claude Code 或其他支持 MCP 协议的 AI 工具的开发者，Serena 是一个值得尝试的增强方案。通过语义理解能力的提升，可以显著改善 AI 辅助编程的效率和准确性。

参考资源：