diff --git a/README.md b/README.md index d4fa11ed..2fadd208 100644 --- a/README.md +++ b/README.md @@ -106,7 +106,7 @@ See our [documentation page](https://oraios.github.io/serena/02-usage/025_jetbra Issue this command to see available options: ```bash -uvx --from git+https://github.com/oraios/serena serena start-mcp-server --help +uvx -p 3.13 --from git+https://github.com/oraios/serena serena start-mcp-server --help ``` **Configuring Your Client**. To connect Serena to your preferred MCP client, you typically need to [configure a launch command in your client](https://oraios.github.io/serena/02-usage/030_clients.html). diff --git a/docs/02-usage/020_running.md b/docs/02-usage/020_running.md index 5766a987..4e2ca372 100644 --- a/docs/02-usage/020_running.md +++ b/docs/02-usage/020_running.md @@ -21,7 +21,7 @@ In general, to get help, append `--help` to the command, i.e. `uvx` is part of `uv`. It can be used to run the latest version of Serena directly from the repository, without an explicit local installation. - uvx --from git+https://github.com/oraios/serena serena + uvx -p 3.13 --from git+https://github.com/oraios/serena serena Explore the CLI to see some of the customization options that serena provides (more info on them below). @@ -124,7 +124,7 @@ case, you can simply run the `start-mcp-server` command without any additional o For example, to run the server in stdio mode via `uvx`, you would run: - uvx --from git+https://github.com/oraios/serena serena start-mcp-server + uvx -p 3.13 --from git+https://github.com/oraios/serena serena start-mcp-server See the section ["Configuring Your MCP Client"](030_clients) for specific information on how to configure your MCP client (e.g. Claude Code, Codex, Cursor, etc.) to use such a launch command. @@ -143,7 +143,7 @@ via the `--port` option. For example, to run the Serena MCP server in streamable HTTP mode on port 9121 using uvx, you would run - uvx --from git+https://github.com/oraios/serena serena start-mcp-server --transport streamable-http --port 9121 + uvx -p 3.13 --from git+https://github.com/oraios/serena serena start-mcp-server --transport streamable-http --port 9121 and then configure your client to connect to `http://localhost:9121/mcp`. diff --git a/docs/02-usage/030_clients.md b/docs/02-usage/030_clients.md index 8db7e6e8..e0c13e73 100644 --- a/docs/02-usage/030_clients.md +++ b/docs/02-usage/030_clients.md @@ -79,7 +79,7 @@ Serena is a great way to make Claude Code both cheaper and more powerful! use this command: ```shell -claude mcp add serena -- uvx --from git+https://github.com/oraios/serena serena start-mcp-server --context claude-code --project "$(pwd)" +claude mcp add serena -- uvx -p 3.13 --from git+https://github.com/oraios/serena serena start-mcp-server --context claude-code --project "$(pwd)" ``` Note: @@ -92,7 +92,7 @@ Note: **Global Configuration**. Alternatively, use `--project-from-cwd` for user-level configuration that works across all projects: ```shell -claude mcp add --scope user serena -- uvx --from git+https://github.com/oraios/serena serena start-mcp-server --context=claude-code --project-from-cwd +claude mcp add --scope user serena -- uvx -p 3.13 --from git+https://github.com/oraios/serena serena start-mcp-server --context=claude-code --project-from-cwd ``` Whenever you start Claude Code, Serena will search up from the current directory for `.serena/project.yml` or `.git` markers, @@ -128,6 +128,8 @@ While serena can be directly installed from the GitHub MCP server registry, we r "type": "stdio", "command": "uvx", "args": [ + "-p", + "3.13", "--from", "git+https://github.com/oraios/serena", "serena", @@ -153,25 +155,18 @@ For example, when using `uvx`, add the following section: ```toml [mcp_servers.serena] +startup_timeout_sec = 25 command = "uvx" -args = ["--from", "git+https://github.com/oraios/serena", "serena", "start-mcp-server", "--context", "codex"] +args = ["-p", "3.13", "--from", "git+https://github.com/oraios/serena", "serena", "start-mcp-server", "--project-from-cwd", "--context", "codex"] ``` -After codex has started, you need to activate the project, which you can do by saying: +The larger startup timeout is to permit uvx to download the necessary dependencies. Once downloaded, the startup time is much faster. -> Call serena.activate_project, serena.check_onboarding_performed and serena.initial_instructions - -**If you don't activate the project, you will not be able to use Serena's tools!** - -It is recommend to set this prompt as a [custom prompt](https://developers.openai.com/codex/custom-prompts), so you don't need to type this every time. - -That's it! Have a look at `~/.codex/log/codex-tui.log` to see if any errors occurred. - -Serena's dashboard will run if you have not disabled it in the configuration, but due to Codex's sandboxing, the web browser -may not open automatically. You can open it manually by going to `http://localhost:24282/dashboard/index.html` (or a higher port, if -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. +:::{attention} +Codex currently ignores the [instructions](https://blog.modelcontextprotocol.io/posts/2025-11-03-using-server-instructions/) +property of MCP servers, so it is recommended to prompt the agent to +"read initial instructions for Serena" when starting your session, e.g. by mentioning this in your `AGENT.md`. +::: ## Claude Desktop @@ -189,6 +184,8 @@ Add the `serena` MCP server configuration "serena": { "command": "uvx", "args": [ + "-p", + "3.13", "--from", "git+https://github.com/oraios/serena", "serena", @@ -225,6 +222,8 @@ MCP server configuration: "serena": { "command": "uvx", "args": [ + "-p", + "3.13", "--from", "git+https://github.com/oraios/serena", "serena", @@ -253,6 +252,8 @@ Go to Settings / Tools / AI Assistant / MCP and add a new **local** configuratio "serena": { "command": "uvx", "args": [ + "-p", + "3.13", "--from", "git+https://github.com/oraios/serena", "serena", @@ -279,6 +280,8 @@ Add this configuration: "serena": { "command": "uvx", "args": [ + "-p", + "3.13", "--from", "git+https://github.com/oraios/serena", "serena", diff --git a/docs/02-usage/040_workflow.md b/docs/02-usage/040_workflow.md index f8b3603f..380009c5 100644 --- a/docs/02-usage/040_workflow.md +++ b/docs/02-usage/040_workflow.md @@ -29,7 +29,7 @@ To explicitly create a project, use the following command while in the project d For instance, when using `uvx`, run - uvx --from git+https://github.com/oraios/serena serena project create [options] + uvx -p 3.13 --from git+https://github.com/oraios/serena serena project create [options] * For an empty project, you will need to specify the programming language (e.g., `--language python`). @@ -201,7 +201,7 @@ Depending on the language backend being used, the management of resources for th where `` is your way of running Serena. For example, when using `uvx`, run - uvx --from git+https://github.com/oraios/serena serena start-project-server + uvx -p 3.13 --from git+https://github.com/oraios/serena serena start-project-server ### Multiple Agents Accessing a Single Serena Instance diff --git a/docs/03-special-guides/serena_on_chatgpt.md b/docs/03-special-guides/serena_on_chatgpt.md index ec872696..d5b640ba 100644 --- a/docs/03-special-guides/serena_on_chatgpt.md +++ b/docs/03-special-guides/serena_on_chatgpt.md @@ -17,7 +17,7 @@ Run the following command to launch Serena as http server (assuming port 8000): ```bash uvx mcpo --port 8000 --api-key -- \ - uvx --from git+https://github.com/oraios/serena \ + uvx -p 3.13 --from git+https://github.com/oraios/serena \ serena start-mcp-server --context chatgpt --project $(pwd) ``` @@ -28,7 +28,7 @@ You can also use other options, and you don't have to pass `--project` if you wa or want to activate it later. See ```shell -uvx --from git+https://github.com/oraios/serena serena start-mcp-server --help +uvx -p 3.13 --from git+https://github.com/oraios/serena serena start-mcp-server --help ``` --- diff --git a/src/serena/util/file_system.py b/src/serena/util/file_system.py index 3784a17a..d7d9f956 100644 --- a/src/serena/util/file_system.py +++ b/src/serena/util/file_system.py @@ -165,10 +165,14 @@ class GitignoreParser: def scan(abs_path: str | None) -> Iterator[str]: for entry in os.scandir(abs_path): - if entry.is_dir(follow_symlinks=follow_symlinks): - queue.append(entry.path) - elif entry.is_file(follow_symlinks=follow_symlinks) and entry.name == ".gitignore": - yield entry.path + try: + if entry.is_dir(follow_symlinks=follow_symlinks): + queue.append(entry.path) + elif entry.is_file(follow_symlinks=follow_symlinks) and entry.name == ".gitignore": + yield entry.path + except PermissionError as ex: + log.debug(f"Skipping entry due to permission error: {entry.path}", exc_info=ex) + continue while queue: next_abs_path = queue.pop(0)