Serena MCP Server: Рэдагаванне коду з урахоўваннем сімвалаў для дапаможнікаў AI

Serena — гэта сервер MCP з адзвярнутым кодам, які дае асістэнтам для програмавання на AI можлівасць розумець базу коду у стылі 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

Эта кампанія встановляе serena CLI на всі сістэмы і запускае мастэр налаштавання. Далей налаштовваюцца кліенты.

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 прыводзяць працэўны працэс да прыzwычкі:

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 кожнаму кліенту ў командзе.