serena-mcp-agent

Serena MCP Agent 集成

Serena 利用语言服务器协议（LSP）进行结构化代码理解，让大模型具备 IDE 级智能，成为功能完备的编码 Agent。

核心价值

能力	优势
语义代码检索	按符号而非文本导航，减少 30 倍以上的 Token 消耗
精准编辑	修改函数体，同时保留代码结构
项目记忆	在 .serena/memories/ 中持久保存知识，供多个会话使用
多客户端支持	Claude Desktop、Claude Code、Codex、ChatGPT、自定义 Agent

项目生命周期

1. 激活

执行任何操作前先激活项目：

"Activate the project /path/to/my_project"

首次激活会使用默认设置创建 .serena/project.yml。

2. 引导

首次会话时自动运行。在 .serena/memories/ 中创建记忆：

• tech_stack_and_dependencies.md
• code_style_and_conventions.md
• task_completion_guidelines.md

如果未自动触发：

"Start the Serena onboarding process for this project."

重要： 引导完成后，请开始新的对话（分析过程中会占满上下文）。

3. 索引（大型项目）

预先建立索引，避免工具超时：

serena project index

运行一次即可；使用期间会自动更新。

工具使用策略

优先级顺序（优先使用排名靠前的工具）：

1. 符号工具 - 效率最高，由 LSP 驱动

   • get_symbols_overview → 查看文件结构，无需读取内容
   • find_symbol → 精确定位定义
   • find_referencing_symbols → 修改前进行影响分析
   • replace_symbol_body → 安全重写函数

2. 基于行的工具 - 不适用符号工具时使用

   • replace_lines、insert_at_line、delete_lines

3. 整文件操作 - 最后的选择

   • read_file、create_text_file

参见： references/tools-reference.md，了解完整的工具分类。

记忆管理

在 .serena/memories/ 中持久保存知识：

工具	用途
write_memory	保存契约、架构和进度
read_memory	加载先前会话的上下文
list_memories	查看可用记忆
prepare_for_new_conversation	生成续接摘要
summarize_changes	记录会话中的工作

模式： 结束会话时，依次使用 summarize_changes → write_memory。

思考工具

在复杂操作期间强制进行自我反思：

工具	使用时机
think_about_collected_information	实施前
think_about_task_adherence	长时间操作期间
think_about_whether_you_are_done	声明完成前

客户端配置

Claude Desktop： 编辑 claude_desktop_config.json

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

Claude Code： 在项目目录中：

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

参见： references/client-setup.md，了解 Codex、ChatGPT、Docker 等的配置方法。

上下文和模式

上下文（启动时设置，不可更改）：

• desktop-app - Claude Desktop（完整工具集）
• claude-code - Claude Code（无重复项）
• ide-assistant - IDE 扩展（精简工具集）
• codex - OpenAI Codex
• chatgpt - 通过 MCPO 使用 ChatGPT

模式（可组合、可切换）：

• editing + interactive - 标准开发（默认）
• planning - 实施前进行分析
• one-shot - 单次响应任务
• no-onboarding - 已存在记忆时跳过引导

动态切换：“切换到规划模式”

参见： references/contexts-and-modes.md，了解完整参考。

安全配置

在 .serena/project.yml 中：

read_only: true  # Disable all editing (analysis only)
excluded_tools:
  - execute_shell_command  # Always disable for untrusted contexts

必须遵守：

1. 所有项目都使用版本控制（Git）
2. 除非明确需要，否则禁用 execute_shell_command
3. 对代码审查/分析任务设置 read_only: true
4. 切勿暴露 MCPO API 密钥

调试框架

对于复杂的自动化工作流（n8n、Zapier 等）：

1. 行为契约 - 修改前记录预期行为
2. 修改前快照 - 捕获当前状态
3. 一致性对照表 - 映射契约 → 当前状态 → 所需修复
4. 试运行 - 应用前验证修改
5. 应用 + 验证 - 执行并提供证据
6. 强化记忆 - 保存最终状态

参见： references/debugging-framework.md，其中包含规范提示词和工作流。

会话协议

开始：

1. 验证项目已激活：get_current_config
2. 检查是否已完成引导：check_onboarding_performed
3. 加载相关记忆：list_memories → read_memory
4. 运行构建/类型检查命令（建立基线）

进行中：

• 编辑前先读取文件（避免重复）
• 优先使用符号工具
• 每次修改后运行验证
• 复杂任务使用思考工具

结束：

1. 最终验证（构建/代码检查/测试）
2. summarize_changes → write_memory
3. 如需继续：prepare_for_new_conversation

何时使用 Serena

适用场景：

• 大型/复杂/遗留代码库
• 跨多个文件重构
• 分析依赖关系和架构
• 对令牌敏感的操作

无需使用：

• 新建的空项目（没有内容可供分析）
• 单文件脚本
• 整个上下文都能轻松容纳时

仪表板

在此监控操作：http://localhost:24282/dashboard/index.html

查看：工具调用、日志、配置、活跃语言。