From 4b430cbc4d9396e9c18eb1bd87abb1a6665ce6ad Mon Sep 17 00:00:00 2001 From: Dominik Jain Date: Wed, 17 Dec 2025 16:45:06 +0100 Subject: [PATCH 1/4] Return to flat structure to improve usability (TOC display in jupyterbook) --- docs/02-usage/030_clients.md | 40 ++++++++++++++++++------------------ 1 file changed, 20 insertions(+), 20 deletions(-) diff --git a/docs/02-usage/030_clients.md b/docs/02-usage/030_clients.md index b474100a..b757934b 100644 --- a/docs/02-usage/030_clients.md +++ b/docs/02-usage/030_clients.md @@ -3,6 +3,13 @@ In the following, we provide general instructions on how to connect Serena to your MCP-enabled client, as well as specific instructions for popular clients. +:::{note} +The configurations we provide for particular clients below will run the latest version of Serena +using the `stdio` protocol with `uvx`. +Adapt the commands to your preferred way of [running Serena](020_running), adding any additional +command-line arguments as needed. +::: + (clients-general-instructions)= ## General Instructions @@ -14,6 +21,8 @@ To connect Serena to your favourite client, simply * a [run command](start-mcp-server) that allows the client to start the MCP server in stdio mode as a subprocess, or * the URL of the HTTP/SSE endpoint, having started the [Serena MCP server in HTTP/SSE mode](streamable-http) beforehand. +Find concrete examples for popular clients below. + Depending on your needs, you might want to further customize Serena's behaviour by * [adding command-line arguments](mcp-args) * [adjusting configuration](050_configuration). @@ -62,16 +71,7 @@ object, e.g. } ``` -## Specific Clients - -:::{note} -In this section, we present example configurations that run the latest version of Serena -using the `stdio` protocol with `uvx`. -Adapt the commands to your preferred way of [running Serena](020_running), adding any additional -command-line arguments as needed. -::: - -### Claude Code +## Claude Code Serena is a great way to make Claude Code both cheaper and more powerful! @@ -101,7 +101,7 @@ single global MCP configuration. The `--project-from-cwd` option is intended for Be sure to use at least `v1.0.52` of Claude Code (as earlier versions do not read MCP server system prompts upon startup). -### VSCode +## VSCode While serena can be directly installed from the GitHub MCP server registry, we recommend to set it up manually (at least for now, until the configuration there has been improved). Just paste the following into @@ -129,7 +129,7 @@ While serena can be directly installed from the GitHub MCP server registry, we r } ``` -### Codex +## Codex Serena works with OpenAI's Codex CLI out of the box, but you have to use the `codex` context for it to work properly. (The technical reason is that Codex doesn't fully support the MCP specifications, so some massaging of tools is required.). @@ -157,7 +157,7 @@ that was already taken). > Codex will often show the tools as `failed` even though they are successfully executed. This is not a problem, seems to be a bug in Codex. Despite the error message, everything works as expected. -### Claude Desktop +## Claude Desktop On Windows and macOS, there are official [Claude Desktop applications by Anthropic](https://claude.ai/download); for Linux, there is an [open-source community version](https://github.com/aaddrick/claude-desktop-debian). @@ -198,7 +198,7 @@ After restarting, you should see Serena's tools in your chat interface (notice t For more information on MCP servers with Claude Desktop, see [the official quick start guide](https://modelcontextprotocol.io/quickstart/user). -### JetBrains Junie +## JetBrains Junie Open Junie, go to the three dots in the top right corner, then Settings / MCP Settings and add Serena to Junie's global MCP server configuration: @@ -224,7 +224,7 @@ MCP server configuration: You will have to prompt Junie to "Activate the current project using serena's activation tool" at the start of each session. -### JetBrains AI Assistant +## JetBrains AI Assistant Here you can set up the more convenient per-project MCP server configuration, as the AI assistant supports specifying the launch working directory. @@ -253,7 +253,7 @@ Go to Settings / Tools / AI Assistant / MCP and add a new **local** configuratio Then make sure to configure the working directory to be the project root. -### Antigravity +## Antigravity :::{warning} At the time of writing (12/2025), Antigravity does not seem to work with Serena due to schema validation issues @@ -282,11 +282,11 @@ Add this configuration: } ``` -### Other Clients +## Other Clients For other clients, follow the [general instructions](#clients-general-instructions) above to set up Serena as an MCP server. -#### Terminal-Based Clients +### Terminal-Based Clients There are many terminal-based coding assistants that support MCP servers, such as @@ -302,7 +302,7 @@ by writing your own context, modes or prompts to adjust it to the client's respe In most cases, the `ide` context is likely to be appropriate for such clients, i.e. add the arguments `--context ide` in order to reduce tool duplication. -#### MCP-Enabled IDEs and Coding Clients (Cline, Roo-Code, Cursor, Windsurf, etc.) +### MCP-Enabled IDEs and Coding Clients (Cline, Roo-Code, Cursor, Windsurf, etc.) Most of the popular existing coding assistants (e.g. IDE extensions) and AI-enabled IDEs themselves support connections to MCP Servers. Serena generally boosts performance by providing efficient tools for symbolic operations. @@ -310,7 +310,7 @@ to MCP Servers. Serena generally boosts performance by providing efficient tools We generally recommend to use the `ide` context for these integrations by adding the arguments `--context ide` in order to reduce tool duplication. -#### Local GUIs and Agent Frameworks +### Local GUIs and Agent Frameworks Over the last months, several technologies have emerged that allow you to run a local GUI client and connect it to an MCP server. The respective applications will typically work with Serena out of the box. From 13eacba43248473704c96e47db4b9ea33673ccfe Mon Sep 17 00:00:00 2001 From: Dominik Jain Date: Wed, 17 Dec 2025 17:05:14 +0100 Subject: [PATCH 2/4] Replace 32x32 icon with simple logo icon --- .../resources/dashboard/serena-icon-32.png | Bin 4846 -> 3788 bytes 1 file changed, 0 insertions(+), 0 deletions(-) diff --git a/src/serena/resources/dashboard/serena-icon-32.png b/src/serena/resources/dashboard/serena-icon-32.png index 348a9224e14cd3b89918ad50e2e68ad243a31efe..1596e4703ae44066819cfc24fa12c4cc601ba809 100644 GIT binary patch delta 1121 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 From dd76b0f09dc776f0c8f5935c566fc37fdc225da5 Mon Sep 17 00:00:00 2001 From: Dominik Jain Date: Wed, 17 Dec 2025 17:05:25 +0100 Subject: [PATCH 3/4] Add favicon to docs --- docs/_config.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/_config.yml b/docs/_config.yml index dbea0794..89a0f6c2 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -53,7 +53,7 @@ parse: ####################################################################################### # HTML-specific settings html: - #favicon : # A path to a favicon image + favicon : "../src/serena/resources/dashboard/serena-icon-32.png" use_edit_page_button : false # Whether to add an "edit this page" button to pages. If `true`, repository information in repository: must be filled in use_repository_button : false # Whether to add a link to your repository button use_issues_button : false # Whether to add an "open an issue" button From b8d7e725ec70d52b94e0756320d8f58881f592bb Mon Sep 17 00:00:00 2001 From: Dominik Jain Date: Wed, 17 Dec 2025 17:05:47 +0100 Subject: [PATCH 4/4] Remove obsolete public folder --- public/.gitignore | 0 1 file changed, 0 insertions(+), 0 deletions(-) delete mode 100644 public/.gitignore diff --git a/public/.gitignore b/public/.gitignore deleted file mode 100644 index e69de29b..00000000