docs: update readme (#139)

Author: mathislucka

README.md

@@ -1,8 +1,30 @@
 # MCP Server for the deepset AI platform
 
 The deepset MCP server exposes tools that MCP clients like Claude or Cursor can use to interact with the deepset AI platform.
-Use these tools to develop pipelines, or to get information about components and how they are defined.
 
+Agents can use these tools to:
+
+- develop and iterate on Pipelines or Indexes
+- debug Pipelines and Indexes
+- search the deepset AI platform documentation
+
+## Contents
+
+- [1. Installation](#installation)
+  - [1.1. Claude Desktop](#claude-desktop-app)
+  - [1.2. Other MCP Clients](#other-mcp-clients)
+  - [1.3. Advanced Configuration](#advanced-configuration)
+- [2. Prompts](#prompts)
+- [3. Use Cases](#use-cases)
+  - [3.1. Creating Pipelines](#creating-pipelines)
+  - [3.2. Debugging Pipelines](#debugging-pipelines)
+- [4. CLI](#cli)
+
+
+
+
+
+![GIF showing CLI interaction with the MCP server](assets/deepset-mcp-3.gif)
 
 
 ## Installation
@@ -12,7 +34,7 @@ Use these tools to develop pipelines, or to get information about components and
 **Prerequisites:**
 - [Claude Desktop App](https://claude.ai/download) needs to be installed
 - You need to be on the Claude Pro, Team, Max, or Enterprise plan
-- You need an installation of [Docker](https://docs.docker.com/desktop/) (scroll down to the `uv` section if you want to use `uv` instead of Docker)
+- You need an installation of [Docker](https://docs.docker.com/desktop/) ([Go here](#using-uv-instead-of-docker) if you want to use `uv` instead of Docker)
 - You need an [API key](https://docs.cloud.deepset.ai/docs/generate-api-key) for the deepset platform
 
 **Steps:**
@@ -51,7 +73,7 @@ Use these tools to develop pipelines, or to get information about components and
 
 
 
-**(Optional) Running the server with uv instead of Docker**
+#### Using uv instead of Docker
 
 Running the server with uv gives you faster startup time and consumes slightly less resources on your system.
 
@@ -85,54 +107,147 @@ Running the server with uv gives you faster startup time and consumes slightly l
 
 ### Other MCP Clients
 
-The repo was not tested with other MCP clients but tools like Cursor or the Haystack MCP package should work out of the box.
+`deepset-mcp` can be used with other MCP clients.
+
+Here is where you need to configure `deepset-mcp` for:
+
+- [Cursor](https://docs.cursor.com/context/mcp#using-mcp-json)
+- [Claude Code](https://docs.anthropic.com/en/docs/claude-code/mcp#configure-mcp-servers)
+- [Gemini CLI](https://cloud.google.com/gemini/docs/codeassist/use-agentic-chat-pair-programmer#configure-mcp-servers)
+
+Generally speaking, depending on your installation, you need to configure an MCP client with one of the following commands:
+
+`uv --directory path/to/deepset-mcp run deepset-mcp --workspace your_workspace --api-key your_api_key`
+
+If you installed the deepset-mcp package globally and added it to your `PATH`, you can just run:
+
+`deepset-mcp --workspace your_workspace --api-key your_api_key`
+
+The server runs locally using `stdio` to communicate with the client.
+
+### Advanced Configuration
+
+#### Tool Selection
+
+You can customize which tools the MCP server should expose.
+Use the `´--tools`-option in your config to explicitly specify which tools should be exposed.
+
+You can list available tools with: `deepset-mcp --list-tools`.
+
+To only expose the `list_pipelines` and `get_pipeline` tools you would use the following command:
+
+`deepset-mcp --tools list_pipelines get_pipeline`
+
+For smooth operations, you should always expose the `get_from_object_store` and `get_slice_from_object_store` tools.
+
+
+#### Allowing access to multiple workspaces
+
+The basic configuration uses a hardcoded workspace which you pass in via the `DEEPSET_WORKSPACE` environment variable.
+If you want to allow an agent to access resources from multiple workspaces, you can use `--workspace-mode explicit`
+in your config.
+
+For example:
 
+```json
+{
+  "mcpServers": {
+    "deepset": {
+      "command": "/opt/homebrew/bin/uv",
+      "args": [
+        "--directory",
+        "/path/to/your/clone/of/deepset-mcp-server",
+        "run",
+        "deepset-mcp",
+        "--workspace-mode",
+        "explicit"
+      ],
+      "env": {
+       "DEEPSET_API_KEY":"<DEEPSET_API_KEY>"
+     }
+
+    }
+  }
+}
+```
+
+An agent using the MCP server now has access to all workspaces that the API-key has access to. When interacting with most
+resources, you will need to tell the agent what workspace it should use to perform an action. Instead of prompting it
+with "list my pipelines", you would now have to prompt it with "list my pipelines in the staging workspace".
+
+
+## Prompts
+
+All tools exposed through the MCP server have minimal prompts. Any Agent interacting with these tools benefits from an additional system prompt.
 
-## Usage
+View the **recommended prompt** [here](src/deepset_mcp/prompts/deepset_debugging_agent.md).
 
-_Assuming you are using the MCP server through Claude Desktop and you are part of the deepset organization._
+This prompt is also exposed as the `deepset_recommended_prompt` on the MCP server.
+In Claude Desktop, click `add from deepset` to add the prompt to your context.
+A better way to add system prompts in Claude Desktop is through "Projects".
 
-**Setup:**
-1. Go to "Projects" in Claude Desktop
-2. Select the "Your Team"-tab
-3. Select the "deepset-copilot" project
+You can customize the system prompt to your specific needs.
 
-![Screenshot of the Projects menu in the Claude Desktop App.](assets/claude_desktop_projects.png)
 
-The _deepset-copilot_ project contains system instructions that are optimized for the deepset MCP server.
+## Use Cases
 
-You can also access the system prompt [here](src/deepset_mcp/prompts/deepset_copilot_prompt.md).
+The primary way to use the deepset MCP server is through an LLM that interacts with the deepset MCP tools in an agentic way.
 
-The MCP server also exposes the system prompt as the `deepset_copilot`-prompt.
-In Claude Desktop you can click on the plus-sign below the chat bar and select "Add from deepset" to add the prompt.
-However, this will only load the prompt as text context into your message. It won't set the prompt as system instructions.
-Using it via system instructions in Claude Desktop yields better results.
+### Creating Pipelines
 
-Using these instructions with Claude will help you to create or update pipelines.
-You can also ask questions about pipelines in the workspace or get information about components
-(e.g. What init params do they accept? What inputs and outputs do they have?).
+Tell the LLM about the type of pipeline you want to build. Creating new pipelines will work best if you use terminology
+that is similar to what is used on the deepset AI platform or in Haystack.
 
-You can activate and deactivate specific tools in the "Search and tools"-menu that is available below the chat bar.
+Your prompts should be precise and specific.
 
-Claude will ask for your permission before a tool call is executed. You can opt to "allow once", "allow always" or "deny".
+Examples:
 
+- "Build a RAG pipeline with hybrid retrieval that uses claude-sonnet-4 from Anthropic as the LLM."
+- "Build an Agent that can iteratively search the web (deep research). Use SerperDev for web search and GPT-4o as the LLM."
 
+You can also instruct the LLM to deploy pipelines, and it can issue search requests against pipelines to test them.
 
-**Limitations**
+**Best Practices**
 
-Unfortunately, you need to set the workspace and organization (through the API key) in the `claude_desktop_config.json`.
-There is no way to pass the API key dynamically to Claude in a secure way.
-The workspace could be passed into the tool call, it's an easy enhancement, but I'd like to get feedback first.
+- be specific in your requests
+- point the LLM to examples, if there is already a similar pipeline in your workspace, then ask it to look at it first, 
+if you have a template in mind, ask it to look at the template
+- instruct the LLM to iterate with you locally before creating the pipeline, have it validate the drafts and then let it 
+create it once the pipeline is up to your standards
 
 
+### Debugging Pipelines
 
+The `deepset-mcp` tools allow LLMs to debug pipelines on the deepset AI platform.
+Primary tools used for debugging are:
+- get_logs
+- validate_pipeline
+- search_pipeline
+- search_pipeline_templates
+- search_component_definition
 
-## Further improvements ideas
+You can ask the LLM to check the logs of a specific pipeline in case it is already deployed but has errors.
+The LLM will find errors in the logs and devise strategies to fix them.
+If your pipeline is not deployed yet, the LLM can autonomously validate it and fix validation errors.
 
-- expose standard prompts via MCP e.g., for debugging, fixing pipelines, reading logs etc
-- fix the docker run command to clear cache
-- the ability to dump the conversation of improving the copilot
-- test with different clients other than Claude Desktop app
+## CLI
+You can use the MCP server as a Haystack Agent through a command-line interface.
+
+Install with `uv pip install deepset-mcp[cli]`.
+
+Start the interactive CLI with:
+
+`deepset agent chat`
+
+You can set environment variables before starting the Agent via:
+
+```shell
+export DEEPSET_API_KEY=your_key
+export DEEPSET_WORKSPACE=your_workspace
+```
 
+You can also provide an `.env` file using the `--env-file` option:
 
+`deepset agent chat --env-file your/env/.file`
 
+The agent will load environment variables from the file on startup.

TODO.md

@@ -23,7 +23,7 @@ def get_agent(benchmark_config: BenchmarkConfig, interactive: bool = False) -> A
         },
     )
 
-    tools = MCPToolset(server_info=server_info)
+    tools = MCPToolset(server_info=server_info, invocation_timeout=300.0)
     if interactive:
         tools = wrap_toolset_interactive(tools).toolset
 

assets/deepset-mcp-3.gif

@@ -344,7 +344,10 @@ def validate_agent_config(
 
 @agent_app.command("chat")
 def chat_with_agent(
-    agent_config: str = typer.Argument(..., help="Path to agent configuration file (YAML)."),
+    agent_config: str = typer.Argument(
+        default=str(Path(__file__).parent.parent / "agent_configs/debugging_agent.yml"),
+        help="Path to agent configuration file (YAML).",
+    ),
     workspace: str | None = typer.Option(None, "--workspace", "-w", help="Override Deepset workspace."),
     api_key: str | None = typer.Option(None, "--api-key", "-k", help="Override Deepset API key."),
     env_file: str | None = typer.Option(None, "--env-file", "-e", help="Path to environment file."),

src/deepset_mcp/agents/debugging/debugging_agent.py

@@ -26,6 +26,14 @@ async def deepset_copilot() -> str:
     return prompt_path.read_text()
 
 
+@mcp.prompt()
+async def deepset_recommended_prompt() -> str:
+    """Recommended system prompt for the deepset copilot."""
+    prompt_path = Path(__file__).parent / "prompts/deepset_debugging_agent.md"
+
+    return prompt_path.read_text()
+
+
 def main() -> None:
     """Entrypoint for the deepset MCP server."""
     parser = argparse.ArgumentParser(description="Run the Deepset MCP server.")

src/deepset_mcp/benchmark/runner/cli_agent.py

@@ -1,5 +1,3 @@
-# Deepset AI Platform Debugging Agent
-
 You are an expert debugging assistant for the deepset AI platform, specializing in helping users identify and resolve issues with their pipelines and indexes. Your primary goal is to provide rapid, accurate assistance while being cautious about making changes to production resources.
 
 ## Core Capabilities
@@ -178,6 +176,16 @@ To prevent this in the future, consider [preventive measure]."
 - Reference template configurations when suggesting parameter values
 - Always provide context when showing technical output
 
+### Working with the Object Store
+
+Many tools write their output into an object store. You will see an object id (e.g. @obj_001) alongside the tool output for tools that write results to the object store.
+
+Tool output is often truncated. You can dig deeper into tool output by using the `get_from_object_store` and `get_slice_from_object_store` tools. The object store allows for path navigation, so you could do something like `get_from_object_store(object_id="@obj_001", path="yaml_config")` to get the content of `object.yaml_config`).
+
+You can also invoke many tools by reference. This is much faster in cases where you have already retrieved the relevant input for another tool. Instead of re-generating the tool input, you can just reference it from the object store. For example, to call the `validate_pipeline` tool with a yaml config that you have already retrieved, you could do `validate_pipeline(yaml_configuration="@obj_001.yaml_config")`. Make sure to use references whenever possible. They are much more efficient than invoking the tool directly.
+
+
+
 ## Error Pattern Recognition
 
 ### Common Errors and Solutions