Readme: how to use in IDEs/extensions and agent frameworks

README.md

@@ -69,21 +69,25 @@ Coming soon: Kotlin and Dart.
 
 <!-- Created with  markdown-toc -i README.md -->
 <!-- Install it with npm install -g markdown-toc -->
+
 <!-- toc -->
 
 - [Is It Really Free to Use?](#is-it-really-free-to-use)
 - [What Can I Use Serena For?](#what-can-i-use-serena-for)
 - [Quick Start](#quick-start)
   * [MCP Server (Claude Desktop)](#mcp-server-claude-desktop)
-  * [Agno](#agno)
+  * [Other MCP Clients - Cline, Roo-Code, Cursor, Windsurf etc.](#other-mcp-clients---cline-roo-code-cursor-windsurf-etc)
+  * [Agno Agent](#agno-agent)
+  * [Other Agent Frameworks](#other-agent-frameworks)
 - [Serena's Tools and Configuration](#serenas-tools-and-configuration)
 - [Comparison with Other Coding Agents](#comparison-with-other-coding-agents)
   * [Subscription-Based Coding Agents](#subscription-based-coding-agents)
   * [API-Based Coding Agents](#api-based-coding-agents)
   * [Other MCP-Based Coding Agents](#other-mcp-based-coding-agents)
-- [Limitations of MCP Servers](#limitations-of-mcp-servers)
+- [Stability Issues in MCP Client-Server Interactions](#stability-issues-in-mcp-client-server-interactions)
   * [Serena Logging](#serena-logging)
 - [Onboarding and Memories](#onboarding-and-memories)
+- [Combination with Other MCP Servers](#combination-with-other-mcp-servers)
 - [Recommendations on Using Serena](#recommendations-on-using-serena)
   * [Which Model to Choose?](#which-model-to-choose)
   * [Onboarding](#onboarding)
@@ -147,12 +151,22 @@ Serena can read, write and execute code, read logs and the terminal output.
    If you are using paths containing backslashes for paths on Windows 
    (note that you can also just use forward slashes), be sure to escape them correctly (`\\`).
 
-That's it! Save the config and then restart Claude Desktop.  
+That's it! Save the config and then restart Claude Desktop. 
+
+Note: on Windows and MacOS there are official Claude Desktop applications by Anthropic, for Linux there is an [open-source
+community version](https://github.com/aaddrick/claude-desktop-debian).
 
 ⚠️ Be sure to fully quit the Claude Desktop application, as closing Claude will just minimize it to the system tray – at least on Windows.  
 
 After restarting, you should see Serena's tools in your chat interface (notice the small hammer icon).
 
+⚠️ Tool Names: Claude Desktop (and most MCP Clients) don't resolve the name of the server. So you shouldn't
+say something like "use Serena's tools". Instead, you can instruct the LLM to use symbolic tools or to
+use a particular tool by referring to its name. Moreover, if you use multiple MCP Servers, you might get
+**tool name collisions** which lead to undefined behavior. For example, Serena is currently incompatible with the
+[Filesystem MCP Server](https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem) due to tool name
+collisions.
+
 ℹ️ Note that MCP servers which use stdio as a protocol are somewhat unusual as far as client/server architectures go, as the server
 necessarily has to be started by the client in order for communication to take place via the server's standard input/output stream.
 In other words, you do not need to start the server yourself. The client application (e.g. Claude Desktop) takes care of this and 
@@ -163,12 +177,34 @@ write a new configuration file, adjust the configuration to point to it and then
 
 For more information on MCP servers with Claude Desktop, see [the official quick start guide](https://modelcontextprotocol.io/quickstart/user).
 
-### Agno
+### Other MCP Clients - Cline, Roo-Code, Cursor, Windsurf etc.
 
-Agno is a model-agnostic agent framework that allows you to use Serena with a large number of underlying LLMs.
+Being an MCP Server, Serena can be included in any MCP Client. The same config as above,
+maybe with small client-specific modifications should work. Most of the popular
+existing coding assistants (IDE extensions or VSCode-like IDEs) accept connecting
+to MCP Servers. Including Serena generally boosts their performance
+by providing them tools for symbolic operations.
+
+In this case, the billing for the usage continues to be controlled by the client of your choice
+(unlike with the Claude Desktop client). But you may still want to use Serena through such an approach,
+e.g., for one of the following reasons:
+
+1. You are already using a coding assistant (say Cline or Cursor) and just want to make it more powerful.
+2. You are on Linux and don't want to use the [community-created Claude Desktop](https://github.com/aaddrick/claude-desktop-debian)
+3. You want tighter integration of Serena into your IDE and don't mind paying for that
+
+The same considerations as in using Serena for Claude Desktop (in particular, tool name collisions) 
+also apply here.
+
+### Agno Agent
+
+Agno is a model-agnostic agent framework that allows you to turn Serena into an agent 
+(independent of the MCP technology) with a large number of underlying LLMs.
 
 While Agno is not yet entirely stable, we chose it, because it comes with its own open-source UI, 
-making it easy to directly use the agent using a chat interface.  
+making it easy to directly use the agent using a chat interface.  With Agno, Serena is turned into an agent
+(so no longer an MCP Server), so it can be used in programmatic ways (for example for benchmarking or within 
+your application).
 
 Here's how it works (see also [Agno's documentation](https://docs.agno.com/introduction/playground)):
 
@@ -221,6 +257,14 @@ this in our testing with Claude, allowing this may not be entirely safe.
 You may choose to disable certain tools for your setup in your Serena project's
 configuration file (`.yml`).
 
+### Other Agent Frameworks
+
+The Agno agent is particularly nice because of the Agno UI, but it is easy to incorporate Serena into any
+agent framework (like [pydantic-ai](https://ai.pydantic.dev/), [langgraph](https://langchain-ai.github.io/langgraph/tutorials/introduction/) or others).
+
+You just have to write an adapter of Serena's tools to the tools in the framework of your choice, like
+it was done by us for agno in the [SerenaAgnoToolkit](/src/serena/agno.py).
+
 ## Serena's Tools and Configuration
 
 Serena combines tools for semantic code retrieval with editing capabilities and shell execution.
@@ -351,6 +395,14 @@ Every file in the `.serena/memories/` directory is a memory file.
 We found the memories to significantly improve the user experience with Serena.
 By itself, Serena is instructed to create new memories whenever appropriate.
 
+## Combination with Other MCP Servers
+
+When using Serena through an MCP Client, you can use it together with other MCP servers.
+However, beware of tool name collisions! See info on that above.
+
+Currently, there is a collision with the popular Filesystem MCP Server. Since Serena also provides
+filesystem operations, there is likely no need to ever enable these two simultaneously.
+
 ## Recommendations on Using Serena
 
 We will continue to collect best practices as the Serena community grows. Below a