Serena MCP: символьный поиск и точечные правки в локальном репозитории

Serena MCP — набор инструментов для кодового агента, который находит и правит код по символам: классам, функциям и методам, а текстовый перебор строк остаётся запасным путём. Проект ведёт организация oraios на GitHub, и под капотом у него серверы языков по протоколу LSP, поэтому агент видит определения и ссылки так, как их видит редактор. Выигрыш заметен на больших репозиториях, где чтение файлов целиком забивает контекст модели; на проекте из десятка файлов хватит и обычного поиска.

Зачем символы

Обычный кодовый агент ищет нужное место перебором: открывает файл, читает его целиком, затем следующий. На большом репозитории это съедает контекст модели и время, а пропущенное место вызова остаётся незамеченным. Serena подключается к языковым серверам и отвечает на более точные вопросы: где определена функция, кто её вызывает, что лежит внутри класса. По описанию проекта, поддерживаются десятки языков, а в качестве второго варианта доступен платный плагин для JetBrains.

• Поиск: find_symbol находит определение, find_referencing_symbols показывает места использования.
• Правка: replace_symbol_body, insert_before_symbol, insert_after_symbol, а также rename_symbol и safe_delete_symbol.
• Служебные: search_for_pattern, read_file, list_dir и execute_shell_command.

Здесь описан локальный репозиторий на вашей машине. Работу с задачами, обсуждениями и pull request мы разбирали в статье про MCP GitHub: Serena её заменить нельзя, она дополняет клиента на уровне кода. Названия инструментов взяты из README на момент проверки, перед запуском сверьте их со своей версией.

Пример для понимания: в сервисе из нескольких сотен файлов нужно изменить сигнатуру функции расчёта. Обычный агент читает десятки файлов в поисках вызовов и легко пропускает один. Агент с Serena запрашивает список ссылок на символ, получает точные места и открывает только их. Запрос выдаёт короткий список вместо десятков прочитанных страниц кода. Экономия контекста здесь прямая, а риск пропуска ниже, хотя проверка результата остаётся за человеком и тестами.

Запуск сервера

Установка идёт через менеджер uv, затем инициализация и запуск сервера с контекстом, который соответствует вашему клиенту. Контексты в документации названы по клиентам: claude-code, codex, ide, desktop-app и другие. Контекст меняет набор и описание инструментов, чтобы они повторяли встроенные возможности клиента как можно реже.

1. Установите пакет командой uv tool install -p 3.13 serena-agent и выполните serena init.
2. Для Claude Code документация предлагает добавить сервер командой claude mcp add --scope user serena -- serena start-mcp-server --context claude-code --project-from-cwd.
3. Откройте клиент в каталоге репозитория: параметр --project-from-cwd выберет проект по текущей папке.
4. Дождитесь индексации и просмотрите список инструментов в клиенте, прежде чем ставить задачу.
5. При первом запуске Serena предлагает пройти онбординг и записывает заметки о проекте в папку .serena внутри репозитория.

Папку .serena решите заранее: добавлять её в репозиторий или в исключения Git. Выбор влияет на всю команду: общий каталог видят все, личный остаётся у одного сотрудника, и тогда каждый работает со своей картой проекта. Заметки полезны следующим сессиям, но в них попадает описание архитектуры, которое вы вряд ли захотите публиковать. Для других клиентов в документации есть отдельные команды: для VS Code, Claude Desktop, Copilot CLI и JetBrains. Контекст в них свой, и подставлять чужой вариант вместе с чужим путём нельзя. Смотрите раздел вашего клиента, а установку самого агента для команды разбирает материал про установку и старт Claude Code.

Права по группам

Сервер Serena выполняет то, что разрешили клиент и конфигурация, а границы задаёте вы. Разделите инструменты по цене ошибки и откройте их в таком порядке.

Документация перечисляет режимы planning, editing, interactive, one-shot и другие, а ещё параметр проекта read_only, который помечает проект только для чтения, и список excluded_tools для отключения конкретных инструментов. Первое знакомство с проектом обходится одним read_only: агент объяснит структуру кода и составит план, а ваш репозиторий останется нетронутым. Инструмент запуска команд даёт агенту всё, что доступно вашему пользователю в терминале, поэтому оставляйте его отключённым, пока нет изолированной среды.

Правка и diff

Точечная правка по символу выглядит аккуратно: агент находит функцию, заменяет её тело, правит вызовы. Но аккуратный вид легко принять за правильный результат. Опора проверки — обычный diff Git, рассказ агента о проделанном служит лишь пояснением к нему.

Работайте в отдельной ветке: до начала задачи зафиксируйте чистое состояние, после сеанса откройте diff и просмотрите каждую строку. Затем запустите тесты и линтер проекта. Сверьте также список мест использования: если агент переименовал функцию, find_referencing_symbols до правки и поиск по старому имени после неё должны давать согласованный ответ. Динамические вызовы, строковые ссылки и конфигурационные файлы языковой сервер видит лишь в части случаев, поэтому их проверяет текстовый поиск.

Отдельная ловушка связана с размером изменения. Точечный инструмент может заменить тело функции целиком, и в сжатом виде изменение выглядит маленьким, а по факту переписан большой блок логики. Читайте diff до последней строки и отмечайте, что поменялось по смыслу: условия, порядок операций, обработка пустых значений. Если агент за один сеанс затронул много файлов, разбейте задачу на несколько веток и принимайте их по очереди. Отдельно оцените, чьим кодом занимается агент. По документации Serena, репозиторий приносит с собой конфигурацию (.serena/project.yml), в которой, например, может быть команда для запуска при активации проекта, а доверенные пути перечислены в глобальной настройке trusted_project_path_patterns. Чужой репозиторий сначала прочитайте глазами и откройте в песочнице: список доверенных путей, по словам документации, закрывает лишь самые простые атаки, а настоящую защиту даёт песочница.

Пилот на репозитории

Пилот лучше начинать с задач, у которых есть проверяемый критерий: найти все места вызова устаревшей функции, составить карту модулей, переименовать метод с зелёными тестами. Для каждой задачи фиксируйте число вызовов инструментов, правки после ручной проверки и причину отката, если она была. Пилот ограничьте по времени и числу задач, чтобы итог можно было сравнить с прежней работой без агента. Результаты занесите в короткую таблицу: задача, число вызовов, число правок после ручной проверки, итог. Через несколько задач станет ясно, окупается ли символьная навигация на вашем коде или хватает встроенных средств клиента.

Про лицензию узнайте заранее. По README компонент SolidLSP выпущен под MIT, а само приложение Serena под GPL-3.0-or-later, и для коммерческой разработки юрист команды должен подтвердить, что локальный запуск вас устраивает. Критерий приёмки пилота запишите до первой задачи: например, все тесты зелёные, diff прочитан вторым человеком, число непредусмотренных файлов равно нулю. Права процесса выберите отдельно и заранее: сервер читает и пишет всё, что доступно его пользователю, поэтому для чужих каталогов используйте отдельную учётную запись, как в схеме из статьи про доступ MCP к папкам. Для проектов, где нужен контур с правами и приёмкой, смотрите страницу про внедрение ИИ в команду разработки.

Частые вопросы