每周一个MCP：Serena MCP

背景

想象一下，你有一位才华横溢的AI编程助手，但它像个“代码盲人”：你只能把代码片段一段段地复制到聊天框里，它无法感知项目的全貌，不知道函数之间的调用关系，修改代码就像在黑暗中摸索。这正是当前大多数AI编程工具的现状。

而 ​Serena MCP​ 的出现，彻底终结了这个时代。它不是一个单独的AI模型，而是一个超级工具包，为你已有的AI（无论是 Claude、GPT 还是本地模型）装上了一个“IDE大脑”，让它从“文本生成器”蜕变为真正的“软件工程师”。与传统编码工具不同，Serena 完全不依赖特定框架，通过提供 语义代码检索和编辑工具 弥合了 LLM 与专业开发环境之间的鸿沟，并提供了类似 IDE 的语义代码理解和操作能力，可在符号级别运行。无需依赖读取整个文件、执行 grep 搜索或进行字符串替换等粗糙的文件级操作，Serena 能够实现精确的符号级操作，显著提升效率和代码质量。

1、核心奇迹：从“文本理解”到“符号理解”的降维打击

普通AI工具看待代码就像我们看一篇文章，只能进行文字匹配。而Serena的核心在于利用了 语言服务器协议（LSP）——这正是 VS Code、IntelliJ 等现代IDE能够智能跳转定义、查找引用的底层技术。

• 传统AI（无Serena）： “帮我找到所有调用 process_data 的地方。”
  • AI行为：在项目文件中进行全局文本搜索“process_data”，结果可能包含变量名、注释、字符串，精准度低，且无法区分定义和引用。
• 智能AI（搭载Serena）： “帮我找到所有调用 process_data 的地方。”
  • AI行为：调用Serena的 find_referencing_symbols 工具。Serena通过LSP向语言服务器查询，毫秒级返回所有精确调用该函数的位置列表，绝无遗漏或误判。

这就好比从使用“Ctrl+F”的原始人，进化成了使用“IDE智能导航”的现代开发者，是真正的降维打击。

2、栩栩如生的能力展示：你的AI能做什么？

搭载Serena后，你的AI助手不再只是一个聊天伙伴，而是能直接在你的项目里“干活”的全能代理。

1. 🧭 IDE级智能导航

   • 场景： 接手一个庞大的开源项目，想理清一个核心函数的来龙去脉。
   • AI指令： “分析 src/core/engine.py 中 start() 函数的所有引用关系。”
   • Serena赋能： AI会利用Serena的工具，为你生成一张清晰的函数调用关系图，让你瞬间理解代码执行流程。

2. ✍️ 手术刀式精准编辑

   • 场景： 需要在一个复杂的类中添加一个新方法。
   • AI指令： “在 UserService 类中、get_user 方法之后，插入一个名为 reset_password 的方法。”
   • Serena赋能： AI不是重写整个文件，而是像资深开发者使用IDE一样，在符号级别进行精准插入，代码格式完美，绝不会破坏现有结构。

3. 🚀 全自动开发工作流

   • 场景： “我需要为项目添加用户认证功能，包括登录、注册和密码重置。”
   • Serena赋能： 你可以要求AI制定分步计划，然后它自己会：
     • 分析现有代码结构，找到合适的切入点和需要修改的文件。
     • 编写新的代码文件（如 auth.py）。
     • 在现有代码中插入路由注册、导入语句。
     • 运行测试，检查新功能是否正常，是否破坏了旧功能。
     • 最后，执行 git add 和 git commit 提交更改。
   • 结果： 你提出需求，AI打工。你只需要在关键节点确认，效率提升十倍不止。

3、无缝集成：如何将这股“神力”注入你的工作流？

Serena的另一个强大之处在于其模型无关性和平台无关性，通过 模型上下文协议（MCP） 实现无缝集成。

一句话总结：你几乎可以在任何你喜欢的编程环境中，为你选择的任何AI模型，赋予Serena的超能力。

4、最佳实践与高阶玩法：像王牌指挥官一样调度AI

• 项目记忆： Serena可以为每个项目创建“记忆文件”（如项目架构.md、数据库设计.md）。新对话开始时，AI先读取记忆，瞬间进入上下文，无需重复分析。
• 复杂任务分解：
  • 指令： “我们接下来要重构支付模块。请先制定一个详细计划，并保存为记忆。”
  • 指令： “现在执行第一步：分析现有支付流程的依赖关系。”
  • 指令： “每完成一个步骤，请运行相关测试，确保无误。”
• 安全网：
  • 指令： “在开始修改前，请先检查git状态。”
  • 指令： “如果修改出错，请使用git恢复文件。”

5、为什么Serena是游戏规则改变者？

Serena主要优点如下

1. 多功能性与平台兼容性：

   • 可与多种 LLMS（如 Claude Code、Codex、ChatGPT 等）集成，并支持多种客户端工具和集成开发环境（如 VSCode、Cursor、IntelliJ 等）。
   • 支持多种编程语言，包括 Python、TypeScript、PHP、Java、C/C++、Rust、Go、Ruby、Perl、Dart、Bash等25种语言，并可通过语言服务器协议（LSP）轻松扩展支持的语言。

2. 高效智能代码操作：

   • 提供工具如 find_symbol、insert_after_symbol 和 replace_symbol_body，实现类似IDE的高级代码导航和编辑功能。
   • 通过符号层级而非逐行的方式理解代码，尤其适用于大的、结构复杂的代码库。

3. 灵活部署与操作模式：

   • 可本地安装、通过 Docker 或 Nix 运行，也可以通过多种方式作为 MCP 服务器使用。支持多种运行模式（例如 Streamable HTTP 模式）。
   • 提供上下文与模式自定义，满足不同集成与工作流需求。

4. 社区驱动与开源：

   • 完全免费，无需订阅或 API 密钥，也没有 API 调用费用。
   • 可扩展性强，支持工具和功能个性化开发，已广泛获得社区贡献支持。

5. 快速上手与使用体验：

   • 提供详细的文档，包括从项目激活、索引到内存保存的完整工作流程。
   • 提供用于管理日志与工具的直观仪表盘，同时支持多用户设计优化。

Serena 致力于提升LLM驱动的代码助手的效率和功能，尤其适合处理复杂项目，但对于小型项目或从头开始的编码任务，效果可能较弱。如果需要更高生产力或扩展 LLM 能力，Serena 是一个理想选择。

另外：

• SuperClaude内置Serena，所以如果你使用SuperClaude话，就不用单独使用Serena了。
• Serena会在项目根目录下创建".serena"目录，还会在“.serena/memories”中创建一些 md 文件来理解项目，并利用它们更高效地处理流程。之后，- Serena 会使用自己的工具，不是读取全部代码，而是只读取必要的代码。Cursor 已经有索引系统了，但 Claude Code 没有，所以使用 Serena 会极大提升你的 Claude Code 效率。

如何助力Coding Agent的Context Engineering？

Claude Code之类的Coding assistant本身已支持本地上下文、代码导航和一些工具调用，但要把“上下文工程”做成体系化、可编排、可复现的工程能力，Serena 通过 MCP 能在四个层面显著放大 coding agent 的效果：上下文选择、上下文结构化、上下文行动化、上下文记忆化。 我看到有人说，serena能帮节省多达约**70%**的token！以我的经验来看，serena确实能节省token。

1、上下文选择：把“找到对的片段”变成确定性流程

• 符号级召回而非文件级粗检：
  • 使用 find_symbol、find_referencing_symbols、get_symbols_overview 等工具，Claude 可精确定位函数/类/接口及其引用闭包，避免把整文件塞进上下文。
• 语义回退机制：
  • 当 LSP 无法提供直接关系（如跨语言调用、反射/动态注册），Serena 的语义记忆层可按 embedding 相似度补齐候选上下文。
• Token 经济性：
  • 仅把“目标符号 + 最小依赖闭包 + 相关调用点”注入 Claude 的提示，而不是整文件/整模块，降低噪声和成本。

2、上下文结构化：将“无序片段”变成“可推理的图谱”

• 统一上下文打包协议：
  • MCP 层将检索结果以结构化单元返回（symbol kind、location、signature、docstring、incoming/outgoing edges），而不是原始文本拼接。
• 关系显式化：
  • 在提示中用关系清单组织上下文，如“此函数被 X 调用，调用了 Y/Z，约束条件为 A/B”，让 Claude 的链式推理路径更短、更稳。
• 设计意图与决策历史并列呈现：
  • 通过内存系统，将该符号的历史 PR 讨论、设计文档摘要、约束警示一并纳入上下文，使 Claude 避免“与历史决策冲突”的建议。

3、上下文行动化：让“看懂上下文”直接变成“可执行编辑”

• 可编排的符号级编辑原语：
  • insert_after_symbol、insert_before_symbol、replace_symbol_body 等，让 Claude 在拿到上下文后能生成 WorkspaceEdit 级别的“行动计划”，避免脆弱的字符串替换。
• 影响面预估与验证回路：
  • 先用 find_referencing_symbols 列出受影响点，Claude 生成变更计划；应用后再二次扫描验证是否有漏改，形成“闭环上下文工程”。
• 多步工作流封装：
  • MCP 工具可被 Claude 作为子步骤调用：检索→计划→编辑→编译/测试触发→回溯修正，保证长链条任务的稳定性和可复用性。

4、上下文记忆化：把一次性的上下文变成团队的“持久知识”

• 项目级 memory：
  • 将“为何这样改”的 rationale、踩坑记录、边界条件作为条目写回记忆层，后续相似任务自动被召回到 Claude 的上下文里。
• 语义索引联动：
  • 每次成功变更，提炼“模式化策略”（如重命名 API 的标准步骤），下次 Claude 直接复用策略模板，减少推理漂移。
• 客户端无关性：
  • 这些记忆与工具存在 MCP 侧，不绑死在某个 IDE。即使从 Claude Code 切到 Roo Code/CLI/CI Bot，也能复用相同上下文工程资产。

实践落地方案（面向 Claude Code 的最小可行集）

• 提示模版要点
  • 先取符号概览→补齐引用闭包→注入设计意图与历史限制→让 Claude 输出“编辑计划 JSON”（含受影响文件、变更点、验证步骤）→再调用编辑原语。
• 质量控制
  • 变更前后自动生成影响清单 diff，要求 Claude 对每个差异点给出“原因解释与验证断言”，避免“看起来改对了但语义漂移”。
• Token 管控
  • 约定每轮调用的上下文预算：符号文摘 + 必要片段 + 关键引用点的最小片段；对大函数只注入签名与关键片段锚点，全文按需拉取。

快速开始

1. 安装

cursor/copilot

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

{
  "mcpServers": {
    "serena": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/oraios/serena",
        "serena-mcp-server"
      ]
    }
}

Claude Code

1

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

2. Onboarding

首次使用 Serena 时，您需要运行 “Serena Onboarding" 。引导流程是Serena读取并理解项目并为您的编码做准备的过程。引导流程会在serena\memories 文件夹中生成 memories (md files) 。此引导流程会读取许多文件并消耗大量代币，所以请注意不要耗尽代币。要运行引导流程，您需要让您的 Claude Code（或其他工具）在聊天中启动 Serena 引导流程。另外，在我的情况下，部分记忆并不准确，我需要进行修正。

3. Indexing

在初始化过程中还生成了一个缓存文件 .serena\cache\typescript\document_symbols_cache_v23-06-25.pkl 。当我用光标编辑器打开缓存文件时，内容是乱码，但我能看到索引已创建。不过，该索引似乎并未涵盖整个项目。因此，我运行了下面的命令，为整个项目创建了索引。

1

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

使用示例

普通使用技巧

✅ 请激活项目：/Users/user/Desktop/magentic-ui

✅ 分析这个项目的执行流程

✅ 对项目进行深度技术分析

✅ 每次修改后请运行相关测试，确保没有破坏现有功能

✅ 请运行代码质量检查工具，检查有哪些需要改进的地方

✅ 如果为项目增加用户认证功能，需要修改哪些文件

✅ 帮我在这个React项目中添加一个新的组件

✅ 找出所有调用 process_data 函数的地方

✅ 帮我修复这个Python脚本的bug

✅ 重构这段代码使其更清晰

✅ 给我这个项目的整体结构概览

✅ 帮我找到处理用户认证的相关代码

✅ 请分析 src/main.py 文件的主要功能和结构

✅ 我需要在用户类中添加一个密码重置功能，请帮我实现

✅ 登录功能有bug，用户输入错误密码时没有正确的错误提示，请帮我修复

✅ 请帮我重构 utils.py 中的数据处理函数，让它更模块化

✅ 请为这个重构任务创建一个详细的计划，并保存为记忆。

✅ 为新添加的密码重置功能编写单元测试

✅ 请运行项目的测试套件，看看有没有失败的测试

✅ 我想在我的Flask应用中添加一个API端点来获取用户统计信息

✅ 我的应用在处理大文件时会崩溃，请帮我找出原因

✅ 我的数据处理模块变得很复杂，请帮我重构

✅ 显示所有项目记忆

高级使用技巧

工作流管理

1
2
3
4
5
6
7
8

# 开始一个复杂任务时
请为这个重构任务创建一个详细的计划，并保存为记忆

# 任务进行中
请检查一下我们是否还在正确的轨道上

# 准备切换对话时
请创建一个总结，包含当前进度和下一步计划，保存为记忆以便新对话继续

项目记忆管理

1
2
3
4
5
6
7
8

# 查看现有记忆
显示所有项目记忆

# 读取特定记忆
读取关于数据库设计的记忆

# 更新记忆
请更新API设计记忆，包含我们刚讨论的新端点

多步骤任务

我需要实现一个完整的用户管理系统，包括：
1. 用户注册和登录
2. 密码重置功能  
3. 用户资料管理
4. 权限控制
5. 相应的测试

请分步骤帮我实现，每完成一个功能就让我确认后再继续下一个

最佳实践

• 请先分析现有代码，然后制定实现计划，最后再开始编码
• 请先检查git状态，确保没有未提交的更改
• 修改login_user函数，增加密码强度验证，要求至少8位包含数字和字母
• 每次修改后请运行相关测试，确保没有破坏现有功能

1、 环境配置与项目初始化：打好地基

1. 选择正确的集成模式

   • 首选：MCP服务器模式。这是最通用、最强大的方式。将Serena配置为Claude Desktop、Cursor等工具的MCP服务器，让你的AI助手直接调用其工具。
   • 进阶：Agno框架集成。如果你需要高度定制化的AI智能体工作流，或者想结合多个模型（如Claude+Gemini），这是不二之选。

2. 项目预索引：启动即快人一步

   • 在开始处理大型项目前，先在项目根目录执行预索引命令。这能极大加速后续的符号查找操作，避免“首操作卡顿”。
   • 实践命令： uvx --from git+https://github.com/oraios/serena serena project index

3. 配置Git安全网

   • 绝对准则： 永远在干净的Git工作区中开始一个由AI主导的重大修改任务。这意味着没有未提交的更改。
   • Windows用户特别注意： 执行 git config --global core.autocrlf true 以避免因换行符问题导致diff混乱。

2、 工作流与提示工程：像指挥官一样调度AI

1. “规划-执行”两段式工作流 这是最核心、最高效的实践。将复杂任务拆分为两个独立的对话会话，以管理AI的上下文限制。

   • 会话一：规划与探索

     • 目标： 让AI全面理解项目结构，制定详尽的实施方案，并保存为“项目记忆”。
     • 提示词范例：

       “我们计划为这个项目添加一个完整的用户认证系统。请首先执行项目入门分析，深入理解当前的代码结构、路由设计和数据库模型。然后，为我制定一个详细的实现计划，包括需要创建的新文件、需要修改的现有文件、数据库变更脚本、以及测试策略。请将这份最终计划保存为名为‘用户认证系统实现计划’的记忆。”

   • 会话二：执行与验证

     • 目标： 在新的对话中，让AI读取记忆，然后分步执行计划。
     • 提示词范例：

       “请读取‘用户认证系统实现计划’这份记忆。我们现在开始执行第一步：创建用户模型和数据库迁移脚本。请记住，每次修改后，运行相关的单元测试以确保没有破坏现有功能。”

2. 精准利用符号级工具 避免使用模糊的文本描述，直接使用Serena提供的语义工具。

   • 反面教材： “帮我找一下处理用户登录的代码。”
   • 最佳实践： “请使用 find_symbol 工具，搜索项目中所有名为 login 或 authenticate 的函数或方法。”
   • 进阶实践： “找到 UserService 类中 create_user 函数的所有引用，然后在其后插入一段日志记录代码。”

3. 构建自动化验证闭环 让AI的工作包含自我验证，确保代码质量。

   • 提示词模板： “请实现[功能描述]。在实现过程中，请遵循以下步骤：1. 先分析相关代码。2. 实现修改。3. 运行项目的linting工具检查代码风格。4. 运行受影响模块的单元测试。5. 如果测试失败，分析原因并修复。”

3、 高级技巧与项目管理

1. 善用“项目记忆”作为知识库

   • 将项目架构说明、核心设计决策、API文档等通过AI总结后保存为记忆。这些记忆会成为新对话的“入职手册”，极大减少上下文消耗。
   • 指令： “请将本项目的数据流图和技术栈总结一下，并保存为‘项目架构概述’的记忆。”

2. 使用Git Worktree进行并行开发

   • 当需要同时进行多个功能开发或实验时，使用 git worktree 为每个任务创建独立的工作目录。
   • 好处： 每个工作树可以独立激活一个Serena会话，互不干扰。可以共享Serena的缓存索引，避免重复构建。

3. 模式切换应对不同场景

   • 规划模式： 当需要AI进行架构设计或任务分解时，指示它 switch to planning mode。
   • 只读模式： 当你只想让AI分析代码而不做修改时，在项目配置文件（.serena/project.yml）中设置 read_only: true。这是进行代码审查或学习新项目时的安全选择。

4、 安全与风险控制

1. 权限控制

   • 在不可信的项目或环境中，谨慎启用 execute_shell_command 工具。虽然大多数MCP客户端会请求用户确认，但仍需保持警惕。
   • 可以考虑在项目配置中限制可执行的命令列表。

2. 变更审查

   • 黄金法则： 永远不要盲目接受AI提出的所有修改。 Serena赋予AI强大的能力，但也可能犯错误或产生不符合预期的代码。
   • 在AI完成一个任务阶段后，使用 git diff 仔细审查所有变更，理解每一处修改的意图，然后再提交。

5、 故障排除与优化

1. 工具失效时

   • 首先尝试指令：“请重启语言服务器。”
   • 检查Serena的Web仪表板（通常运行在 http://localhost:24282），查看详细的工具调用日志和错误信息。

2. 性能优化

   • 对于特定语言，确保你已安装了对应的高性能语言服务器（如Rust的 rust-analyzer, Go的 gopls），并将其配置在系统PATH中。
   • 如果项目过大，索引仍然缓慢，考虑让AI先专注于某个子模块而非整个项目。

总结：核心心法

将Serena MCP视为一位能力极强但需要清晰指引的初级工程师。你的角色是技术负责人或架构师。最佳实践的核心就是：

• 明确任务（清晰的提示词）
• 提供上下文（项目记忆）
• 制定计划（规划-执行工作流）
• 建立验收标准（自动化测试和代码检查）
• 最终审核（人工代码审查）

遵循这些实践，你将能最大化Serena MCP的潜力，真正实现十倍效率的提升，同时保持对代码库的绝对控制力和高质量标准。

结论

Serena MCP 不仅仅是一个工具，它代表了一种范式转移——AI从被动的“辅助者”变成了主动的、拥有“视觉”和“动手能力”的“合作者”。如果你正在经历AI编程工具在复杂项目前的无力感，那么Serena就是你一直在等待的答案。 Serena 能够减少token使用量、缩短响应时间，还能提升代码质量。使用 Serena 简单又免费，所以为何不试试看呢。

参考

• Serena MCP Server Github
• Serena MCP Server Documentation
• Serena MCP Server Overview in Zread.ai
• 超元域-Serena MCP入门篇