deepset-mcp 0.0.2__tar.gz

deepset_mcp-0.0.2/.github/workflows/ai_agent.yml

@@ -0,0 +1,27 @@
+name: AI Agent
+
+on:
+  issues:
+    types: [labeled]
+  issue_comment:
+    types: [created]
+
+jobs:
+  process-ai-issue:
+    if: |
+      (github.event_name == 'issues' && github.event.label.name == 'deepset-ai') ||
+      (github.event_name == 'issue_comment' && contains(github.event.issue.labels.*.name, 'deepset-ai'))
+    runs-on: ubuntu-latest
+    steps:
+      - name: Send Issue to deepset AI Platform
+        env:
+          DEEPSET_API_TOKEN: ${{ secrets.DEEPSET_API_TOKEN }}
+          ISSUE_URL: ${{ github.event.issue.html_url }}
+          REPOSITORY: ${{ github.repository }}
+        run: |
+          curl --request POST \
+               --url https://api.cloud.deepset.ai/api/v1/workspaces/default/pipelines/github-agent-claude/search \
+               --header 'accept: application/json' \
+               --header 'authorization: Bearer ${{ env.DEEPSET_API_TOKEN }}' \
+               --header 'content-type: application/json' \
+               --data '{"debug": false, "view_prompts": false, "queries": ["${{ env.ISSUE_URL }}"], "params": {"agent": {"repo": "${{ env.REPOSITORY }}"}}}'

deepset_mcp-0.0.2/.github/workflows/ci.yml

@@ -0,0 +1,71 @@
+name: Run CI
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  test:
+    name: Run Tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Install Python
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: ".python-version"
+
+      - name: Install project
+        run: uv sync --locked --all-extras --dev
+
+      - name: Run tests
+        run: uv run --dev pytest -m "not integration"
+
+  lint:
+    name: Run Linting
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Install Python
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: ".python-version"
+
+      - name: Install project
+        run: uv sync --locked --all-extras --group lint
+
+      - name: Run lint
+        run: uv run ruff check
+
+      - name: Run format
+        run: uv run ruff format --check
+
+  types:
+    name: Run mypy
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Install Python
+        uses: actions/setup-python@v5
+        with:
+          python-version-file: ".python-version"
+
+      - name: Install project
+        run: uv sync --locked --all-extras --group types
+
+      - name: Run types
+        run: uv run mypy src/ test/

deepset_mcp-0.0.2/.github/workflows/docker_push.yml

@@ -0,0 +1,45 @@
+name: Docker image release
+
+on:
+  workflow_dispatch:
+  push:
+    branches: [main]
+    tags: ["v[0-9].[0-9]+.[0-9]+*"]
+
+
+jobs:
+  build-and-push:
+    name: Build base image
+    runs-on: ubuntu-latest
+    if: github.repository_owner == 'deepset-ai'
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Login to DockerHub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKER_HUB_USER }}
+          password: ${{ secrets.DOCKER_HUB_TOKEN }}
+          
+      - name: Docker meta
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: deepset/deepset-mcp-server
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v6
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}

deepset_mcp-0.0.2/.github/workflows/pypi_release.yml

@@ -0,0 +1,47 @@
+name: Publish deepset-mcp distribution to PyPI and TestPyPI
+on:
+  push:
+    tags:
+      - 'v*.*.*'        # matches v1.0.0, v0.10.0, etc.
+      - 'v*.*.*-rc*'    # matches v1.0.2-rc1, v0.10.0-rc2, etc.
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        persist-credentials: false
+    - name: Install uv
+      uses: astral-sh/setup-uv@v5
+    - name: Set up Python
+      run: uv python install
+    - name: Install the project
+      run: uv sync --locked --all-extras --dev
+    - name: Build a binary wheel and a source tarball
+      run: uv build
+    - name: Store the distribution packages
+      uses: actions/upload-artifact@v4
+      with:
+        name: python-package-distributions
+        path: dist/
+  publish-to-pypi:
+    name: >-
+      Publish deepset-mcp distribution to PyPI
+    if: startsWith(github.ref, 'refs/tags/')  # only publish to PyPI on tag pushes
+    needs:
+    - build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/deepset-mcp
+    permissions:
+      id-token: write  # IMPORTANT: mandatory for trusted publishing
+    steps:
+    - name: Download all the dists
+      uses: actions/download-artifact@v4
+      with:
+        name: python-package-distributions
+        path: dist/
+    - name: Publish distribution to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1

deepset_mcp-0.0.2/.gitignore

@@ -0,0 +1,28 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+data/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# env files
+.env
+.env.prod
+.env.dev
+.env.test
+
+
+agent_runs/
+
+misc.xml
+modules.xml
+profiles_settings.xml
+deepset-mcp-server.iml
+Project_Default.xml
+pyright-overrides.xml
+vcs.xml

deepset_mcp-0.0.2/.python-version

@@ -0,0 +1 @@
+3.11

deepset_mcp-0.0.2/Dockerfile

@@ -0,0 +1,57 @@
+# ─── BUILD STAGE ───────────────────────────────────────────────────────────────
+FROM python:3.11-slim AS builder
+
+# 1. Install curl & build tools for uv & any C extensions
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends curl build-essential git \
+ && rm -rf /var/lib/apt/lists/*
+
+# 2. Install uv standalone and symlink it
+RUN curl -LsSf https://astral.sh/uv/install.sh | sh \
+ && ln -sf /root/.local/bin/uv /usr/local/bin/uv
+
+WORKDIR /src
+
+# We need git for uv-dynamic-versioning
+COPY .git/ .git/
+
+# 3. Copy in only what uv needs to build the locked venv
+COPY pyproject.toml uv.lock README.md entrypoint.sh ./
+COPY src/deepset_mcp/ src/deepset_mcp/
+
+# 4. Create & populate .venv from uv.lock
+RUN uv sync --locked
+
+
+
+# ─── RUNTIME STAGE ─────────────────────────────────────────────────────────────
+FROM python:3.11-slim
+
+# 2. Create an unprivileged user with a home directory
+RUN groupadd --system appgroup \
+ && useradd --system --create-home --home-dir /home/appuser --gid appgroup appuser
+
+ENV HOME=/home/appuser
+
+WORKDIR /app
+
+# 5. Copy in the pre-built venv and your project sources
+COPY --from=builder /src/.venv               /app/.venv
+COPY --from=builder /src/pyproject.toml      /app/pyproject.toml
+COPY --from=builder /src/uv.lock              /app/uv.lock
+COPY --from=builder /src/README.md            /app/README.md
+COPY --from=builder /src/src/deepset_mcp      /app/src/deepset_mcp
+COPY --from=builder /src/entrypoint.sh        /app/entrypoint.sh
+
+RUN chmod +x /app/entrypoint.sh
+
+# 6. Ensure appuser owns all of /app
+RUN chown -R appuser:appgroup /app
+
+# 7. Put the venv’s bin first in PATH
+ENV PATH="/app/.venv/bin:${PATH}"
+
+# 9. Switch to non-root user
+USER appuser
+
+ENTRYPOINT ["/app/entrypoint.sh"]

deepset_mcp-0.0.2/Makefile

@@ -0,0 +1,62 @@
+.PHONY: help install test test-unit test-integration test-integration-slow test-all lint lint-fix format format-check types clean
+
+# Default target
+help:
+	@echo "Available commands:"
+	@echo "  install              Install dependencies with uv"
+	@echo "  test-unit            Run unit tests only (excludes integration tests)"
+	@echo "  test-integration     Run integration tests without extra slow tests"
+	@echo "  test-integration-slow Run integration tests including extra slow tests"
+	@echo "  test-all             Run all tests"
+	@echo "  lint                 Run ruff check"
+	@echo "  lint-fix             Run ruff check with --fix"
+	@echo "  format               Run ruff format"
+	@echo "  format-check         Run ruff format with --check"
+	@echo "  types                Run mypy type checking"
+	@echo "  clean                Clean up cache files"
+
+# Install dependencies
+install:
+	uv sync --locked --all-extras --all-groups
+
+# Test commands
+test-unit:
+	uv run --dev pytest -m "not integration"
+
+test-integration:
+	uv run --dev pytest -m "integration and not extra_slow"
+
+test-integration-slow:
+	uv run --dev pytest -m "integration"
+
+test-all:
+	uv run --dev pytest
+
+# Shorthand for test-unit (most common use case)
+test: test-unit
+
+# Linting commands
+lint:
+	uv run ruff check
+
+lint-fix:
+	uv run ruff check --fix
+
+# Formatting commands
+format:
+	uv run ruff format
+
+format-check:
+	uv run ruff format --check
+
+# Type checking
+types:
+	uv run mypy src/ test/
+
+# Clean up
+clean:
+	find . -type f -name "*.pyc" -delete
+	find . -type d -name "__pycache__" -delete
+	find . -type d -name ".pytest_cache" -exec rm -rf {} +
+	find . -type d -name ".mypy_cache" -exec rm -rf {} +
+	find . -type d -name ".ruff_cache" -exec rm -rf {} +

deepset_mcp-0.0.2/PKG-INFO

@@ -0,0 +1,288 @@
+Metadata-Version: 2.4
+Name: deepset-mcp
+Version: 0.0.2
+Summary: Collection of MCP tools and Agents to work with the deepset AI platform. Create, debug or learn about pipelines on the platform. Useable from the CLI, Cursor, Claude Code, or other MCP clients.
+Project-URL: Homepage, https://deepset.ai
+Author-email: Mathis Lucka <mathis.lucka@deepset.ai>, Tanay Soni <tanay.soni@deepset.ai>
+Keywords: Agents,Haystack,LLM,MCP,deepset,pipelines
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Requires-Dist: fastapi
+Requires-Dist: glom
+Requires-Dist: httpx
+Requires-Dist: mcp>=1.10.1
+Requires-Dist: model2vec
+Requires-Dist: numpy
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: pyyaml
+Requires-Dist: rich
+Provides-Extra: analysis
+Requires-Dist: jupyterlab; extra == 'analysis'
+Requires-Dist: matplotlib; extra == 'analysis'
+Requires-Dist: pandas; extra == 'analysis'
+Requires-Dist: seaborn; extra == 'analysis'
+Provides-Extra: cli
+Requires-Dist: anthropic-haystack>=2.7.0; extra == 'cli'
+Requires-Dist: haystack-ai>=2.15.1; extra == 'cli'
+Requires-Dist: langfuse-haystack; extra == 'cli'
+Requires-Dist: mcp-haystack>=0.4.0; extra == 'cli'
+Requires-Dist: typer; extra == 'cli'
+Description-Content-Type: text/markdown
+
+# 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.
+
+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
+
+### Claude Desktop App
+
+**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/) ([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:**
+1. Go to: `/Users/your_user/Library/Application Support/Claude` (Mac)
+2. Either open or create `claude_desktop_config.json`
+3. Add the following json as your config (or update your existing config if you are already using other MCP servers)
+
+```json
+{
+  "mcpServers": {
+    "deepset": {
+      "command": "/usr/local/bin/docker",
+      "args": [
+        "run",
+        "-i",
+        "-e",
+        "DEEPSET_WORKSPACE",
+        "-e",
+        "DEEPSET_API_KEY",
+        "deepset/deepset-mcp-server:main"
+      ],
+      "env": {
+       "DEEPSET_WORKSPACE":"<WORKSPACE>",
+       "DEEPSET_API_KEY":"<DEEPSET_API_KEY>"
+     }
+
+    }
+  }
+}
+```
+
+4. Quit and start the Claude Desktop App
+5. The deepset server should appear in the "Search and Tools" menu (this takes a few seconds as the Docker image needs to be downloaded and started)
+
+![Screenshot of the Search and Tools menu in the Claude Desktop App with deepset server running.](assets/claude_desktop_with_tools.png)
+
+
+
+#### Using uv instead of Docker
+
+Running the server with uv gives you faster startup time and consumes slightly less resources on your system.
+
+1. [Install uv](https://docs.astral.sh/uv/guides/install-python/) if you don't have it yet
+2. Put the following into your `claude_desktop_config.json`
+
+```python
+{
+  "mcpServers": {
+    "deepset": {
+      "command": "uvx",
+      "args": [
+        "deepset-mcp"
+      ],
+      "env": {
+       "DEEPSET_WORKSPACE":"<WORKSPACE>",
+       "DEEPSET_API_KEY":"<DEEPSET_API_KEY>"
+     }
+
+    }
+  }
+}
+```
+
+This will load the [deepset-mcp package from PyPi](https://pypi.org/project/deepset-mcp/) and install it into a temporary virtual environment.
+
+3. Quit and start the Claude Desktop App
+
+
+
+### Other MCP Clients
+
+`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:
+
+`uvx 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": "uvx",
+      "args": [
+        "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.
+
+View the **recommended prompt** [here](src/deepset_mcp/prompts/deepset_debugging_agent.md).
+
+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".
+
+You can customize the system prompt to your specific needs.
+
+
+## Use Cases
+
+The primary way to use the deepset MCP server is through an LLM that interacts with the deepset MCP tools in an agentic way.
+
+### Creating Pipelines
+
+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.
+
+Your prompts should be precise and specific.
+
+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.
+
+**Best Practices**
+
+- 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
+
+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.
+
+## CLI
+You can use the MCP server as a Haystack Agent through a command-line interface.
+
+Install with `uvx tool 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.