MCP 服务器

Serena

一个功能齐全的编码智能体，它使用符号操作（由语言服务器启用），即使在大型代码库中也能很好地工作。本质上是 Cursor、Windsurf Agents、Cline、Roo Code 等的免费替代品。

README

:rocket: Serena 是一个强大的、功能齐全的代码代理，可以直接在你的代码库上工作。
:wrench: Serena 与现有的 LLM 集成，为它们提供必要的语义代码检索和编辑工具！
:free: Serena 免费使用。无需 API 密钥或订阅！

问：我是否可以在不支付（巨额）API 成本或不断购买令牌的情况下拥有最先进的编码代理？答：是的，你可以！通过将 Serena 与你最喜欢的（甚至是免费的）LLM 集成，从而使其能够直接在你的代码库上执行编码任务。

演示

这是一个 Serena 使用 Claude Desktop 为自己实现一个小功能（更好的日志 GUI）的演示。请注意 Serena 的工具如何使 Claude 能够找到和编辑正确的符号。

https://github.com/user-attachments/assets/6eaa9aa1-610d-4723-a2d6-bf1e487ba753

LLM 集成

Serena 提供了编码工作流程所需的工具，但需要 LLM 来完成实际工作，协调工具的使用。

Serena 可以通过以下几种方式与 LLM 集成：

通过使用 模型上下文协议 (MCP)。 Serena 提供了一个 MCP 服务器，该服务器与 Claude 集成（并且很快也将与 ChatGPT 集成）。
通过使用 Agno – 模型无关的代理框架。 Serena 基于 Agno 的代理允许你将几乎任何 LLM 变成编码代理，无论它是由 Google、OpenAI 还是 DeepSeek 提供（使用付费 API 密钥），还是由 Ollama、Together 或 Anyscale 提供的免费模型。
通过将 Serena 的工具集成到你选择的代理框架中。 Serena 的工具实现与框架特定的代码分离，因此可以轻松地适应任何代理框架。

编程语言支持和语义分析

Serena 的语义代码分析能力建立在使用广泛实现的语言服务器之上语言服务器协议 (LSP)。 LSP 提供了一组通用的代码查询和编辑功能，基于对代码的符号理解。凭借这些能力，Serena 发现和编辑代码就像经验丰富的开发人员使用 IDE 的功能一样。即使在非常庞大和复杂的项目中，Serena 也能有效地找到正确的上下文并做正确的事情！因此，它不仅是免费和开源的，而且经常比现有的收费解决方案取得更好的结果。

语言服务器为各种编程语言提供支持。使用 Serena，我们提供

直接的、开箱即用的支持：
- Python
- Java (注意: 启动速度慢，尤其是初始启动)
- TypeScript
间接支持（可能需要一些代码更改/手动安装）：
- Ruby (未经测试)
- Go (未经测试)
- C# (未经测试)
- Rust (未经测试)
这些语言由语言服务器库 multilspy 支持，Serena 在底层使用该库。但我们没有明确测试对这些语言的支持是否真的有效。

原则上，通过为新的语言服务器提供一个浅适配器，可以轻松地支持更多语言实现。

即将推出：Kotlin 和 Dart。

真的可以免费使用吗？
我可以使用 Serena 做什么？
快速入门
Serena 的工具和配置
与其他编码代理的比较
MCP 客户端-服务器交互中的稳定性问题
- Serena 日志记录
入门和记忆
与其他 MCP 服务器的组合
使用 Serena 的建议
致谢
自定义 Serena
完整工具列表

真的可以免费使用吗？

是的！即使是 Anthropic 的 Claude 的免费层也支持 MCP 服务器，因此你可以免费使用 Serena 和 Claude。据推测，一旦添加了对 MCP 服务器的支持，ChatGPT Desktop 很快也可以实现同样的功能。此外，通过 Agno，你可以选择将 Serena 与免费/开放权重的模型一起使用。

Serena 是 Oraios AI 对开发者社区的贡献。我们自己也经常使用它。

我们厌倦了必须支付多个基于 IDE 的订阅（例如 Windsurf 或 Cursor），这迫使我们不断购买令牌，而我们已经承担了聊天订阅费用。像 Claude Code、Cline、Aider 和其他基于 API 的工具所产生的巨额 API 成本同样没有吸引力。因此，我们构建 Serena 的目的是能够取消大多数其他订阅。

我可以使用 Serena 做什么？

你可以使用 Serena 执行任何编码任务——分析、计划、编辑等等。 Serena 可以读取、写入和执行代码，读取日志和终端输出。 “Vibe coding” 是可能的，如果你想几乎感觉“代码不再存在”，你可能会发现 Serena 比 IDE 中的代理更适合 vibing （因为你将拥有一个单独的 GUI，真正让你忘记）。

快速入门

设置和配置

安装 uv（说明此处）
将存储库克隆到 /path/to/serena。
将 serena_config.template.yml 复制到 serena_config.yml 并调整设置。
将 myproject.template.yml 复制到 myproject.yml 并调整特定于你的项目的设置。（为你希望 Serena 处理的每个项目添加一个这样的文件。）
如果你希望 Serena 在项目之间动态切换，请添加所有项目文件的列表在上一步中创建的 projects 列表到 serena_config.yml 中。

完成此初始设置后，请继续执行以下部分之一，具体取决于你如何想要使用 Serena。

MCP 服务器 (Claude Desktop)

为你的项目创建一个配置文件，例如基于 myproject.template.yml 中的模板的 myproject.yml。
在你的客户端中配置 MCP 服务器。对于 Claude Desktop（适用于 Windows 和 macOS），转到文件 / 设置 / 开发者 / MCP 服务器 / 编辑配置，这将允许你打开 JSON 文件 claude_desktop_config.json。添加以下内容（使用调整后的路径）以启用 Serena：
```
{
    "mcpServers": {
        "serena": {
            "command": "/abs/path/to/uv",
            "args": ["run", "--directory", "/abs/path/to/serena", "serena-mcp-server", "/abs/path/to/myproject.yml"]
        }
    }
}
```
:info: 如果你在配置中设置了 enable_project_activation，则项目文件的路径是可选的，因为此设置将允许你简单地指示 Claude 激活你想要处理的项目。

如果你正在使用包含反斜杠的路径作为 Windows 上的路径（请注意，你也可以只使用正斜杠），请确保正确转义它们 (\\)。

就这样！保存配置，然后重新启动 Claude Desktop。

注意：在 Windows 和 macOS 上，Anthropic 提供了官方的 Claude Desktop 应用程序，对于 Linux，有一个开源社区版本。

⚠️ 请务必完全退出 Claude Desktop 应用程序，因为关闭 Claude 只会将其最小化到系统托盘——至少在 Windows 上是这样。

重新启动后，你应该在你的聊天界面中看到 Serena 的工具（注意小锤子图标）。

⚠️ 工具名称：Claude Desktop（以及大多数 MCP 客户端）不解析服务器的名称。因此，你不应该说“使用 Serena 的工具”之类的话。相反，你可以指示 LLM 使用符号工具或通过引用其名称来使用特定工具。此外，如果你使用多个 MCP 服务器，你可能会遇到 工具名称冲突，这会导致未定义的行为。例如，Serena 目前与文件系统 MCP 服务器不兼容，因为工具名称冲突。

ℹ️ 请注意，使用 stdio 作为协议的 MCP 服务器在客户端/服务器架构方面有些不寻常，因为服务器必须由客户端启动，才能通过服务器的标准输入/输出流进行通信。换句话说，你不需要自己启动服务器。客户端应用程序（例如 Claude Desktop）会处理此问题，因此需要使用启动命令进行配置。

ℹ️ 此外请注意，Serena 始终配置用于单个项目。要将其用于另一个项目，你必须编写一个新的配置文件，调整配置以指向它，然后重新启动客户端。

有关 Claude Desktop 的 MCP 服务器的更多信息，请参阅官方快速入门指南。

其他 MCP 客户端 - Cline, Roo-Code, Cursor, Windsurf 等

作为 MCP 服务器，Serena 可以包含在任何 MCP 客户端中。与上述相同的配置，可能需要进行小的客户端特定修改才能工作。大多数流行的现有编码助手（IDE 扩展或类似 VSCode 的 IDE）接受连接到 MCP 服务器。包含 Serena 通常会通过为它们提供符号操作工具来提高它们的性能。

在这种情况下，使用量的计费仍然由你选择的客户端控制（与 Claude Desktop 客户端不同）。但你可能仍然希望通过这种方法使用 Serena，例如，出于以下原因之一：

你已经在使用编码助手（例如 Cline 或 Cursor），只是想使其更强大。
你在 Linux 上，并且不想使用社区创建的 Claude Desktop
你希望将 Serena 更紧密地集成到你的 IDE 中，并且不介意为此付费

与在 Claude Desktop 中使用 Serena 相同的注意事项（特别是工具名称冲突）也适用于此处。

Agno 代理

Agno 是一个模型无关的代理框架，允许你将 Serena 变成一个代理（独立于 MCP 技术），具有大量底层 LLM。

虽然 Agno 尚未完全稳定，但我们选择它是因为它带有自己的开源 UI，使其易于使用聊天界面直接使用代理。使用 Agno，Serena 被变成一个代理（因此不再是 MCP 服务器），因此它可以以编程方式使用（例如用于基准测试或在你的应用程序中）。

以下是它的工作原理（另请参阅 Agno 的文档）：

使用 npx 下载 agent-ui 代码

npx create-agent-ui@latest

或者，手动克隆它：

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

使用可选要求安装 serena：

# 你也可以只选择 agno,google 或 agno,anthropic 而不是 all-extras
uv pip install --all-extras -r pyproject.toml -e .

将 .env.example 复制到 .env 并填写你打算使用的提供商的 API 密钥。
使用以下命令启动 agno 代理应用程序：
```
uv run python scripts/agno_agent.py
```
默认情况下，该脚本使用 Claude 作为模型，但你可以选择任何模型 Agno 支持的模型（基本上是任何现有模型）。
在一个新的终端中，使用以下命令启动 agno UI：
```
cd agent-ui 
pnpm dev
```
将 UI 连接到你上面启动的代理并开始聊天。你将拥有与 MCP 服务器版本相同的工具。

这是一个 Serena 使用最新的 Gemini 模型执行小型分析任务的简短演示：

https://github.com/user-attachments/assets/ccfcb968-277d-4ca9-af7f-b84578858c62

⚠️ 重要提示：与 MCP 服务器方法相比，Agno UI 中的工具执行不要求用户许可。shell 工具尤其重要，因为它可能执行任意代码。虽然我们在使用 Claude 进行测试时从未遇到任何问题，但允许这样做可能并不完全安全。你可以在你的 Serena 项目的配置文件 (.yml) 中选择禁用某些工具。

其他代理框架

Agno 代理特别好，因为它具有 Agno UI，但很容易将 Serena 合并到任何代理框架中（例如 pydantic-ai、langgraph 或其他）。

你只需要编写一个 Serena 工具的适配器到你选择的框架中的工具，就像我们为 agno 在 SerenaAgnoToolkit 中所做的那样。

Serena 的工具和配置

Serena 将用于语义代码检索的工具与编辑功能和 shell 执行相结合。在下面找到完整的工具列表。

通常建议使用所有工具，因为这允许 Serena 提供最大的价值：只有通过执行 shell 命令（特别是测试），Serena 才能自主地识别和纠正错误。

但是，应该注意的是，execute_shell_command 工具允许执行任意代码。当将 Serena 用作 MCP 服务器时，客户端通常会在执行工具之前征求用户的许可，因此，只要用户事先检查执行参数，这就不应该是一个问题。但是，如果你有顾虑，你可以选择在你的项目的 .yml 配置文件中禁用某些命令。如果你只想使用 Serena 纯粹地分析代码并提出实现建议而不修改代码库，你可以考虑在配置中禁用编辑工具，即

create_text_file
insert_after_symbol
insert_at_line
insert_before_symbol
replace_symbol_body
delete_lines。

通常，请务必备份你的工作并使用版本控制系统，以避免丢失任何工作。

与其他编码代理的比较

据我们所知，Serena 是第一个功能齐全的编码代理，其中所有功能都可以通过 MCP 服务器获得，因此不需要 API 密钥或订阅。

基于订阅的编码代理

最突出的基于订阅的编码代理是 IDE 的一部分，例如 Windsurf、Cursor 和 VSCode。 Serena 的功能类似于 Cursor 的 Agent、Windsurf 的 Cascade 或 VSCode 的即将推出的代理模式。

Serena 的优势是不需要订阅。一个潜在的缺点是它没有直接集成到 IDE 中，因此对新编写的代码的检查不如无缝。

更多技术差异是：

Serena 不受特定 IDE 的约束。 Serena 的 MCP 服务器可以与任何 MCP 客户端（包括某些 IDE）一起使用，并且基于 Agno 的代理提供了应用其功能的其他方式。
Serena 不受特定的大型语言模型或 API 的约束。
Serena 使用语言服务器导航和编辑代码，因此它具有符号对代码的理解。基于 IDE 的工具通常使用基于 RAG 或纯文本的方法，这种方法通常功能较弱，尤其是在大型代码库中。
Serena 是开源的，并且代码库很小，因此可以轻松地扩展和修改。

基于 API 的编码代理

基于订阅的代理的替代方案是基于 API 的代理，例如 Claude Code、Cline、Aider、Roo Code 等，其中使用成本直接映射到底层 LLM 的 API 成本。它们中的一些（例如 Cline）甚至可以作为扩展包含在 IDE 中。它们通常非常强大，它们的主要缺点是（可能非常高）API 成本。

Serena 本身可以用作基于 API 的代理（请参阅上面关于 Agno 的部分）。我们尚未为 Serena 编写 CLI 工具或专用的 IDE 扩展（并且可能没有必要，因为 Serena 已经可以与支持 MCP 服务器的任何 IDE 一起使用）。如果需要像 Claude Code 这样的 CLI 工具的 Serena，我们将考虑编写一个。

Serena 与其他基于 API 的代理的主要区别在于 Serena 还可以用作 MCP 服务器，因此不需要 API 密钥并绕过 API 成本。这是 Serena 的一个独特功能。

其他基于 MCP 的编码代理

还有其他为编码设计的 MCP 服务器，例如 DesktopCommander 和 codemcp。但是，据我们所知，它们都没有提供语义代码检索和编辑工具；它们纯粹依赖于基于文本的分析。正是语言服务器和 MCP 的集成使 Serena 独一无二并且对于具有挑战性的编码任务非常强大，尤其是在更大的代码库。

MCP 客户端-服务器交互中的稳定性问题

Claude Desktop 和各种 MCP 服务器 SDK 中对 MCP 服务器的支持是相对较新的发展，我们发现它们有些不稳定。有时，Claude Desktop 会在工具执行时崩溃（出现 asyncio 错误或其他类似错误）。一方面，它可以显示没有意义的错误消息，另一方面，它可能无法在事情无法挽回地失败时显示错误消息。但我们预计这些稳定性问题会随着时间的推移而改善。

MCP 服务器的工作配置可能因平台而异平台和客户端之间。我们建议始终使用绝对路径，因为相对路径可能是错误来源。语言服务器在单独的子进程中运行，并使用 asyncio 调用——有时 Claude Desktop 会让它崩溃。如果你启用了 Serena 的日志窗口，并且它消失了，你就会知道发生了什么。

目前，你可能需要多次重新启动 Claude Desktop，可能需要手动清理残留进程，并且你可能会在对话中遇到冻结。在后一种情况下，只需重试即可。如果你遇到无法解决的设置问题，请随时提出问题。

Serena 日志记录

为了帮助进行故障排除，我们编写了一个用于日志记录的小型 GUI 实用程序。我们建议你启用它通过项目配置 (myproject.yml)，如果你遇到问题。对于 Claude Desktop，还有 MCP 日志可以帮助识别问题。

入门和记忆

默认情况下，Serena 将在首次为项目启动时执行入门过程。该过程的目标是让 Serena 熟悉该项目并存储记忆，然后它可以在未来的交互中利用这些记忆。

记忆是存储在项目目录中的 .serena/memories/ 中的文件，代理可以选择读取这些文件。请随意读取和调整它们，你也可以手动添加新的记忆。 .serena/memories/ 目录中的每个文件都是一个记忆文件。

我们发现记忆可以显着改善 Serena 的用户体验。就其本身而言，Serena 被指示在适当的时候创建新的记忆。

与其他 MCP 服务器的组合

通过 MCP 客户端使用 Serena 时，你可以将其与其他 MCP 服务器一起使用。但是，请注意工具名称冲突！请参阅上面有关该主题的信息。

目前，与流行的文件系统 MCP 服务器存在冲突。由于 Serena 还提供文件系统操作，因此可能没有必要同时启用这两个服务器。

使用 Serena 的建议

随着 Serena 社区的壮大，我们将继续收集最佳实践。下面是一个我们在内部使用 Serena 时学到的东西的简短概述。

这些建议中的大多数对于任何编码代理都是正确的，包括所有代理上面提到的。

选择哪个模型？

令我们惊讶的是，Serena 似乎在使用 Claude 3.7 的非思考版本时效果最好，而不是其思考版本（我们尚未与 Gemini 进行广泛的比较）。思考版本花费的时间更长，在使用工具方面有更多困难，并且通常会只是编写代码而不读取足够的上下文。

在我们的初步实验中，Gemini 似乎工作得非常好。不幸的是，Gemini 不支持 MCP（尚未？），因此使用它的唯一方法是通过 API 密钥。从好的方面来说， Gemini 相对便宜，并且可以处理巨大的上下文长度。

入门

在第一次交互中，Serena 被指示执行入门并写入第一个记忆文件。有时（取决于 LLM），文件不会写入磁盘。在这种情况下，只需要求 Serena 写入记忆即可。

在此阶段，Serena 通常会读取和写入大量文本，从而填满上下文。我们建议你在入门完成后切换到另一个对话，以避免耗尽令牌。入门将仅执行一次，除非你明确触发它。

入门完成后，我们建议你快速浏览一下记忆，并且如有必要，编辑它们或添加其他记忆。

编辑代码之前

最好从干净的 git 状态开始代码生成任务。不仅这将使你更容易检查更改，而且模型本身也将有机会通过调用 git diff 来查看它已更改的内容，从而纠正自己或在需要时在后续对话中继续工作。

:warning: 重要提示：由于 Serena 将使用系统原生的行尾符写入文件并且它可能想要查看 git diff，因此重要的是在 Windows 上将 git config core.autocrlf 设置为 true。如果在 Windows 上将 git config core.autocrlf 设置为 false，你最终可能会得到巨大的差异仅由于行尾符。通常，最好在 Windows 上启用此 git 设置：

git config --global core.autocrlf true

代码编辑中的潜在问题

根据我们的经验，LLM 真的不擅长计数，也就是说，它们在在正确的位置插入代码块。大多数编辑操作都可以在符号级别执行，从而克服了这个问题。但是，有时，行级插入很有用。

Serena 被指示仔细检查行号和它将编辑的任何代码块，但如果你遇到问题，你可能会发现明确告诉它如何编辑代码很有用。

上下文耗尽

对于漫长而复杂的任务，或者 Serena 读取了大量内容的任务，你可能会接近上下文令牌的限制。在这种情况下，通常最好在新的对话中继续。Serena 有一个专用工具来创建当前状态的摘要进度和所有相关信息，以便继续进行。你可以请求创建此摘要并将其写入记忆。然后，在新的对话中，你可以只要求 Serena 读取记忆并继续执行任务。根据我们的经验，这效果非常好。从好的方面来说，由于在单个会话中不涉及摘要，因此 Serena 通常不会迷路（不像某些在幕后进行摘要的其他代理），并且它也被指示偶尔检查是否它是否在正确的轨道上。

此外，Serena 被指示节约上下文（例如，不要不必要地读取代码符号的主体），但我们发现 Claude 在节约方面并不总是很好（Gemini 似乎在这方面做得更好）。如果你知道不需要读取主体，你可以明确指示它不要读取主体。

控制工具执行

Claude Desktop 会在执行工具之前询问你。对于大多数工具，你可以安全地单击“允许此聊天”，特别是如果你的所有文件都在版本控制之下。一个例外是 execute_shell_command 工具 - 在那里你可能想要单独检查每个调用。我们建议你查看对该命令的每个调用，并且不要为整个聊天启用它。

构建你的代码库

Serena 使用代码结构来查找、读取和编辑代码。这意味着它将适用于结构良好的代码，但可能无法适用于完全非结构化的代码（例如具有巨大的、非模块化函数的上帝类）。类型注释也有很大帮助。你的代码越好， Serena 的工作效果就越好。因此，我们通常建议你编写结构良好、模块化和类型化的代码 - 它不仅可以帮助你，还可以帮助你的 AI ;)。

日志记录、Linting 和测试

Serena 无法调试（据我们所知，目前没有编码助手可以做到这一点）。这意味着为了提高 代理循环 中的结果，Serena 需要通过执行测试、运行脚本、执行 linting 等来获取信息。通常，包含许多带有明确信息的日志消息并进行有意义的测试非常有帮助。特别是后者通常有助于代理自我纠正。

我们通常建议从所有 linting 检查和测试都通过的状态开始编辑任务。

一般建议

我们发现，在实际实施任务之前，花一些时间概念化和计划任务通常是一个好主意，特别是对于非平凡的任务。这有助于获得更好的结果，并有助于提高控制感和保持循环。你可以在一个会话中制定详细的计划， Serena 可能会读取大量代码以构建上下文，然后在另一个会话中继续实施（可能在创建合适的记忆之后）。

致谢

我们基于多个现有的开源技术构建了 Serena，其中最重要的是：

multilspy。一个围绕遵循 LSP 的语言服务器的精美设计的包装器。它不容易使用符号 Serena 所需的逻辑进行扩展，因此我们没有将其作为依赖项合并，而是复制了源代码并使其适应我们的需求。
Python MCP SDK
Agno 和相关的 agent-ui，我们使用它来允许 Serena 与任何模型一起工作，而不仅仅是支持 MCP 的模型。
我们通过 multilspy 使用的所有语言服务器。

如果没有这些项目，Serena 将不可能实现（或者构建起来会更加困难）。

自定义 Serena

使用你自己的想法扩展 Serena 的 AI 功能非常容易。只需通过从 serena.agent.Tool 继承并实现 apply 方法（不是接口的一部分，请参阅 Tool 中的注释）来实现一个新的工具。默认情况下，SerenaAgent 将立即可以访问它。

添加对新语言的支持也相对简单。我们期待看到社区会提出什么！有关贡献的详细信息，请参阅此处。

完整工具列表

以下是 Serena 工具的完整列表，并附有简短说明（uv run serena-list-tools 的输出）：

activate_project：按名称激活项目。
check_onboarding_performed：检查是否已执行入门。
create_text_file：在项目目录中创建/覆盖文件。
delete_lines：删除文件中的一系列行。
delete_memory：从 Serena 的项目特定记忆存储中删除记忆。
execute_shell_command：执行 shell 命令。
find_referencing_code_snippets：查找给定位置的符号被引用的代码片段。
find_referencing_symbols：查找引用给定位置的符号的符号（可以选择按类型过滤）。
find_symbol：执行对具有/包含给定名称/子字符串的符号的全局（或本地）搜索（可以选择按类型过滤）。
get_active_project：获取当前活动项目的名称（如果有），并列出现有项目
get_dir_overview：获取给定目录中所有文件中定义的顶级符号的概述。
get_document_overview：获取给定文件中定义的顶级符号的概述。
insert_after_symbol：在给定符号的定义结束后插入内容。
insert_at_line：在文件中的给定行插入内容。
insert_before_symbol：在给定符号的定义开始之前插入内容。
list_dir：列出给定目录中的文件和目录（可以选择递归）。
list_memories：列出 Serena 的项目特定记忆存储中的记忆。
onboarding：执行入门（识别项目结构和基本任务，例如用于测试或构建）。
prepare_for_new_conversation：提供准备新对话的说明（以便继续使用必要的上下文）。
read_file：读取项目目录中的文件。
read_memory：从 Serena 的项目特定记忆存储中读取具有给定名称的记忆。
replace_lines：用新内容替换文件中的一系列行。
replace_symbol_body：替换符号的完整定义。
search_in_all_code：在项目中的所有代码文件（并且仅在代码文件中）中搜索模式。
summarize_changes：提供总结对代码库所做更改的说明。
think_about_collected_information：用于思考收集的信息的完整性的思考工具。
think_about_task_adherence：用于确定代理是否仍在当前任务的轨道上的思考工具。
think_about_whether_you_are_done：用于确定任务是否真正完成的思考工具。
write_memory：将命名的记忆（供将来参考）写入 Serena 的项目特定记忆存储。