Serena：语义检索和编辑代码的免费MCP工具

综合介绍

Serena 是 Oraios AI 团队开发的一款免费开源编程工具，托管在 GitHub 上。它是一个强大的代码助手，可以直接在你的代码库中工作，帮助开发者分析、编辑和执行代码。Serena 通过语言服务器协议（LSP）实现语义分析，能快速理解代码结构。它还能与大型语言模型（LLM）集成，比如 Claude 或其他免费模型，无需额外订阅费用。Serena 的设计初衷是让开发者摆脱昂贵的工具依赖，提供实用、高效的编程支持。它适合个人开发者、小型团队，甚至大型项目使用。

功能列表

• 语义检索：根据代码含义查找符号、引用或定义。
• 代码编辑：支持插入、替换、删除代码块，操作精准。
• 命令执行：在项目中运行测试或脚本，查看结果。
• 项目概览：显示目录结构和文件内容总结。
• 多语言支持：直接支持 Python、Java、TypeScript，间接支持更多语言。
• 记忆存储：保存分析记录，供后续使用。
• LLM 集成：通过 MCP 或 Agno 框架与语言模型配合。
• 开源免费：无需 API 密钥或付费即可使用。

使用帮助

Serena 的安装和使用需要一些步骤，但整体不难。下面详细介绍如何安装、配置，以及操作它的核心功能。

安装流程

1. 检查环境
   Serena 需要 Python 3.11。打开终端，输入：

python --version

如果版本低于 3.11，请前往 Python 官网下载安装。

2. 下载项目
   访问 https://github.com/oraios/serena，点击“Code”，复制 HTTPS 链接。在终端运行：

git clone https://github.com/oraios/serena.git

项目会下载到本地。

3. 安装工具 uv
   Serena 使用 uv 管理依赖。安装 uv 的方法参考：https://docs.astral.sh/uv/getting-started/installation/。比如在 Linux/macOS 上运行：

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

4. 安装依赖
   进入项目目录：

cd serena

安装基本依赖：

uv pip install -e .

如果要用 Agno 框架，安装全部依赖：

uv pip install --all-extras -e .

5. 配置项目
   复制示例配置文件：

cp myproject.demo.yml myproject.yml

编辑 myproject.yml，设置：

• project_root：你的代码路径，如 /home/user/mycode。
• language：语言类型，如 python。
• ignored_dirs：忽略的文件夹，如 .git。
  保存文件。

启动方式

Serena 支持两种主要使用方式：MCP 服务器和 Agno 框架。

MCP 服务器（配合 Claude Desktop）

1. 安装 Claude Desktop
   下载地址：https://claude.ai/download，支持 Windows 和 macOS。
2. 配置 MCP
   打开 Claude Desktop，进入“File > Settings > Developer > MCP Servers > Edit Config”，编辑 claude_desktop_config.json，添加：

{
"mcpServers": {
"serena": {
"command": "/path/to/uv",
"args": ["run", "--directory", "/path/to/serena", "serena-mcp-server", "/path/to/myproject.yml"]
}
}
}

将 /path/to/uv 和 /path/to/serena 替换为实际路径。Windows 用户注意用双反斜杠（\）。

3. 启动
   保存后重启 Claude Desktop。界面会显示 Serena 工具（带小锤子图标）。

Agno 框架

1. 安装 UI
   下载 Agno UI：

   npx create-agent-ui@latest
   

   或手动克隆：

   git clone https://github.com/agno-agi/agent-ui.git
   cd agent-ui
   pnpm install
   pnpm dev
   

2. 配置环境
   在 Serena 目录下，复制 .env.example 为 .env，填入 API 密钥（若使用付费模型）。
3. 启动 Agno
   在 Serena 目录运行：

   uv run python scripts/agno_agent.py
   

   默认使用 Claude，可在脚本中改用其他模型。

4. 连接 UI
   在浏览器打开 Agno UI（通常是 http://localhost:5173），连接到 Agno 代理。

核心功能操作

语义检索

想找某个函数的引用：

1. 在 Claude 或 Agno 界面输入请求，如“查找 my_function 的引用”。
2. Serena 调用 find_symbol，返回函数定义和引用位置。

代码编辑

插入新代码：

1. 用 read_file 查看文件：

   read_file path/to/file.py
   

2. 用 insert_at_line 插入，比如在第 5 行加代码：

   insert_at_line path/to/file.py 5 'print("Test")'
   

3. 检查文件，确认修改。

运行命令

运行测试：

1. 输入：

   execute_shell_command 'pytest tests/'
   

2. Serena 执行并返回结果。若出错，它会建议修复。

特色功能操作

项目概览

快速了解代码结构：

1. 输入：

   get_dir_overview
   

2. Serena 返回目录中的文件和顶层符号。

自动分析与建议

分析问题：

1. 运行测试后，用 think_about_collected_information：

   think_about_collected_information
   

2. Serena 根据日志或输出提出修复建议。

注意事项

• 路径问题：使用绝对路径，避免相对路径出错。
• 安全性：Agno 模式下，execute_shell_command 不需确认，小心操作。
• 日志：启用日志窗口（在 myproject.yml 中加 show_logs: true），方便调试。
• 版本控制：建议用 Git 管理代码，防止意外丢失。

通过这些步骤，你可以轻松使用 Serena，提升编程效率。

应用场景

1. 快速修复 Bug
   测试失败时，Serena 运行脚本，分析日志，建议修改代码，适合紧急修复。
2. 学习开源项目
   用 Serena 分析陌生代码库，生成结构概览，快速掌握核心逻辑。
3. 原型开发
   个人开发者用 Serena 插入代码、运行测试，快速验证想法。

QA

1. Serena 完全免费吗？
   是的，它开源且无需订阅。配合免费 LLM（如 Claude 免费版）即可使用。
2. 支持哪些语言？
   直接支持 Python、Java、TypeScript。间接支持 Ruby、Go、C#（需手动配置，未完全测试）。
3. 如何处理大项目？
   Serena 用 LSP 分析代码，效率高。建议配置 ignored_dirs 忽略无关文件夹。