feat: add list_component_families tool (#23)

* feat: add list_component_families tool

* test: add tests for list_component_families tool

* feat: wrapup component family tool

Author: mathislucka

README.md

@@ -40,3 +40,13 @@ To use it with Claude Desktop app, use the following config:
 - the ability to dump the conversation of improving the copilot
 - test with different models not just Claude Sonnet 3.7
 - test with different clients other than Claude Desktop app
+
+
+## Todo
+
+### Haystack Knowledge
+- list_component_families
+- get_component_family
+- get_component_definition
+
+

src/deepset_mcp/main.py

@@ -1,9 +1,9 @@
 import os
-from typing import Any
 
 from mcp.server.fastmcp import FastMCP
 
 from deepset_mcp.api.client import AsyncDeepsetClient
+from deepset_mcp.tools.haystack_service import list_component_families as list_component_families_tool
 from deepset_mcp.tools.pipeline import (
     create_pipeline as create_pipeline_tool,
     get_pipeline as get_pipeline_tool,
@@ -88,15 +88,16 @@ async def update_pipeline(
 
 
 @mcp.tool()
-async def get_component_schemas() -> Any:
-    """Retrieves the schemas for all available Haystack components from the deepset API.
+async def list_component_families() -> str:
+    """
+    Returns a list of all component families available in deepset alongside their descriptions.
 
-    These schemas define the expected input and output parameters for each component type, which is useful for
-    constructing or validating componets in a pipeline YAML.
+    Use this as a starting point for when you are unsure what types of components are available.
     """
     async with AsyncDeepsetClient() as client:
-        response = await client.request(endpoint="v1/haystack/components", method="GET")
-        return response.json
+        response = await list_component_families_tool(client)
+
+    return response
 
 
 @mcp.tool()

src/deepset_mcp/tools/haystack_service.py

@@ -0,0 +1,31 @@
+from deepset_mcp.api.exceptions import UnexpectedAPIError
+from deepset_mcp.api.protocols import AsyncClientProtocol
+
+
+async def list_component_families(client: AsyncClientProtocol) -> str:
+    """Lists all Haystack component families that are available on deepset."""
+    haystack_service = client.haystack_service()
+
+    try:
+        response = await haystack_service.get_component_schemas()
+    except UnexpectedAPIError as e:
+        return f"Failed to retrieve component families: {e}"
+
+    components = response["component_schema"]["definitions"]["Components"]
+
+    families = {}
+    for component_def in components.values():
+        component_type = component_def["properties"]["type"]
+        family = component_type["family"]
+        description = component_type.get("family_description", "No description available.")
+        families[family] = description
+
+    if not families:
+        return "No component families found in the response"
+
+    # Format the families into a readable string
+    parts = ["Available Haystack component families:\n"]
+    for family, description in sorted(families.items()):
+        parts.append(f"\n**{family}**\n{description}\n")
+
+    return "\n".join(parts)

test/unit/tools/test_haystack_service.py

@@ -0,0 +1,80 @@
+from typing import Any
+
+import pytest
+
+from deepset_mcp.api.exceptions import UnexpectedAPIError
+from deepset_mcp.tools.haystack_service import list_component_families
+from test.unit.conftest import BaseFakeClient
+
+
+class FakeHaystackServiceResource:
+    def __init__(
+        self, get_component_schemas_response: dict[str, Any] | None = None, exception: Exception | None = None
+    ):
+        self._get_component_schemas_response = get_component_schemas_response
+        self._exception = exception
+
+    async def get_component_schemas(self) -> dict[str, Any]:
+        if self._exception:
+            raise self._exception
+        if self._get_component_schemas_response is not None:
+            return self._get_component_schemas_response
+        raise NotImplementedError
+
+
+class FakeClient(BaseFakeClient):
+    def __init__(self, resource: FakeHaystackServiceResource):
+        self._resource = resource
+        super().__init__()
+
+    def haystack_service(self) -> FakeHaystackServiceResource:
+        return self._resource
+
+
+@pytest.mark.asyncio
+async def test_list_component_families_no_families() -> None:
+    response: dict[str, Any] = {"component_schema": {"definitions": {"Components": {}}}}
+    resource = FakeHaystackServiceResource(get_component_schemas_response=response)
+    client = FakeClient(resource)
+    result = await list_component_families(client)
+    assert "No component families found" in result
+
+
+@pytest.mark.asyncio
+async def test_list_component_families_success() -> None:
+    response = {
+        "component_schema": {
+            "definitions": {
+                "Components": {
+                    "Component1": {
+                        "properties": {"type": {"family": "converters", "family_description": "Convert data format"}}
+                    },
+                    "Component2": {"properties": {"type": {"family": "readers", "family_description": "Read data"}}},
+                    # Should be ignored - same family as Component1
+                    "Component3": {
+                        "properties": {"type": {"family": "converters", "family_description": "Convert data format"}}
+                    },
+                }
+            }
+        }
+    }
+    resource = FakeHaystackServiceResource(get_component_schemas_response=response)
+    client = FakeClient(resource)
+    result = await list_component_families(client)
+
+    assert "Available Haystack component families" in result
+    assert "**converters**" in result
+    assert "Convert data format" in result
+    assert "**readers**" in result
+    assert "Read data" in result
+    # Only two unique families should be present
+    assert result.count("**") == 4  # Two sets of ** for each family
+
+
+@pytest.mark.asyncio
+async def test_list_component_families_api_error() -> None:
+    resource = FakeHaystackServiceResource(exception=UnexpectedAPIError(status_code=500, message="API Error"))
+    client = FakeClient(resource)
+    result = await list_component_families(client)
+    assert "Failed to retrieve component families" in result
+    assert "API Error" in result