/ 目录 / 演练场 / Serena
● 社区 oraios ⚡ 即开即用

Serena

作者 oraios · oraios/serena

Serena将语言服务器支持的语义搜索和符号编辑引入到您的代理中,因此重命名/重构/查找引用实际上可以跨越庞大的代码库。

Serena是您的代理的IDE。“它不是抓取文件和祈祷,而是使用40多种语言的真实LSP后端来回答符号级问题: '这个函数在哪里被调用?' , '类型层次结构是什么?' , '在任何使用它的地方重命名这个符号'。然后,它将提供符号编辑工具,以便代理可以替换函数体、安全地删除符号或相对于AST节点插入代码。 记忆系统在整个会话中保持上下文— Claude从上周中断的地方继续。

为什么要用

核心特性

实时演示

实际使用效果

serena.replay ▶ 就绪
0/0

安装

选择你的客户端

~/Library/Application Support/Claude/claude_desktop_config.json  · Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "serena": {
      "command": "uvx",
      "args": [
        "--from",
        "serena-agent",
        "serena",
        "start-mcp-server",
        "--context=claude-desktop"
      ]
    }
  }
}

打开 Claude Desktop → Settings → Developer → Edit Config。保存后重启应用。

~/.cursor/mcp.json · .cursor/mcp.json
{
  "mcpServers": {
    "serena": {
      "command": "uvx",
      "args": [
        "--from",
        "serena-agent",
        "serena",
        "start-mcp-server",
        "--context=claude-desktop"
      ]
    }
  }
}

Cursor 使用与 Claude Desktop 相同的 mcpServers 格式。项目级配置优先于全局。

VS Code → Cline → MCP Servers → Edit
{
  "mcpServers": {
    "serena": {
      "command": "uvx",
      "args": [
        "--from",
        "serena-agent",
        "serena",
        "start-mcp-server",
        "--context=claude-desktop"
      ]
    }
  }
}

点击 Cline 侧栏中的 MCP Servers 图标,然后选 "Edit Configuration"。

~/.codeium/windsurf/mcp_config.json
{
  "mcpServers": {
    "serena": {
      "command": "uvx",
      "args": [
        "--from",
        "serena-agent",
        "serena",
        "start-mcp-server",
        "--context=claude-desktop"
      ]
    }
  }
}

格式与 Claude Desktop 相同。重启 Windsurf 生效。

~/.continue/config.json
{
  "mcpServers": [
    {
      "name": "serena",
      "command": "uvx",
      "args": [
        "--from",
        "serena-agent",
        "serena",
        "start-mcp-server",
        "--context=claude-desktop"
      ]
    }
  ]
}

Continue 使用服务器对象数组,而非映射。

~/.config/zed/settings.json
{
  "context_servers": {
    "serena": {
      "command": {
        "path": "uvx",
        "args": [
          "--from",
          "serena-agent",
          "serena",
          "start-mcp-server",
          "--context=claude-desktop"
        ]
      }
    }
  }
}

加入 context_servers。Zed 保存后热重载。

claude mcp add serena -- uvx --from serena-agent serena start-mcp-server --context=claude-desktop

一行命令搞定。用 claude mcp list 验证,claude mcp remove 卸载。

使用场景

实战用法: Serena

在 1M 行代码库中查找函数的每个调用者

👤 在成熟的大型仓库中工作的工程师 ⏱ ~10 min intermediate

何时使用: 您需要一个完整、正确的调用者列表 - grep 会给出误报(注释、字符串、其他作用域中类似名称的函数)并错过重载。

前置条件
  • 紫外线安装 — 卷曲-LsSf https://astral.sh/uv/install.sh | 嘘
  • 项目以 Serena 的 LSP 支持的语言打开 — 大多数主流语言都是开箱即用的
步骤
  1. 打开项目
    使用 Serena 打开 /abs/path/to/repo。 确认LSP索引建立。✓ 已复制
    → Serena 报告项目根目录和加载的 LSP
  2. 查找符号参考
    查找“PaymentService.chargeCustomer”的每个调用站点。 包括重载和覆盖,排除测试。✓ 已复制
    → 精确的文件:行列表,注释/字符串没有误报
  3. 总结影响
    按模块对调用站点进行分组。 对于每个组,请告诉我调用者如何处理返回值。✓ 已复制
    → 模块分组的叙述,而不是平面列表

结果: 在你接触变化之前,你就清楚地知道它会影响什么。

注意事项
  • 一些多语言存储库需要多个 LSP — 如果语言不共享服务器,则按子项目启动 Serena
搭配使用: filesystem · github

重命名公共 API 符号而不破坏依赖项

👤 库/框架维护者 ⏱ ~15 min intermediate

何时使用: 您要重命名可能在文件外部使用的函数或类 - 您需要 LSP 精确的重命名,而不是文本替换。

前置条件
  • 清理 git 树 — git status clean 这样你就可以在提交之前查看差异
步骤
  1. 试运行重命名
    在 src/api/users.ts 中将 getUser 重命名为 fetchUserById。 使用 Serena 的符号重命名。 预览差异 - 尚未应用。✓ 已复制
    → 每个受影响文件的差异预览
  2. 审查并申请
    应用重命名。 告诉我 Serena 标记为不明确的任何文件。✓ 已复制
    → 已应用重命名、歧义列表(如果有)
  3. 运行套件
    运行测试并报告失败,重点关注引用旧名称的任何内容。✓ 已复制
    → 测试绿色,或精确的失败列表

结果: 整个存储库的重命名都是干净的,包括公共重新导出、index.ts 桶和过时的 JSDoc 引用。

注意事项
  • LSP 重命名不会捕获动态访问 (obj['getUser']) — 符号重命名后,对旧名称字符串执行一次 grep; Serena 会显示任何无法静态解析的内容
搭配使用: filesystem · git

替换函数体而不影响周围代码

👤 工程师在大文件中进行外科手术编辑 ⏱ ~10 min intermediate

何时使用: 您希望重写“calculatePrice”的实现,但要准确保留其签名和 JSDoc。 整个文件重新生成是错误的工具。

步骤
  1. 瞄准符号
    在 src/billing/pricing.ts 中,找到“calculatePrice”。 仅显示当前正文(不显示签名或文档)。✓ 已复制
    → 仅正文片段
  2. 更换本体
    仅将主体替换为处理免税情况的版本。 保持签名和 JSDoc 完整。✓ 已复制
    → 使用瑟琳娜的替换身体工具; diff 中的签名未更改

结果: 最小的、可审查的差异——没有偶然的空格/格式变化。

注意事项
  • 代理回退到全文件写入 — 明确指示“使用 Serena 的符号替换,而不是 write_file”
搭配使用: filesystem

一小时内进入不熟悉的代码库

👤 新员工、承包商或 OSS 贡献者 ⏱ ~60 min beginner

何时使用: 您刚刚克隆了一个包含 500 个文件的存储库,并且需要一张思维导图才能做出贡献。

步骤
  1. 获取架构
    使用 Serena 打开此存储库。 构建地图:顶级模块、它们的公共导出和主要入口点。 以“arch_overview”的形式保存到 Serena 内存中。✓ 已复制
    → 结构化概览; 创建记忆笔记
  2. 遵循用户请求
    跟踪用户点击 POST /orders 时发生的情况。 让我按顺序浏览每个文件。✓ 已复制
    → 请求 → 处理程序 → 服务 → 存储库跟踪,以及 Serena 的参考查找
  3. 注意陷阱
    将任何看起来不寻常的模式(自定义装饰器、魔术常量)作为“陷阱”保存到内存中。✓ 已复制
    → 为下一次会话保存记忆笔记

结果: 下一次课程中,克劳德已经熟悉了地图——无需重新加入成本。

搭配使用: filesystem · github

组合

与其他 MCP 搭配,撬动十倍杠杆

serena + filesystem

Serena 用于符号感知导航 + 用于任意 I/O 的文件系统

使用 Serena 查找身份验证模块,然后使用文件系统为该文件夹编写新的自述文件。✓ 已复制
serena + github

使用 Serena 进行本地重构; 通过 GitHub MCP 推送分支并打开 PR

使用 Serena 重命名 ApiClient → HttpClient,然后打开一个标题为“refactor(api): rename ApiClient”的 PR。✓ 已复制
serena + git

在提交之前查看 Serena 生成的 diff

显示 Serena 重命名后的 git diff。 如有任何可疑之处,请在我们提交之前标记出来。✓ 已复制
serena + context7

库感知重构 - Serena 用于本地移动,Context7 用于匹配 v-next API

将此文件迁移到 Next.js 15 模式。 使用新 API 的 Context7 和 Serena 以符号方式应用更改。✓ 已复制

工具

此 MCP 暴露的能力

工具输入参数何时调用成本
find_symbol name: str, scope?: str 通过名称以 LSP 精度定位类/函数/var free (local)
find_references symbol: ref 符号的所有调用者/用法; 比 grep 好得多 free
get_symbols_overview path: str 在决定阅读内容之前文件/模块大纲 free
rename_symbol symbol: ref, new_name: str, dryRun?: bool 整个项目的安全重命名 free
replace_symbol_body symbol: ref, new_body: str 在不触及签名的情况下交换函数/方法体 free
insert_before_symbol / insert_after_symbol symbol: ref, code: str 添加锚定到 AST 节点的装饰器、导入或同级声明 free
move_file / move_dir src: str, dst: str 重新定位代码并让 LSP 修复每个导入器 free
write_memory / read_memory key: str, value?: str 跨会话保留项目上下文(架构图、陷阱) free
search_pattern regex: str, path: str 当目标不是命名符号(字符串文字、模式)时的回退 free

成本与限制

运行它的成本

API 配额
无 — 本地 LSP
每次调用 Token 数
小 - Serena 返回符号范围的片段,而不是整个文件
费用
自由的
提示
在大文件上,优先使用 get_symbols_overview + find_symbol 而不是 read_text_file — 您花费的令牌数量减少了 10 倍,并且获得了更好的信号

安全

权限、密钥、影响范围

凭据存储: 无 — 一切都在本地运行
数据出站: 默认情况下无。 Serena 可以运行 shell 命令(禁用); 在授予 Claude 写入权限之前,请查看工具列表。
切勿授予: Access to directories outside your project

故障排查

常见错误与修复

LSP 启动失败/未找到符号

检查项目语言的语言服务器是否已安装(例如,Python 的 Pyright,TS 的 TypeScript-Language-Server)。 Serena 日志列出了它正在使用的 LSP。

验证: Run Serena in verbose mode; confirm LSP handshake succeeded
重命名跳过了一些文件

通常意味着文件不在 LSP 的工作区中。 确认项目根目录是 monorepo 根目录,而不是子包。

验证: Ask Serena to list its workspace roots
代理退回到原始文件写入而不是 Serena 工具

在 CLAUDE.md 中明确规定:“对于符号操作,始终使用 Serena 的工具; 切勿在现有 .py/.ts 文件上 write_file'

验证: Re-run the task; inspect tool_use calls in the trace
uvx:未找到命令

首先安装uv:curl -LsSf https://astral.sh/uv/install.sh | 嘘; 然后重新打开你的终端

验证: uvx --version

替代方案

Serena 对比其他方案

替代方案何时用它替代权衡
JetBrains MCP您已经使用 JetBrains IDE 并希望代理驱动其重构工具需要开放的IDE进程; 较重
filesystem您不需要符号意识 - 只需读/写文件没有语义搜索或安全重命名
mcp-language-server您想要一个更小的仅 LSP 包装器,而不是 Serena 的内存 + 外壳层高级工具较少; 您自己编写工作流程

更多

资源

📖 阅读 GitHub 上的官方 README

🐙 查看未解决的 issue

🔍 浏览全部 400+ MCP 服务器和 Skills