feat: add custom components tools and resources (#73)

* feat: add custom components package

* feat: add custom components models

* feat: add custom components resource

* feat: add custom components imports to protocols

* feat: add custom components protocol

* feat: add custom components to client protocol

* feat: add custom components import to client

* feat: add custom components method to client

* feat: add get_custom_components tool function

* feat: add custom components tools

* feat: import get_custom_components tool

* feat: import custom components tools

* feat: add custom components mcp tools

* clean: remove commented code

* refactor: remove workspace dependency from CustomComponentsResource

* refactor: remove get_user method from CustomComponentsResource

* feat: create user api package

* feat: create UserResource for managing user operations

* refactor: update imports to use DeepsetUser from shared_models

* feat: add UserResourceProtocol and update CustomComponentsProtocol

* feat: add users method to AsyncClientProtocol

* feat: import UserResource in client

* feat: add users method and update custom_components to not pass workspace

* refactor: remove User model from custom_components models

* refactor: use separate users resource for user information

* refactor: update get_latest_custom_component_installation_logs to use new resource pattern

* test: add CustomComponentsProtocol and UserResourceProtocol imports

* test: add custom_components and users methods to BaseFakeClient

* test: create custom_components test package

* test: add unit tests for CustomComponentsResource

* test: create user test package

* test: add unit tests for UserResource

* test: add unit tests for custom_components tools

* test: add integration tests for UserResource

* fix: use correct field name for DeepsetUser model

* fix: add type annotations to test methods

* fix: add type annotations and type ignore in empty test

* fix: add type annotations and type ignore in user fetch error test

* fix: add type annotations and type ignore in api error test

* fix: add type annotations and type ignore in logs test

* fix: add type annotations and type ignore in empty logs test

* fix: add type annotations and type ignore in logs api error test

* add type ignore for main test method assignment

* fix: remove unused import

* fix: add exact endpoint with query params and type annotations

* fix: add exact endpoint with query params and type annotations for empty test

* fix: add exact endpoint with custom query params for with_params test

* fix: add type annotations for logs test

* check logs test result

* fix: add type annotations and correct assertion for none test

* fix: add type annotations for get_user test

* fix: add type annotations for get_user_partial_data test

* fix: add type annotations for get_user_not_found test

* fix: properly instantiate DeepsetUser from response data

* fix: return proper string type for logs

* fix: properly instantiate CustomComponentInstallationList from response data

* fix: improve endpoint matching and handle non-dict responses better

* fix: update protocol to match correct return type

* WIP

* fix: tests, lint etc

* fix: APIError init

Author: mathislucka

src/deepset_mcp/api/client.py

@@ -2,12 +2,14 @@
 from types import TracebackType
 from typing import Any, Self, TypeVar, overload
 
+from deepset_mcp.api.custom_components.resource import CustomComponentsResource
 from deepset_mcp.api.haystack_service.resource import HaystackServiceResource
 from deepset_mcp.api.indexes.resource import IndexResource
 from deepset_mcp.api.pipeline.resource import PipelineResource
 from deepset_mcp.api.pipeline_template.resource import PipelineTemplateResource
 from deepset_mcp.api.protocols import AsyncClientProtocol
 from deepset_mcp.api.transport import AsyncTransport, TransportProtocol, TransportResponse
+from deepset_mcp.api.user.resource import UserResource
 
 T = TypeVar("T")
 
@@ -139,3 +141,11 @@ def pipeline_templates(self, workspace: str) -> PipelineTemplateResource:
     def indexes(self, workspace: str) -> IndexResource:
         """Resource to interact with indexes in the specified workspace."""
         return IndexResource(client=self, workspace=workspace)
+
+    def custom_components(self, workspace: str) -> CustomComponentsResource:
+        """Resource to interact with custom components in the specified workspace."""
+        return CustomComponentsResource(client=self)
+
+    def users(self) -> UserResource:
+        """Resource to interact with users."""
+        return UserResource(client=self)

src/deepset_mcp/api/custom_components/__init__.py

@@ -0,0 +1,22 @@
+from typing import Any
+
+from pydantic import BaseModel
+
+
+class CustomComponentInstallation(BaseModel):
+    """Model representing a custom component installation."""
+
+    custom_component_id: str
+    status: str
+    version: str
+    created_by_user_id: str
+    logs: list[dict[str, Any]]
+    organization_id: str
+
+
+class CustomComponentInstallationList(BaseModel):
+    """Model representing a list of custom component installations."""
+
+    data: list[CustomComponentInstallation]
+    total: int
+    has_more: bool

src/deepset_mcp/api/custom_components/models.py

@@ -0,0 +1,55 @@
+from typing import Any
+
+from deepset_mcp.api.custom_components.models import CustomComponentInstallationList
+from deepset_mcp.api.protocols import AsyncClientProtocol, CustomComponentsProtocol
+from deepset_mcp.api.transport import raise_for_status
+
+
+class CustomComponentsResource(CustomComponentsProtocol):
+    """Resource for managing custom components in deepset."""
+
+    def __init__(self, client: AsyncClientProtocol) -> None:
+        """Initialize a CustomComponentsResource.
+
+        :param client: The API client to use for requests.
+        """
+        self._client = client
+
+    async def list_installations(
+        self, limit: int = 20, page_number: int = 1, field: str = "created_at", order: str = "DESC"
+    ) -> CustomComponentInstallationList:
+        """List custom component installations.
+
+        :param limit: Maximum number of installations to return.
+        :param page_number: Page number for pagination.
+        :param field: Field to sort by.
+        :param order: Sort order (ASC or DESC).
+
+        :returns: List of custom component installations.
+        """
+        resp = await self._client.request(
+            endpoint=f"v2/custom_components?limit={limit}&page_number={page_number}&field={field}&order={order}",
+            method="GET",
+            response_type=dict[str, Any],
+        )
+
+        raise_for_status(resp)
+
+        if resp.json is None:
+            return CustomComponentInstallationList(data=[], total=0, has_more=False)
+
+        return CustomComponentInstallationList(**resp.json)
+
+    async def get_latest_installation_logs(self) -> str | None:
+        """Get the logs from the latest custom component installation.
+
+        :returns: Latest installation logs.
+        """
+        resp = await self._client.request(
+            endpoint="v2/custom_components/logs",
+            method="GET",
+        )
+
+        raise_for_status(resp)
+
+        return resp.text

src/deepset_mcp/api/custom_components/resource.py

@@ -1,6 +1,7 @@
 from types import TracebackType
 from typing import Any, Protocol, Self, TypeVar, overload
 
+from deepset_mcp.api.custom_components.models import CustomComponentInstallationList
 from deepset_mcp.api.indexes.models import Index, IndexList
 from deepset_mcp.api.pipeline.log_level import LogLevel
 from deepset_mcp.api.pipeline.models import (
@@ -10,6 +11,7 @@
     PipelineValidationResult,
 )
 from deepset_mcp.api.pipeline_template.models import PipelineTemplate
+from deepset_mcp.api.shared_models import DeepsetUser
 from deepset_mcp.api.transport import TransportResponse
 
 
@@ -25,6 +27,28 @@ async def get_component_input_output(self, component_name: str) -> dict[str, Any
         ...
 
 
+class CustomComponentsProtocol(Protocol):
+    """Protocol defining the implementation for CustomComponentsResource."""
+
+    async def list_installations(
+        self, limit: int = 20, page_number: int = 1, field: str = "created_at", order: str = "DESC"
+    ) -> CustomComponentInstallationList:
+        """List custom component installations."""
+        ...
+
+    async def get_latest_installation_logs(self) -> str | None:
+        """Get the logs from the latest custom component installation."""
+        ...
+
+
+class UserResourceProtocol(Protocol):
+    """Protocol defining the implementation for UserResource."""
+
+    async def get(self, user_id: str) -> DeepsetUser:
+        """Get user information by user ID."""
+        ...
+
+
 T = TypeVar("T")
 
 
@@ -98,6 +122,14 @@ def indexes(self, workspace: str) -> "IndexResourceProtocol":
         """Access indexes in the specified workspace."""
         ...
 
+    def custom_components(self, workspace: str) -> "CustomComponentsProtocol":
+        """Access custom components in the specified workspace."""
+        ...
+
+    def users(self) -> "UserResourceProtocol":
+        """Access users."""
+        ...
+
 
 class IndexResourceProtocol(Protocol):
     """Protocol defining the implementation for IndexResource."""

src/deepset_mcp/api/protocols.py

@@ -0,0 +1,37 @@
+from typing import Any
+
+from deepset_mcp.api.exceptions import ResourceNotFoundError
+from deepset_mcp.api.protocols import AsyncClientProtocol, UserResourceProtocol
+from deepset_mcp.api.shared_models import DeepsetUser
+from deepset_mcp.api.transport import raise_for_status
+
+
+class UserResource(UserResourceProtocol):
+    """Resource for managing users in deepset."""
+
+    def __init__(self, client: AsyncClientProtocol) -> None:
+        """Initialize a UserResource.
+
+        :param client: The API client to use for requests.
+        """
+        self._client = client
+
+    async def get(self, user_id: str) -> DeepsetUser:
+        """Get user information by user ID.
+
+        :param user_id: The ID of the user to fetch.
+
+        :returns: User information.
+        """
+        resp = await self._client.request(
+            endpoint=f"v1/users/{user_id}",
+            method="GET",
+            response_type=dict[str, Any],
+        )
+
+        raise_for_status(resp)
+
+        if resp.json is None:
+            raise ResourceNotFoundError(f"User '{user_id}' not found.")
+
+        return DeepsetUser(**resp.json)