====== Serena ======

//Vytvořeno: **15.8.2026** | Aktualizováno: **~~LASTMOD~~**//

[[https://github.com/oraios/serena|Serena]] je open-source nástroj, který dává coding agentům schopnosti IDE přes Model Context Protocol (MCP). Agent díky němu může v projektu vyhledávat a upravovat funkce, třídy a jejich reference podle významu kódu, ne jen podle textu nebo čísel řádků.

===== K čemu slouží =====

Serena není AI model ani samostatný autonomní agent. Je to vrstva mezi agentem, například OpenCode, Claude Code nebo Codexem, a nástroji pro analýzu zdrojového kódu.

Největší přínos má při práci nad většími nebo neznámými projekty:

  * najde definici funkce, třídy nebo metody a všechna její použití;
  * zobrazí přehled symbolů v souboru, aniž by agent musel načíst celý soubor;
  * přejmenuje symbol napříč projektem přes refaktoring language serveru;
  * nahradí celé tělo konkrétního symbolu nebo vloží obsah před či za něj;
  * vrátí diagnostiku z language serveru;
  * uchovává volitelnou projektovou paměť pro další agentní session.

Příklad: při přejmenování metody ''calculateTotal'' na ''calculateInvoiceTotal'' by agent neměl slepě nahradit řetězec v souborech. Serena může najít symbol a požádat language server o refaktoring, který pracuje s jeho skutečnými referencemi.

Serena nenahrazuje testy, lint, code review ani Git. Sémantické nástroje snižují riziko chybné editace, ale správnost výsledku stále musí ověřit testy a kontrola změn.

===== CLI a MCP server =====

Serena má dvě role.

  * **CLI ''serena''** obsluhuje instalaci, konfiguraci, správu projektu, indexaci a spuštění serveru.
  * **MCP server** je rozhraní, přes které Serenu volá agent. Agent nepoužívá příkazy typu ''serena find-symbol''; po připojení dostane MCP nástroje jako ''find_symbol'' nebo ''rename_symbol''.

Po instalaci přes [[https://docs.astral.sh/uv/getting-started/installation/|uv]] jsou pro člověka užitečné například tyto příkazy:

<code bash>
# Instalace a inicializace s výchozím LSP backendem
uv tool install -p 3.13 serena-agent
serena init

# Vytvoření projektu a předindexace symbolů
serena project create --index

# Dodatečná indexace a kontrola projektu
serena project index
serena project health-check

# Spuštění MCP serveru
serena start-mcp-server
</code>

Podle [[https://oraios.github.io/serena/02-usage/020_running.html|dokumentace spuštění]] se v běžném režimu ''stdio'' server nespouští ručně: MCP klient jej spustí jako vlastní podproces a komunikuje s ním přes standardní vstup a výstup.

==== Provozní režimy ====

**Stdio** je vhodné pro jednoho agenta nad jedním projektem. Každá agentní session spustí vlastní instanci Sereny.

**Streamable HTTP** se hodí, když se k jedné instanci mají připojovat různí klienti nad týmž projektem. Server pak spouští správce prostředí a klienti se připojí na MCP URL. Serena je stavová a v jedné instanci má aktivní právě jeden projekt; nesdílí se proto mezi agenty, kteří pracují nad různými repozitáři.

===== Jak funguje LSP backend =====

[[https://microsoft.github.io/language-server-protocol/|Language Server Protocol (LSP)]] je standardní rozhraní mezi editorem a analyzátorem konkrétního programovacího jazyka. Language server zná syntaxi, importy, typy, definice a reference v projektu.

<code>
Agent → MCP → Serena → LSP language server → analýza projektu
      ←      ←        ←                     ← výsledky
</code>

Serena převede MCP volání na dotazy do vhodného language serveru a odpověď vystaví agentovi ve sjednocené podobě. Nejde o hledání nad embeddingy ani o vektorovou databázi nad zdrojovým kódem. Sémantické porozumění dodává konkrétní language server.

Například [[https://github.com/microsoft/pyright|Pyright]] analyzuje Python, [[https://intelephense.com/|Intelephense]] PHP, [[https://github.com/typescript-language-server/typescript-language-server|TypeScript Language Server]] TypeScript a JavaScript, ''gopls'' Go a ''rust-analyzer'' Rust. [[https://oraios.github.io/serena/01-about/020_programming-languages.html|Serena podporuje]] desítky jazyků; u některých server sama stáhne a u jiných vyžaduje lokální závislost nebo další konfiguraci.

==== Nástroje pro agenta ====

[[https://oraios.github.io/serena/01-about/035_tools.html|Nástroje Sereny]] zahrnují zejména:

  * ''find_symbol'', ''find_declaration'', ''find_implementations'' a ''find_referencing_symbols'' pro navigaci v kódu;
  * ''get_symbols_overview'' pro strukturu souboru;
  * ''get_diagnostics_for_file'' pro chyby a varování;
  * ''rename_symbol'', ''replace_symbol_body'', ''insert_before_symbol'', ''insert_after_symbol'' a ''safe_delete_symbol'' pro symbolické editace;
  * nástroje pro projektovou paměť a onboarding.

Podpora jednotlivých operací závisí na schopnostech language serveru. LSP backend například umí rename symbolů, ale obecný přesun symbolu, souboru nebo adresáře není dostupný pro všechny jazyky.

===== Indexace a projektová paměť =====

Serena rozlišuje analýzu kódu od projektové paměti.

==== Indexace kódu ====

Language server při otevření projektu analyzuje workspace a vytváří si vlastní informace o symbolech a vztazích. Serena může u větších projektů předem načíst symbolická data příkazem ''serena project index''. Tato předindexace zrychlí první dotazy; podle [[https://oraios.github.io/serena/02-usage/040_workflow.html|workflow dokumentace]] se spouští jednou a Serena ji pak průběžně aktualizuje při změnách souborů.

U JetBrains backendu indexaci obstarává IDE, takže samostatná indexace Sereny nedává smysl.

==== Paměť a onboarding ====

Při prvním použití projektu může Serena provést onboarding: projde důležité soubory, build a testovací nastavení a vytvoří lidsky čitelné Markdown poznámky v '' .serena/memories/'' v kořeni projektu. Typicky jde o architekturu, příkazy pro build a testy nebo projektové konvence.

[[https://oraios.github.io/serena/02-usage/045_memories.html|Paměť Sereny]] není RAG ani databáze. Agent nejdříve dostane seznam názvů pamětí a relevantní soubor si přečte cíleně. Paměti lze upravovat ručně, verzovat s projektem a kombinovat s ''AGENTS.md''.

Onboarding může spotřebovat hodně kontextu. Po prvním spuštění je vhodné vytvořené poznámky zkontrolovat a pro další práci začít novou agentní session. Pokud projekt vlastní paměť nepotřebuje, lze ji i onboarding vypnout režimy ''no-memories'' nebo ''no-onboarding''.

===== Alternativní JetBrains backend =====

Vedle výchozího LSP backendu nabízí Serena [[https://oraios.github.io/serena/02-usage/025_jetbrains_plugin.html|placený plugin pro JetBrains IDE]]. MCP server zůstává stejný; plugin je jen alternativní zdroj jazykové inteligence z otevřeného IDE.

JetBrains varianta navíc umí například indexovat externí knihovny, přesouvat symboly, soubory a adresáře, inlinovat symboly, zobrazit type hierarchy a interaktivně debugovat přes breakpointy a REPL. Vyžaduje otevřený stejný projekt v IDE a není nutná, pokud LSP backend poskytuje dostatečnou podporu pro daný jazyk.

===== Doporučené nastavení pro coding agenta =====

Výchozí LSP backend není chybný. Nevhodné však může být výchozí nastavení serveru určené pro klienta, který nemá vlastní nástroje pro soubory a shell. OpenCode už takové nástroje má, proto není dobré vystavit dvě sady podobných nástrojů bez jasného pravidla použití.

Pro terminálového coding agenta je vhodný kontext ''ide'', který je určený pro asistenty s vlastními základními nástroji. Server lze spustit například takto:

<code bash>
serena start-mcp-server \
  --context ide \
  --project-from-cwd \
  --open-web-dashboard false
</code>

  * ''--context ide'' omezuje duplicity se souborovými a shellovými nástroji agenta.
  * ''--project-from-cwd'' vybere projekt podle aktuálního adresáře; Serena hledá nejbližší '' .serena/project.yml'' nebo ''.git''.
  * Dashboard je vhodný při ladění, ale v headless agentním provozu jej není nutné otevírat.

[[https://oraios.github.io/serena/02-usage/030_clients.html|Dokumentace MCP klientů]] upozorňuje, že agenti někdy preferují vlastní ''grep'' a čtení souborů, i když mají Sereně dostupné sémantické nástroje. Pro práci v projektu proto dává smysl mít v ''AGENTS.md'' explicitní pravidlo: pro navigaci v kódu, hledání referencí, rename a změny napříč soubory má agent nejprve použít symbolické nástroje Sereny. Textové vyhledávání zůstává vhodné pro konfigurace, dokumentaci, nezdrojové soubory a případy, kde LSP daný jazyk nebo konstrukci nepokrývá.

===== Bezpečnost a omezení =====

Serena může upravovat soubory a spouštět příkazy. Důvěryhodný MCP klient, důvěryhodný repozitář a důvěryhodná lokální konfigurace jsou součástí jejího bezpečnostního modelu.

  * Udržuj projekt v Gitu a ověřuj ''git diff'', testy a lint.
  * Aktivní nástroje omez na nezbytné minimum.
  * Nedůvěryhodné repozitáře otevírej v sandboxu, například v Dockeru. Označení projektu jako nedůvěryhodného není sandbox a samo o sobě nebrání agentovi měnit soubory nebo spouštět příkazy.
  * HTTP režim ponech na ''localhost'', pokud není k dispozici bezpečná síťová vrstva s autentizací a omezeným přístupem.
  * LSP backend může na vyžádání instalovat language servery. Serena pro řadu z nich používá připnuté verze, kontrolu hashů, omezení zdrojových hostitelů a vlastní instalační adresáře, ale správce stále musí důvěřovat použitým registry a závislostem.

Podrobnosti popisuje [[https://oraios.github.io/serena/02-usage/070_security.html|bezpečnostní dokumentace Sereny]].

===== Kdy ji použít =====

Serena se vyplatí pro rozsáhlejší aplikace, monorepa, refaktoring veřejných API, práci v neznámém kódu a dlouhodobé agentní workflow. Pro malý skript, čistě dokumentační repozitář nebo jednorázovou textovou změnu přinese málo oproti běžnému hledání a editaci souborů.

===== Zdroje =====

  * [[https://github.com/oraios/serena|Serena – repozitář projektu]]
  * [[https://oraios.github.io/serena/01-about/035_tools.html|Serena – přehled MCP nástrojů]]
  * [[https://oraios.github.io/serena/01-about/020_programming-languages.html|Serena – jazyková podpora a LSP]]
  * [[https://oraios.github.io/serena/01-about/025_features.html|Serena – srovnání funkcí LSP a JetBrains backendu]]
  * [[https://oraios.github.io/serena/02-usage/020_running.html|Serena – spuštění serveru]]
  * [[https://oraios.github.io/serena/02-usage/030_clients.html|Serena – připojení MCP klienta]]
  * [[https://oraios.github.io/serena/02-usage/040_workflow.html|Serena – workflow projektu a indexace]]
  * [[https://oraios.github.io/serena/02-usage/045_memories.html|Serena – paměť a onboarding]]
  * [[https://oraios.github.io/serena/02-usage/025_jetbrains_plugin.html|Serena – JetBrains plugin]]
  * [[https://oraios.github.io/serena/02-usage/070_security.html|Serena – bezpečnostní doporučení]]
  * [[https://microsoft.github.io/language-server-protocol/|Language Server Protocol]]