Merge branch 'main' into fix/2939-sparse-vector-storage

Author: davidsbatista

integrations/mcp/CHANGELOG.md

@@ -1,5 +1,43 @@
 # Changelog
 
+## [integrations/mcp-v1.3.0] - 2026-03-24
+
+### 🚀 Features
+
+- Make connection to Stdio MCP servers work on notebooks by redirecting errlog (#3037)
+
+### 📚 Documentation
+
+- Fix some invalid raises directives (#2847)
+- Simplify pydoc configs (#2855)
+
+### 🧪 Testing
+
+- Test compatible integrations with python 3.14; update pyproject (#3001)
+
+### 🧹 Chores
+
+- Remove unused allow-direct-references (#2866)
+- Add ANN ruff ruleset to llama_cpp, llama_stack, mcp, meta_llama, mistral, mongodb_atlas, nvidia, ollama, openrouter, opensearch (#2991)
+- Enforce ruff docstring rules (D102/D103/D205/D209/D213/D417/D419) in integrations 21-30 (#3010)
+
+## [integrations/mcp-v1.2.0] - 2026-01-16
+
+### 🚀 Features
+
+- Add state-based configuration support to MCPToolset (#2689)
+
+
+### 🧹 Chores
+
+- Remove Readme API CI workflow and configs (#2573)
+- Make fmt command more forgiving (#2671)
+
+### 🌀 Miscellaneous
+
+- Chore: Simplify and update mcp examples (#2581)
+- Fix: Proper tool validation in mcp (#2654)
+
 ## [integrations/mcp-v1.1.0] - 2025-11-12
 
 ### 🚀 Features
@@ -33,28 +71,6 @@
 ### 🌀 Miscellaneous
 
 - Add MCPTool/MCPToolset warm_up (#2384)
-- Added `eager_connect` parameter to `MCPTool` and `MCPToolset` (default: `False`).
-  
-  **When `eager_connect=False` (default)**:
-  - Connection deferred until first use or `warm_up()` call
-  - Fast initialization, enables pipeline validation without server availability
-  - Recommended for most use cases
-  
-  **When `eager_connect=True`**:
-  - Connects immediately during initialization
-  - Fail-fast validation, tool schema available immediately
-  - Use when you need upfront validation
-  - Existing agent/pipelines should set `eager_connect=True` to keep the behaviour from previous releases
-  
-  ```python
-  # Lazy connection (default)
-  tool = MCPTool(name="weather", server_info=info)
-  
-  # Eager connection
-  tool = MCPTool(name="weather", server_info=info, eager_connect=True)
-  ```
-- See related https://github.com/deepset-ai/haystack/pull/9856 for more details
-
 
 ## [integrations/mcp-v0.8.0] - 2025-10-14
 

integrations/mcp/src/haystack_integrations/tools/mcp/mcp_tool.py

@@ -4,7 +4,10 @@
 
 import asyncio
 import concurrent.futures
+import io
 import json
+import sys
+import tempfile
 import threading
 import warnings
 from abc import ABC, abstractmethod
@@ -435,7 +438,17 @@ async def connect(self) -> list[types.Tool]:
         logger.debug(f"PROCESS: Connecting to stdio server with command: {self.command}")
 
         server_params = StdioServerParameters(command=self.command, args=self.args, env=self.env)
-        stdio_transport = await self.exit_stack.enter_async_context(stdio_client(server_params))
+
+        # In notebook environments, sys.stderr is a custom object without a real file descriptor, which causes MCP stdio
+        # connection to fail. We detect this and set the MCP server's errlog to a temp file instead.
+        errlog = sys.stderr
+        try:
+            sys.stderr.fileno()
+        except (io.UnsupportedOperation, AttributeError, OSError):
+            errlog = tempfile.NamedTemporaryFile(mode="w", suffix="-mcp-stderr.log", delete=False)
+            logger.warning("MCP server stderr redirected to {path}", path=errlog.name)
+
+        stdio_transport = await self.exit_stack.enter_async_context(stdio_client(server_params, errlog=errlog))
         return await self._initialize_session_with_transport(stdio_transport, f"stdio server (command: {self.command})")
 
 

integrations/mcp/tests/test_mcp_tool.py

@@ -1,5 +1,7 @@
+import io
 import json
 import os
+from unittest.mock import AsyncMock, MagicMock, patch
 
 import pytest
 from haystack.components.agents import Agent
@@ -13,6 +15,7 @@
     MCPTool,
     StdioServerInfo,
 )
+from haystack_integrations.tools.mcp.mcp_tool import StdioClient
 
 from .mcp_memory_transport import InMemoryServerInfo
 from .mcp_servers_fixtures import calculator_mcp, echo_mcp
@@ -197,6 +200,42 @@ def test_mcp_tool_serde_with_state_mapping(self, mcp_tool_cleanup):
         assert new_tool._inputs_from_state == {"state_a": "a"}
         assert new_tool._outputs_to_state == {"result": {"source": "output"}}
 
+    @pytest.mark.asyncio
+    @pytest.mark.parametrize(
+        "fileno_side_effect,fileno_return_value,notebook_environment",
+        [
+            (io.UnsupportedOperation("fileno"), None, True),
+            (None, 2, False),
+        ],
+    )
+    async def test_stdio_client_stderr_handling(self, fileno_side_effect, fileno_return_value, notebook_environment):
+        """Test that StdioClient uses sys.stderr in terminals and falls back to a file in notebooks."""
+        client = StdioClient(command="echo", args=["hello"])
+
+        mock_stderr = MagicMock()
+        mock_stderr.fileno.side_effect = fileno_side_effect
+        mock_stderr.fileno.return_value = fileno_return_value
+
+        with (
+            patch.object(client, "exit_stack") as mock_stack,
+            patch("haystack_integrations.tools.mcp.mcp_tool.stdio_client") as mock_stdio_client,
+            patch("haystack_integrations.tools.mcp.mcp_tool.sys") as mock_sys,
+            patch.object(client, "_initialize_session_with_transport", new_callable=AsyncMock) as mock_init,
+        ):
+            mock_sys.stderr = mock_stderr
+            mock_stack.enter_async_context = AsyncMock(return_value=(MagicMock(), MagicMock()))
+            mock_init.return_value = []
+
+            await client.connect()
+
+            _, kwargs = mock_stdio_client.call_args
+            errlog = kwargs["errlog"]
+            if notebook_environment:
+                assert errlog is not mock_stderr
+                assert hasattr(errlog, "write")
+            else:
+                assert errlog is mock_stderr
+
     @pytest.mark.skipif("OPENAI_API_KEY" not in os.environ, reason="OPENAI_API_KEY not set")
     @pytest.mark.integration
     def test_pipeline_warmup_with_mcp_tool(self):

integrations/openrouter/pyproject.toml

@@ -85,6 +85,13 @@ select = [
   "ARG",
   "B",
   "C",
+  "D102",   # Missing docstring in public method
+  "D103",   # Missing docstring in public function
+  "D205",   # 1 blank line required between summary line and description
+  "D209",   # Closing triple quotes go to new line
+  "D213",   # summary lines must be positioned on the second physical line of the docstring
+  "D417",   # Missing argument descriptions in the docstring
+  "D419",   # Docstring is empty
   "DTZ",
   "E",
   "EM",
@@ -134,9 +141,9 @@ ban-relative-imports = "parents"
 
 [tool.ruff.lint.per-file-ignores]
 # Tests can use magic values, assertions, and relative imports
-"tests/**/*" = ["PLR2004", "S101", "TID252", "ANN"]
+"tests/**/*" = ["D", "PLR2004", "S101", "TID252", "ANN"]
 # Examples can print their output and don't need type annotations
-"examples/**/*" = ["T201", "ANN"]
+"examples/**/*" = ["D", "T201", "ANN"]
 
 [tool.coverage.run]
 source = ["haystack_integrations"]

integrations/openrouter/src/haystack_integrations/components/generators/openrouter/chat/chat_generator.py

@@ -18,6 +18,7 @@
 class OpenRouterChatGenerator(OpenAIChatGenerator):
     """
     Enables text generation using OpenRouter generative models.
+
     For supported models, see [OpenRouter docs](https://openrouter.ai/models).
 
     Users can pass any text generation parameters valid for the OpenRouter chat completion API
@@ -71,8 +72,7 @@ def __init__(
         http_client_kwargs: dict[str, Any] | None = None,
     ) -> None:
         """
-        Creates an instance of OpenRouterChatGenerator. Unless specified otherwise,
-        the default model is `openai/gpt-5-mini`.
+        Creates an instance of OpenRouterChatGenerator.
 
         :param api_key:
             The OpenRouter API key.

integrations/opensearch/pyproject.toml

@@ -94,6 +94,13 @@ select = [
   "ARG",
   "B",
   "C",
+  "D102",   # Missing docstring in public method
+  "D103",   # Missing docstring in public function
+  "D205",   # 1 blank line required between summary line and description
+  "D209",   # Closing triple quotes go to new line
+  "D213",   # summary lines must be positioned on the second physical line of the docstring
+  "D417",   # Missing argument descriptions in the docstring
+  "D419",   # Docstring is empty
   "DTZ",
   "E",
   "EM",
@@ -145,7 +152,7 @@ ban-relative-imports = "parents"
 
 [tool.ruff.lint.per-file-ignores]
 # Tests can use magic values, assertions, and relative imports
-"tests/**/*" = ["PLR2004", "S101", "TID252", "ANN"]
+"tests/**/*" = ["D", "PLR2004", "S101", "TID252", "ANN"]
 
 [tool.coverage.run]
 source = ["haystack_integrations"]

integrations/opensearch/src/haystack_integrations/components/retrievers/opensearch/open_search_hybrid_retriever.py

@@ -114,8 +114,9 @@ def __init__(
         **kwargs: Any,
     ) -> None:
         """
-        Initialize the OpenSearchHybridRetriever, a super component to retrieve documents from OpenSearch using
-        both embedding-based and keyword-based retrieval methods.
+        Initialize the OpenSearchHybridRetriever using both embedding-based and keyword-based retrieval methods.
+
+        This is a super component to retrieve documents from OpenSearch using both retrieval methods.
 
         We don't explicitly define all the init parameters of the components in the constructor, for each
         of the components, since that would be around 20+ parameters. Instead, we define the most important ones
@@ -242,7 +243,9 @@ def __init__(
 
     if TYPE_CHECKING:
 
-        def warm_up(self) -> None: ...
+        def warm_up(self) -> None:
+            """Warm up the underlying pipeline components."""
+            ...
 
         def run(
             self,
@@ -251,7 +254,9 @@ def run(
             filters_embedding: dict[str, Any] | None = None,
             top_k_bm25: int | None = None,
             top_k_embedding: int | None = None,
-        ) -> dict[str, list[Document]]: ...
+        ) -> dict[str, list[Document]]:
+            """Run the hybrid retrieval pipeline and return retrieved documents."""
+            ...
 
     def _create_pipeline(self, data: dict[str, Any]) -> Pipeline:
         """
@@ -328,6 +333,7 @@ def to_dict(self) -> dict[str, Any]:
 
     @classmethod
     def from_dict(cls, data: dict[str, Any]) -> "OpenSearchHybridRetriever":
+        """Deserialize an OpenSearchHybridRetriever from a dictionary."""
         # deserialize the document store
         doc_store = OpenSearchDocumentStore.from_dict(data["init_parameters"]["document_store"])
         data["init_parameters"]["document_store"] = doc_store

integrations/opensearch/src/haystack_integrations/document_stores/opensearch/auth.py

@@ -41,6 +41,7 @@ def _get_aws_session(
 ) -> "boto3.Session":
     """
     Creates an AWS Session with the given parameters.
+
     Checks if the provided AWS credentials are valid and can be used to connect to AWS.
 
     :param aws_access_key_id: AWS access key ID.

integrations/opensearch/src/haystack_integrations/document_stores/opensearch/document_store.py

@@ -559,6 +559,7 @@ async def write_documents_async(
     def _deserialize_document(hit: dict[str, Any]) -> Document:
         """
         Creates a Document from the search hit provided.
+
         This is mostly useful in self.filter_documents().
         """
         data = hit["_source"]
@@ -1482,6 +1483,7 @@ def _embedding_retrieval(
     ) -> list[Document]:
         """
         Retrieves documents that are most similar to the query embedding using a vector similarity metric.
+
         It uses the OpenSearch's Approximate k-Nearest Neighbors search algorithm.
 
         This method is not meant to be part of the public interface of
@@ -1513,8 +1515,9 @@ async def _embedding_retrieval_async(
         search_kwargs: dict[str, Any] | None = None,
     ) -> list[Document]:
         """
-        Asynchronously retrieves documents that are most similar to the query embedding using a vector similarity
-        metric. It uses the OpenSearch's Approximate k-Nearest Neighbors search algorithm.
+        Asynchronously retrieves documents most similar to the query embedding using a vector similarity metric.
+
+        It uses the OpenSearch's Approximate k-Nearest Neighbors search algorithm.
 
         This method is not meant to be part of the public interface of
         `OpenSearchDocumentStore` nor called directly.
@@ -1641,8 +1644,7 @@ def _extract_distinct_counts_from_aggregations(
 
     def count_unique_metadata_by_filter(self, filters: dict[str, Any], metadata_fields: list[str]) -> dict[str, int]:
         """
-        Returns the number of unique values for each specified metadata field of the documents
-        that match the provided filters.
+        Returns the number of unique values for each specified metadata field of the documents that match the filters.
 
         :param filters: The filters to apply to count documents.
             For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
@@ -1685,8 +1687,7 @@ async def count_unique_metadata_by_filter_async(
         self, filters: dict[str, Any], metadata_fields: list[str]
     ) -> dict[str, int]:
         """
-        Asynchronously returns the number of unique values for each specified metadata field of the documents
-        that match the provided filters.
+        Asynchronously returns the number of unique values for each specified metadata field matching the filters.
 
         :param filters: The filters to apply to count documents.
             For filter syntax, see [Haystack metadata filtering](https://docs.haystack.deepset.ai/docs/metadata-filtering)
@@ -1862,6 +1863,7 @@ def get_metadata_field_unique_values(
     ) -> tuple[list[str], dict[str, Any] | None]:
         """
         Returns unique values for a metadata field, optionally filtered by a search term in the content.
+
         Uses composite aggregations for proper pagination beyond 10k results.
 
         :param metadata_field: The metadata field to get unique values for.
@@ -1927,6 +1929,7 @@ async def get_metadata_field_unique_values_async(
     ) -> tuple[list[str], dict[str, Any] | None]:
         """
         Asynchronously returns unique values for a metadata field, optionally filtered by a search term in the content.
+
         Uses composite aggregations for proper pagination beyond 10k results.
 
         :param metadata_field: The metadata field to get unique values for.

integrations/optimum/pyproject.toml

@@ -108,6 +108,13 @@ select = [
   "ARG",
   "B",
   "C",
+  "D102",   # Missing docstring in public method
+  "D103",   # Missing docstring in public function
+  "D205",   # 1 blank line required between summary line and description
+  "D209",   # Closing triple quotes go to new line
+  "D213",   # summary lines must be positioned on the second physical line of the docstring
+  "D417",   # Missing argument descriptions in the docstring
+  "D419",   # Docstring is empty
   "DTZ",
   "E",
   "EM",
@@ -153,9 +160,9 @@ ban-relative-imports = "parents"
 
 [tool.ruff.lint.per-file-ignores]
 # Tests can use magic values, assertions, and relative imports
-"tests/**/*" = ["PLR2004", "S101", "TID252", "ANN"]
+"tests/**/*" = ["D", "PLR2004", "S101", "TID252", "ANN"]
 # Examples can print their output
-"examples/**" = ["T201"]
+"examples/**" = ["D", "T201"]
 "tests/**" = ["T201"]
 
 [tool.coverage.run]