Serena MCP Server: редактирование кода с учётом символов для помощников ИИ

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

В то время как обычный ассистент видит файлы, полные текста, Serena подключается к бэкенду Language Server Protocol — движку, обеспечивающему функции «Перейти к определению», «Найти все ссылки» и безопасное переименование элементов в редакторе, — и предоставляет эти возможности в виде инструментов MCP для любого совместимого клиента. Всё работает на локальном компьютере, поддерживается более 30 языков, а среди клиентов — Claude Code, VS Code, Cursor, OpenCode и Claude Desktop.

В чём проблемы при поиске в обычном текстовом формате

Если попросить ассистента найти все функции, отвечающие за аутентификацию, обычная процедура выглядит следующим образом:

1. Выполните поиск текста с помощью grep или ripgrep по слову «authentication».
2. Прочитайте соответствующие файлы, иногда целиком, вводя тысячи строк в контекст.
3. Верните каждую строку, содержащую этот текст, включая комментарии, литералы строк и нерелевантные результаты.

Это подходит для небольшого проекта, но становится неэффективным по мере увеличения объема кодовой базы. Четыре повседневные задачи показывают эту проблему:

+----------------------------+-------------------------------------+--------------------------------------------+
| Task                       | Without Serena                      | With Serena                                |
+============================+=====================================+============================================+
| **Semantic search**        | Text match on "auth" - returns      | Returns `authenticateUser()`,              |
| "find auth functions"      | false positives, misses functions   | `login()`, `verifyCredentials()`           |
|                            | named `verifyCredentials`           | with file locations and line numbers       |
+----------------------------+-------------------------------------+--------------------------------------------+
| **Go to definition**       | Searches files for "User" and       | Jumps directly to the `User`               |
| "show me the User schema"  | "schema" - returns every reference  | class/interface definition with            |
|                            |                                     | full import tree                           |
+----------------------------+-------------------------------------+--------------------------------------------+
| **Find references**        | Text search for "PaymentProcessor"  | Returns all usages with context:           |
| "where is                  | - misses dynamic usages             | imports, instantiations, method calls      |
| PaymentProcessor used?"    |                                     |                                            |
+----------------------------+-------------------------------------+--------------------------------------------+
| **Cross-file refactoring** | Text search and replace - misses    | Semantic rename via LSP - updates          |
| "rename UserService        | string interpolations or aliased    | every reference correctly across           |
| to AccountService"         | imports, breaks things              | the entire codebase                        |
+----------------------------+-------------------------------------+--------------------------------------------+

Стоимость токенов усугубляет проблему. Без семантических инструментов ассистент читает целые файлы, чтобы понять их структуру, а затем использует этот текст в контексте. С Serena один вызов find_symbol("UserService") возвращает именно то, что необходимо.

Работа на уровне символов

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

• find_symbol находит символ по имени и может вернуть его полный текст.
• get_symbols_overview отображает список символов в файле или директории без необходимости чтения исходного кода.
• find_referencing_symbols перечисляет все места вызова и использования данного символа во всём кодовом базисе.

rename_symbol переименовывает элементы через LSP, обновляя каждую ссылку.

replace_symbol_body заменяет содержимое функции или класса, не трогая окружающий код.

insert_before_symbol и insert_after_symbol вставляют код в точно определённое семантическое место.

LLM не редактирует код строчка за строчкой, чтобы не рисковать потерей какой-либо ссылки; вместо этого она передаёт задачу Serena, которая работает с индексированными данными и языковым сервером, поэтому изменения учитывают все ссылки. Символ, используемый в 20 местах, обновляется во всех 20. В документации проекта перечислены все инструменты языкового сервера.

Память и панель управления

Каждый проект также имеет постоянное хранилище памяти. По мере того как ассистент учится правилам, особенностям и архитектурным решениям, он может сохранять их в виде заметок. Эти заметки сохраняются после сброса разговора и доступны в следующей сессии, так что работа не начинается с нуля.

По умолчанию включена веб-панель управления по адресу http://localhost:24282/dashboard/index.html, которая отображает действия Serena:

• Обзор сессий и активных проектов
• Журнал вызовов инструментов с статистикой о том, какие инструменты использовались, как часто и как долго
• Логи сервера в реальном времени
• Редактор настроек, позволяющий изменять параметры без перезагрузки
• Менеджер памяти для просмотра и редактирования накопленных заметок к проектам
• Контрольные элементы сервера

В macOS и Windows также существует нативный интерфейс в системной панели, тогда как в Linux используется только браузер.

Список инструментов определяется контекстами

Заранее определенные контексты контролируют, какие инструменты будут доступны. Это связано с тем, что клиент может уже самостоятельно выполнять некоторые операции, такие как чтение файлов или запуск оболочки, поэтому Serena не дублирует их, сохраняя чистоту списка инструментов.

+---------------------+------------------------------+------------------------------------------------+
| Context             | Designed for                 | What it does                                   |
+=====================+==============================+================================================+
| `desktop-app`       | Claude Desktop, general use  | **Full toolset** - everything Serena offers.   |
|                     |                              | Use this when the client has no built-in       |
|                     |                              | coding capabilities. This is also the right    |
|                     |                              | choice for a shared Docker instance serving    |
|                     |                              | multiple different clients.                    |
+---------------------+------------------------------+------------------------------------------------+
| `claude-code`       | Claude Code                  | Disables tools that overlap with Claude        |
|                     |                              | Code's built-in capabilities (file edits,      |
|                     |                              | shell commands, etc.) to avoid conflicts.      |
|                     |                              | Single-project context.                        |
+---------------------+------------------------------+------------------------------------------------+
| `ide`               | VS Code, Cursor, Cline, Kilo | Generic IDE augmentation - focuses on          |
|                     |                              | semantic tools, assumes the IDE already        |
|                     |                              | handles basic file operations.                 |
|                     |                              | Single-project context.                        |
+---------------------+------------------------------+------------------------------------------------+
| `agent`             | Agno, autonomous agents      | Broader autonomy for agents that drive the     |
|                     |                              | full workflow independently.                   |
+---------------------+------------------------------+------------------------------------------------+
| `codex`             | OpenAI Codex                 | Optimized for Codex's tool calling format.     |
+---------------------+------------------------------+------------------------------------------------+
| NOTE: The `claude-code` and `ide` contexts are **single-project**: when you pass a project          |
| path at startup, those contexts lock down to only the tools relevant to that project and            |
| disable the project-switching tool entirely (since you won't need it).                              |
+---------------------+------------------------------+------------------------------------------------+

Для одного контейнера Docker, обслуживающего одновременно Claude Code, VS Code и OpenCode, используйте desktop-app — его сверхсемейство. Когда Serena запускается локально для каждого клиента, выбирайте контекст, соответствующий этому инструменту.

Установка

Используйте uv. Собственная документация Serena предупреждает о рынках MCP, поскольку они часто поставляют устаревшие команды:

uv tool install -p 3.13 serena-agent@latest --prerelease=allow
serena init

Это устанавливает CLI serena в глобальную среду и запускает мастер настройки. Далее настраиваются клиенты.

Claude Code, глобальный вариант (рекомендуется):

claude mcp add --scope user serena -- serena start-mcp-server \
  --context claude-code --project-from-cwdlaude mcp add serena -- serena start-mcp-server --context claude-code --project "$(pwd)"

Claude Code по проекту:

claude mcp add serena -- serena start-mcp-server --context claude-code --project "$(pwd)"

VS Code, в файле .vscode/mcp.json в корне проекта:

{
  "servers": {
    "serena": {
      "type": "stdio",
      "command": "serena",
      "args": [
        "start-mcp-server",
        "--context", "ide",
        "--project", "${workspaceFolder}"
      ]
    }
  }
}

Claude Desktop — в файле ~/.config/claude_desktop_config.json в Linux или ~/Library/Application Support/Claude/claude_desktop_config.json в macOS:

{
  "mcpServers": {
    "serena": {
      "command": "serena",
      "args": ["start-mcp-server", "--context", "desktop-app"]
    }
  }
}

Запуск в Docker

Docker — это подход, который рекомендуются документация Serena для обеспечения изоляции, особенно когда агенту разрешено вносить изменения. В контейнере он может видеть только те директории, которые подключены к нему. Пример записи в compose.yml:

services:
  serena:
    image: ghcr.io/oraios/serena:latest
    container_name: myproject-serena
    restart: unless-stopped
    environment:
      - SERENA_DOCKER=1
    ports:
      - "10121:9121"   # SSE endpoint
      - "34282:24282"  # Web dashboard
    volumes:
      - .:/workspace/myproject
    command: >
      serena start-mcp-server
        --transport sse
        --port 9121
        --host 0.0.0.0
        --context desktop-app
        --project /workspace/myproject

Примечания к данной конфигурации:

• --transport sse должен быть задан внутри Docker, поскольку stdio может работать только тогда, когда клиент запускает саму Serena в качестве дочернего процесса.
• --context desktop-app предоставляет наибольший набор инструментов и подходит как для Claude Code, так и для расширений VS Code и OpenCode. Более узкие контексты, такие как claude-code, отключают инструменты, необходимые другим клиентам.
• --project /workspace/myproject должен указывать на путь внутри контейнера, куда монтируется код. Избегайте использования --project-from-cwd в этом случае, поскольку рабочая директория контейнера — это место установки Serena, а не проект.
• Нестандартные порты хоста (10121 и 34282) позволяют нескольким проектам запускать свои собственные экземпляры Serena без конфликтов.

При установке SERENA_DOCKER=1 Serena понимает, что находится внутри контейнера. Глобальный файл ~/.serena/serena_config.yml, монтируемый или встроенный в конфигурацию, должен содержать настройки, совместимые с контейнерами:

gui_log_window: false
web_dashboard_listen_address: "0.0.0.0"
web_dashboard_open_on_launch: false

Чтобы подключить конфигурацию хоста, добавьте сопоставление томов ~/.serena:/root/.serena. Запустите сервис:

docker compose up -d serena

Подключение клиентов к контейнеру

Каждый клиент взаимодействует с одним и тем же SSE-конечной точкой, отличается лишь формат конфигурации. Claude Code может зарегистрировать её глобально:

claude mcp add serena --transport sse --url http://localhost:10121/sse

Или проект может содержать файл .mcp.json:

{
  "mcpServers": {
    "serena": {
      "type": "sse",
      "url": "http://localhost:10121/sse"
    }
  }
}

VS Code использует файл .vscode/mcp.json:

{
  "servers": {
    "serena": {
      "type": "sse",
      "url": "http://localhost:10121/sse"
    }
  }
}

OpenCode использует opencode.jsonc:

{
  "mcp": {
    "serena": {
      "type": "remote",
      "url": "http://localhost:10121/sse",
      "enabled": true
    }
  }
}

Codex, Kilo Code и другие клиенты, совместимые с MCP, работают аналогичным образом.

Конфигурация проекта

Serena читает файл .serena/project.yml, расположенный в корне проекта. Практическая настройка TypeScript начинается с указания имени:

project_name: "myproject"

Затем языки и игнорирование правил:

languages:
  - typescript   # uses typescript-language-serverencoding: "utf-8"
ignore_all_files_in_gitignore: trueignored_paths:
  - "node_modules"
  - "dist"
  - "build"
  - "coverage"
  - ".next"
  - "out"
  - ".cache"

Список ignored_paths служит дополнительной мерой безопасности к файлу .gitignore. Папка node_modules сама по себе может содержать более 80 000 файлов, и их индексация существенно замедляет запуск приложения, а также засоряет результаты поиска символов внутренними данными сторонних библиотек.

Что коммитить, а что игнорировать:

.serena/project.yml      ← commit this (shared config)
.serena/memories/        ← commit this (AI-generated project notes, useful for everyone)
.serena/cache/           ← gitignore (rebuilt per machine)
.serena/project.local.yml ← gitignore (per-developer overrides)

Какие изменения на практике

В монорепозитории Deno 2 с TypeScript, включающем фронтенд, API и общие пакеты, выделяются четыре аспекта:

• Решение проблем между пакетами. Поскольку весь монорепозиторий рассматривается как одно рабочее пространство, Serena одним шагом отслеживает тип из папки packages/ до всех мест его использования в папке apps/api/, тогда как раньше ассистент должен был читать файл за файлом и собирать информацию вручную.
• Более безопасные рефакторинги. Задача по переименованию общего интерфейса, затрагивающая около 20 файлов, выполнялась с помощью команды rename_symbol и ничего не упустила. При поиске и замене текста всегда оставалось одно динамическое использование, скрытое внутри строки-шаблона.
• Вопросы на естественном языке. При запросе на объяснение процесса аутентификации возвращаются соответствующие символы вместе с контекстом, вместо того чтобы ассистент перебирал файлы. Ответ поступает быстрее, с большей точностью и при меньшем использовании контекста.
• Экономия токенов. Трудно измерить точно, но это реально. Чтобы найти определение, достаточно вызвать функцию find_symbol и получить содержимое напрямую, причем правки не выходят за рамки контекста, поскольку текст пишет Serena.

Сокращения в Makefile помогают превратить рабочий процесс в привычку:

make serena-up      # Start the Serena container
make serena-stop    # Stop it
make serena-logs    # Tail logs
make serena-index   # Force re-index after big changes
make serena-health  # Health check the workspace

Вердикт

Анализ логики и генерация кода — это сильные стороны инструментов кодирования на основе ИИ. Однако работа с большими кодовыми базами представляет собой слабую сторону таких инструментов. Сервер языка, созданный именно для решения этой задачи, повышает как качество результатов, так и эффективность затрат. Команды, которые тратят много времени на чтение файлов, но при этом выполняют некачественные операции по рефакторингу в крупных репозиториях, поймут, что установка такого решения того стоит. Docker помогает сохранять порядок: Serena работает рядом с остальными компонентами стека, сохраняет свой индекс и предоставляет один конечный пункт SSE каждому клиенту в команде.