Serena（AI编程MCP工具包） Skill 技能

Serena 简介

Serena 是一款专为 AI 编程 Agent 打造的开源 MCP（Model Context Protocol）工具包，通过语义级别的代码检索、编辑、重构与调试能力，赋予 AI Agent 类似 IDE 的开发体验。与传统的基于行号或正则匹配的编辑方式不同，Serena 基于符号（Symbol）对代码进行结构化理解，能够在大型复杂代码库中准确定位符号引用、实现位置、类型层级等语义信息，大幅提升 AI 编程的精准度与可靠性。Serena 支持 40 余种编程语言，通过语言服务器协议（LSP）或 JetBrains 插件后端提供代码分析能力，支持 Claude Code、Codex、Cursor、VS Code 等所有兼容 MCP 协议的 AI 客户端。截至 2026 年 9 月，GitHub 获星超过 28,000 颗，是当前最受欢迎的 AI 编程增强工具之一。

核心能力

一、符号级代码检索

Serena 提供丰富的代码检索工具，能够在符号级别理解代码结构，包括：查找符号定义位置、查找符号的所有引用、查看符号概览（文件大纲）、查找接口实现、查询项目外部依赖中的符号、以及类型层级分析。这些能力基于语言服务器协议或 JetBrains IDE 的深度代码分析，比传统文本搜索快数倍且结果精准。

二、语义化重构与编辑

Serena 的编辑工具以符号为单位而非文本行，支持安全重命名（跨文件自动更新所有引用）、符号体内替换、在符号前后插入内容、安全删除（检查依赖后再删除）等操作。这些原子化的语义操作让 AI Agent 的代码修改既快又准，避免了传统字符串替换带来的引号错配、行号偏移等问题。

三、跨工具链兼容

Serena 支持两条技术路径：默认的 LSP（语言服务器协议）后端支持 40 余种编程语言，包括 Python、TypeScript、Go、Rust、Java、C++ 等主流语言，以及 Ada、Fortran、Haxe、Lean 4 等小众语言；可选的 JetBrains 插件后端则利用 IntelliJ 系 IDE 的强大分析能力，额外支持符号移动、内联、未使用代码传播删除等高级重构操作，以及基于断点、变量检查和表达式求值的调试工作流。

四、记忆系统

Serena 内置记忆模块，支持在多会话、多用户和多项目之间共享知识。这一功能对于长期运行的 AI Agent 工作流尤为重要——AI 可以将关键决策、用户偏好和项目上下文写入持久化存储，在后续会话中无缝恢复，无需每次从头构建上下文。

五、灵活配置体系

Serena 提供四级配置体系：全局配置、MCP 启动命令级配置、项目级本地覆盖配置、以及动态可组合的配置片段（Modes）。用户可以通过 YAML 文件精确控制哪些工具启用、工具描述如何呈现、以及语言后端的具体参数，实现与不同 AI 客户端和工作流程的深度适配。

六、评估体系

Serena 提供了严谨的第三方评估方法：在 20 余项典型日常开发任务上，对比有/无 Serena 工具的 AI 编程表现。结果显示，加入 Serena 后，Claude Code 中的跨文件重命名操作步骤从 8~12 步压缩为 1 步原子调用；Codex 在 Java 代码库中的符号导航能力显著提升。这些评估在官方文档中有完整记录，用户也可以在自己的项目中复现。

安装配置

一、前置条件

Serena 通过 uv 包管理器安装，因此系统需先安装 uv。uv 官方安装方式：

curl -LsSf https://astral.sh/uv/install.sh | sh

安装完成后，确认 uv 可用：

uv --version

二、安装 Serena

通过 uv 安装最新版本 Serena：

uv tool install -p 3.13 serena-agent

安装成功后，serena 命令将可在 shell 中直接使用。

三、初始化验证

运行初始化命令，验证环境是否正确配置：

serena init

默认使用 LSP 后端初始化；如需使用 JetBrains 后端，加上参数 -b JetBrains。初始化成功后，会看到确认信息，表明 Serena 已就绪。

使用步骤

第一步：配置 MCP 客户端

根据所使用的 AI 客户端，按照官方文档配置启动命令。以 Claude Code 为例，需在 MCP 配置文件中添加 Serena 的启动命令（uv run serena start-mcp-server），指定传输协议（默认 stdio，也可选 Streamable HTTP）和端口号。详细配置步骤见官方文档。

第二步：验证工具注册

配置完成后，让 AI 客户端列举可用工具，确认 Serena 的语义检索与编辑工具已正确注册。常见工具包括 find_symbol、find_references、rename、get_type_hierarchy、search_in_dependencies 等。

第三步：在代码库中检索符号

当需要理解陌生代码库时，让 Agent 使用 find_symbol 定位核心类或函数，用 find_references 查看调用方，用 get_type_hierarchy 理解继承关系。AI 无需逐文件阅读，靠符号导航即可掌握代码全貌。

第四步：执行语义化编辑

执行代码修改时，让 Agent 使用 rename 做跨文件重命名（而非全局搜索替换），用 replace_symbol_body 精准修改函数实现，用 safe_delete 移除未使用代码。Serena 会自动处理所有引用更新，避免遗漏。

第五步：使用记忆系统持久化上下文

对于多轮任务或项目特有的约定、偏好，在需要时调用记忆 API（memory_get/memory_set）读写持久化存储，使后续会话自动继承关键上下文，不必重复说明项目规范。

适用场景

• 大型代码库重构：跨文件符号重命名、模块移动——AI 以前做 10 步，现在做 1 步。
• 多语言 Monorepo 导航：Serena 的 LSP 后端覆盖 40+ 语言，AI 可在混合代码库中精准定位符号。
• AI 编程教学与评估：利用内置评估框架，对比不同 AI 客户端的编程能力。
• 企业级多 Agent 协作：通过共享记忆空间，让多个 AI Agent 在同一项目中继承上下文。
• 精准代码审查：AI Agent 基于语义工具而非文本搜索做审查，误报率大幅降低。

适用人群

• 已在使用 Claude Code、Codex、Cursor 等 AI 编程工具的开发者。
• 需要处理大型、复杂代码库的 AI Agent 工作流。
• 希望 AI 代码修改更精准、避免字符串替换后遗症的工程团队。
• 研究 AI 编程能力边界、需要可靠基准评估工具的 AI 研究者。

工作原理

Serena 的核心设计理念是「将 IDE 的语义能力带给 AI Agent」。

当 AI Agent 通过 MCP 协议连接到 Serena 服务器后，所有代码检索和编辑请求首先经过语义分析层。对于 LSP 后端，Serena 调用对应语言的语言服务器（由社区维护的开源 LSP 实现），获取符号的元信息（定义位置、引用列表、类型信息）。对于 JetBrains 后端，则通过插件调用 IntelliJ 平台的深度代码索引与分析引擎，获取更完整的重构和调试能力。

分析结果通过 MCP 协议返回给 AI 客户端，AI 基于这些语义上下文做出更准确的决策。与传统基于正则和行号的操作相比，Serena 的方案具有以下优势：结果精准（符号级别，而非文本匹配）、副作用少（工具自动处理所有引用更新）、token 效率高（不必读取整个文件）。

官方链接

• GitHub 仓库：https://github.com/oraios/serena
• 官方文档：https://oraios.github.io/serena/
• Discord 社区：https://discord.com/invite/cVUNQmnV4r