Serena — семантический инструментарий для кодинг-агентов через MCP

С кодинг-агентами есть одна старая проблема: они видят код как текст. Агент ищет нужное место регуляркой, правит строки и надеется, что ничего не сломал. Но у кода есть структура: символы, объявления, ссылки между файлами. И именно этой структурой оперирует любой разработчик в IDE. Serena закрывает этот пробел: это открытый инструментарий, который даёт агенту возможности уровня IDE — семантический поиск, правки и рефакторинг на уровне символов.

Проект подключается к любому LLM-клиенту по протоколу MCP (Model Context Protocol). По сути это MCP-сервер с набором инструментов: сам LLM решает, когда их вызывать, а Serena выполняет работу. Авторы называют такой подход «agent-first»: инструменты работают с высокоуровневыми абстракциями, а не с номерами строк и не с примитивным поиском по тексту. На практике это значит, что агент работает быстрее и надёжнее, особенно в больших и сложных кодовых базах.

Зачем агенту семантика

Без семантических инструментов агент вынужден делать «хирургию текста». Переименовать метод, который используется в десяти файлах? Это 8–12 осторожных шагов поиска и замены, и в каждом шаге можно ошибиться. Найти все места, где вызывается функция? Очередная регулярка, которая то ловит лишнее, то пропускает нужное.

Serena решает эти задачи атомарными вызовами: один запрос находит символ, другой переименовывает его во всём проекте. Авторы проекта провели любопытную оценку: они попросили разных агентов (Claude Code, Codex CLI, Copilot CLI) выполнить около 20 рутинных задач и высказаться о пользе инструментов Serena. Все агенты независимо пришли к одному выводу: семантические инструменты — самое ценное дополнение к их стандартному набору. Кросс-файловые переименования, поиск ссылок и переходы по зависимостям монорепозитория они назвали главными выигрышами. Полную методику и результаты можно посмотреть в документации проекта.

Как это работает

Serena — не самостоятельный агент. Инструменты предоставляет Serena, а «мозгом» остаётся ваш LLM-клиент: он оркестрирует вызовы инструментов в ходе работы. Современные клиенты почти все поддерживают MCP:

• терминальные: Claude Code, Codex, OpenCode, Gemini-CLI;
• IDE и плагины: VSCode, Cursor, JetBrains IDE (Copilot, Junie, JetBrains AI Assistant);
• десктопные и веб-клиенты: Claude Desktop, Codex App, OpenWebUI.

Подключение стандартное для MCP: либо вы даёте клиенту команду запуска сервера, либо запускаете Serena в HTTP-режиме и передаёте клиенту URL. Подробные инструкции для каждого клиента есть в документации.

Важное предупреждение от авторов: не ставьте Serena через маркетплейсы MCP или плагинов. Там гуляют устаревшие и неоптимальные команды установки — пользуйтесь инструкциями из README.

Два бэкенда: language servers и JetBrains

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

Language servers — вариант по умолчанию, бесплатный и открытый. Serena включает слой абстракции над серверами, которые реализуют протокол LSP (Language Server Protocol). Это тот же протокол, на котором работают VSCode и другие редакторы. Через него Serena поддерживает более 40 языков программирования: Python, TypeScript, JavaScript, Go, Rust, Java, Kotlin, C/C++, C#, PHP, Ruby, Swift, Dart, Elixir, Haskell, Scala, Lua и многие другие — вплоть до Fortran, Solidity и Terraform. Полный список — на странице Language Support.

Serena JetBrains Plugin — платный плагин (есть бесплатный пробный период), который использует движок анализа кода вашей JetBrains IDE. Он покрывает все языки и фреймворки, которые поддерживают IntelliJ IDEA, PyCharm, WebStorm, PhpStorm, GoLand и другие IDE (кроме Rider и CLion). Плагин доступен в JetBrains Marketplace, детали настройки — в документации.

Возможности

Набор инструментов Serena делится на несколько групп. Полное описание каждого инструмента — в документации.

Семантический поиск

Агент исследует кодовую базу на уровне символов и не читает файлы целиком. Доступны: поиск символа по имени, структура файла (outline), поиск всех ссылок на символ, поиск объявлений и реализаций, диагностика. У этого набора есть особенность: агент получает точные координаты символа, а не «примерно 150-ю строку».

Рефакторинг

Здесь заметна разница между бэкендами. Через language servers доступно переименование символов. JetBrains-плагин умеет больше: переименование файлов и директорий, перемещение символов и файлов, inline-рефакторинг, распространение удалений (когда убираете неиспользуемый код, плагин подчищает ссылки на него).

Символьное редактирование

Вместо замены текста по регулярке агент правит код по смыслу: заменить тело метода, вставить новый метод до или после существующего, безопасно удалить символ. Такие правки точнее и экономнее по токенам, чем типичные альтернативы.

Отладка

Эксклюзив JetBrains-плагина: общий инструмент отладки, через который агент ставит точки останова, смотрит значения переменных, вычисляет выражения и управляет потоком выполнения через постоянный REPL-подобный интерфейс.

Базовые утилиты

Помимо семантики, Serena даёт набор простых инструментов: поиск по регулярке, замену текста, листинг директорий, чтение файлов и запуск команд в shell. Когда Serena работает внутри готового агента вроде Claude Code, эти инструменты по умолчанию отключены — у агента есть свои.

Память

В Serena встроена система памяти: агент может сохранять знания о проекте и читать их в следующих сессиях. Механика простая, но пользователи хорошо её принимают — часто в связке с AGENTS.md или внутренними системами памяти агента. Если память вам не нужна, её можно отключить.

Установка и быстрый старт

Единственная зависимость — менеджер пакетов uv. Установка занимает одну команду:

uv tool install -p 3.13 serena-agent

Дальше инициализация и проверка, что всё работает:

serena init

По умолчанию Serena настроится на language servers. Чтобы работать через JetBrains IDE, добавьте флаг -b JetBrains. Затем подключите сервер к своему клиенту по инструкции из документации.

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

Конфигурация

Serena настраивается через многоуровневую систему YAML. Конфигурация собирается из нескольких слоёв: глобальный конфиг, параметры команды запуска, настройки на проект (с локальными переопределениями) и настройки под конкретный клиент или сценарий работы. Активные инструменты, их описания, промпты и параметры бэкенда меняются парой строк YAML.

Короткое видео хорошо показывает подход в деле:

Introduction to Serena in 5 Minutes (YouTube)

Лицензия

Лицензия двухкомпонентная. Библиотека SolidLSP (слой работы с language servers) распространяется под MIT, остальное приложение — под GPL-3.0-or-later. Совокупная поставка целиком подпадает под GPL. Общий обзор — в файле LICENSE, а вклад в проект требует подписания CLA (подробнее в CONTRIBUTING.md).

Итог

Serena — зрелый и востребованный инструмент: если ваш агент постоянно читает файлы в поисках нужного места и делает хрупкие замены по регуляркам, семантический слой заметно ускорит и удешевит его работу. Один MCP-сервер — и у агента появляются возможности уровня IDE в более чем 40 языках.