feat: add resource for integrations (#134)

* feat: create integrations package

* feat: add integration models

* feat: add integration resource protocol

* feat: add integration resource implementation

* feat: add integration resource protocol import

* feat: add integrations method to AsyncClientProtocol

* feat: add integration resource import to client

* feat: add integrations method to AsyncDeepsetClient

* feat: add integration tools

* feat: add integration tool imports

* feat: add integration tools to registry

* feat: add integration protocol import to test conftest

* feat: add integrations method to BaseFakeClient

* feat: create integrations unit test package

* feat: add integration resource unit tests

* feat: add integration tools unit tests

* feat: add integration resource integration tests

* refactor: use Iterator type annotation instead of List

* refactor: improve type annotations and docstrings for IntegrationList

* chore: remove tools; fix tests, types

* chore: docs

Author: mathislucka

src/deepset_mcp/api/README.md

@@ -28,7 +28,7 @@ The client automatically handles authentication, request management, and connect
 
 ## Core Resources
 
-The SDK provides access to eight main resources, each designed for specific aspects of the deepset platform:
+The SDK provides access to nine main resources, each designed for specific aspects of the deepset platform:
 
 ### Pipelines
 
@@ -272,6 +272,29 @@ async with AsyncDeepsetClient() as client:
         print(f"Version: {installation.version}")
 ```
 
+### Integrations
+
+Manage external service integrations:
+
+```python
+from deepset_mcp.api.client import AsyncDeepsetClient
+from deepset_mcp.api.integrations.models import IntegrationProvider
+
+async with AsyncDeepsetClient() as client:
+    integrations = client.integrations()
+    
+    # List all integrations
+    integration_list = await integrations.list()
+    
+    for integration in integration_list.integrations:
+        print(f"Provider: {integration.provider}")
+        print(f"Domain: {integration.provider_domain}")
+        
+    # Get a specific integration by provider
+    openai_integration = await integrations.get(IntegrationProvider.OPENAI)
+    print(f"OpenAI Integration: {openai_integration.provider_domain}")
+```
+
 ### Secrets
 
 Manage secrets for secure configuration and sensitive data:
@@ -500,6 +523,7 @@ Main client class for API access.
 - `indexes(workspace: str)`: Returns IndexResource for the specified workspace
 - `pipeline_templates(workspace: str)`: Returns PipelineTemplateResource for the specified workspace
 - `custom_components(workspace: str)`: Returns CustomComponentsResource for the specified workspace
+- `integrations()`: Returns IntegrationResource
 - `haystack_service()`: Returns HaystackServiceResource
 - `secrets()`: Returns SecretResource
 - `users()`: Returns UserResource

src/deepset_mcp/api/client.py

@@ -7,6 +7,7 @@
 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.integrations.resource import IntegrationResource
 from deepset_mcp.api.pipeline.resource import PipelineResource
 from deepset_mcp.api.pipeline_template.resource import PipelineTemplateResource
 from deepset_mcp.api.protocols import AsyncClientProtocol
@@ -270,3 +271,7 @@ def secrets(self) -> SecretResource:
     def workspaces(self) -> WorkspaceResource:
         """Resource to interact with workspaces."""
         return WorkspaceResource(client=self)
+
+    def integrations(self) -> IntegrationResource:
+        """Resource to interact with integrations."""
+        return IntegrationResource(client=self)

src/deepset_mcp/api/integrations/__init__.py

@@ -0,0 +1 @@
+"""Integration API resources and models."""

src/deepset_mcp/api/integrations/models.py

@@ -0,0 +1,49 @@
+"""Models for the integrations API."""
+
+from enum import StrEnum
+from uuid import UUID
+
+from pydantic import BaseModel
+
+
+class IntegrationProvider(StrEnum):
+    """Supported integration providers."""
+
+    AWS_BEDROCK = "aws-bedrock"
+    AZURE_DOCUMENT_INTELLIGENCE = "azure-document-intelligence"
+    AZURE_OPENAI = "azure-openai"
+    COHERE = "cohere"
+    DEEPL = "deepl"
+    GOOGLE = "google"
+    HUGGINGFACE = "huggingface"
+    NVIDIA = "nvidia"
+    OPENAI = "openai"
+    SEARCHAPI = "searchapi"
+    SNOWFLAKE = "snowflake"
+    UNSTRUCTURED = "unstructured"
+    VOYAGE_AI = "voyage-ai"
+    WANDB_AI = "wandb-ai"
+    MONGODB = "mongodb"
+    TOGETHER_AI = "together-ai"
+
+
+class Integration(BaseModel):
+    """Model representing an integration."""
+
+    invalid: bool
+    model_registry_token_id: UUID
+    provider: IntegrationProvider
+    provider_domain: str
+
+
+class IntegrationList(BaseModel):
+    """Model representing a list of integrations."""
+
+    integrations: list[Integration]
+
+    def __len__(self) -> int:
+        """Return the length of the list.
+
+        :returns: Number of integrations.
+        """
+        return len(self.integrations)

src/deepset_mcp/api/integrations/protocols.py

@@ -0,0 +1,27 @@
+"""Protocol definitions for integrations resource."""
+
+from typing import TYPE_CHECKING, Protocol
+
+from deepset_mcp.api.integrations.models import Integration, IntegrationList, IntegrationProvider
+
+if TYPE_CHECKING:
+    pass
+
+
+class IntegrationResourceProtocol(Protocol):
+    """Protocol for integration resource operations."""
+
+    async def list(self) -> IntegrationList:
+        """Retrieve all integrations.
+
+        :returns: IntegrationList containing all available integrations.
+        """
+        ...
+
+    async def get(self, provider: IntegrationProvider) -> Integration:
+        """Retrieve a specific integration by provider.
+
+        :param provider: The integration provider to retrieve.
+        :returns: Integration instance for the specified provider.
+        """
+        ...

src/deepset_mcp/api/integrations/resource.py

@@ -0,0 +1,57 @@
+"""Resource implementation for integrations API."""
+
+import logging
+from typing import TYPE_CHECKING
+
+from deepset_mcp.api.integrations.models import Integration, IntegrationList, IntegrationProvider
+from deepset_mcp.api.integrations.protocols import IntegrationResourceProtocol
+from deepset_mcp.api.transport import raise_for_status
+
+logger = logging.getLogger(__name__)
+
+if TYPE_CHECKING:
+    from deepset_mcp.api.protocols import AsyncClientProtocol
+
+
+class IntegrationResource(IntegrationResourceProtocol):
+    """Manages interactions with the deepset integrations API."""
+
+    def __init__(self, client: "AsyncClientProtocol") -> None:
+        """Initialize an IntegrationResource instance.
+
+        :param client: The async client protocol instance.
+        """
+        self._client = client
+
+    async def list(self) -> IntegrationList:
+        """Retrieve all integrations.
+
+        :returns: IntegrationList containing all available integrations.
+        """
+        resp = await self._client.request(
+            endpoint="v1/model_registry_tokens",
+            method="GET",
+        )
+
+        raise_for_status(resp)
+
+        if resp.json is not None:
+            integrations = [Integration.model_validate(item) for item in resp.json]
+            return IntegrationList(integrations=integrations)
+        else:
+            return IntegrationList(integrations=[])
+
+    async def get(self, provider: IntegrationProvider) -> Integration:
+        """Retrieve a specific integration by provider.
+
+        :param provider: The integration provider to retrieve.
+        :returns: Integration instance for the specified provider.
+        """
+        resp = await self._client.request(
+            endpoint=f"v1/model_registry_tokens/{provider.value}",
+            method="GET",
+        )
+
+        raise_for_status(resp)
+
+        return Integration.model_validate(resp.json)

src/deepset_mcp/api/protocols.py

@@ -5,6 +5,7 @@
 from deepset_mcp.api.custom_components.protocols import CustomComponentsProtocol
 from deepset_mcp.api.haystack_service.protocols import HaystackServiceProtocol
 from deepset_mcp.api.indexes.protocols import IndexResourceProtocol
+from deepset_mcp.api.integrations.protocols import IntegrationResourceProtocol
 from deepset_mcp.api.pipeline.protocols import PipelineResourceProtocol
 from deepset_mcp.api.pipeline_template.protocols import PipelineTemplateResourceProtocol
 from deepset_mcp.api.secrets.protocols import SecretResourceProtocol
@@ -115,3 +116,7 @@ def secrets(self) -> "SecretResourceProtocol":
     def workspaces(self) -> "WorkspaceResourceProtocol":
         """Access workspaces."""
         ...
+
+    def integrations(self) -> "IntegrationResourceProtocol":
+        """Access integrations."""
+        ...

test/integration/test_integration_integrations_resource.py

@@ -0,0 +1,73 @@
+"""Integration tests for IntegrationResource."""
+
+import os
+
+import pytest
+
+from deepset_mcp.api.client import AsyncDeepsetClient
+from deepset_mcp.api.integrations.models import IntegrationProvider
+
+
+@pytest.mark.asyncio
+@pytest.mark.integration
+class TestIntegrationResourceIntegration:
+    """Integration tests for IntegrationResource.
+
+    These tests run against the actual deepset API and require:
+    - DEEPSET_API_KEY environment variable to be set
+    - Valid API access
+    """
+
+    @pytest.fixture(autouse=True)
+    def check_api_key(self) -> None:
+        """Ensure API key is available for integration tests."""
+        if not os.environ.get("DEEPSET_API_KEY"):
+            pytest.skip("DEEPSET_API_KEY not set, skipping integration tests")
+
+    async def test_list_integrations_real_api(self) -> None:
+        """Test listing integrations against real API."""
+        async with AsyncDeepsetClient() as client:
+            # Act
+            result = await client.integrations().list()
+
+            # Assert
+            # We can't assert specific content since it depends on the account configuration
+            # but we can verify the structure is correct
+            assert hasattr(result, "integrations")
+            assert isinstance(result.integrations, list)
+
+            # If there are integrations, verify their structure
+            for integration in result.integrations:
+                assert hasattr(integration, "invalid")
+                assert hasattr(integration, "model_registry_token_id")
+                assert hasattr(integration, "provider")
+                assert hasattr(integration, "provider_domain")
+                assert isinstance(integration.invalid, bool)
+                assert isinstance(integration.provider, IntegrationProvider)
+                assert isinstance(integration.provider_domain, str)
+
+    async def test_get_integration_real_api(self) -> None:
+        """Test getting a specific integration against real API.
+
+        This test attempts to get an AWS Bedrock integration.
+        If it doesn't exist, the test will expect a 404 error.
+        """
+        async with AsyncDeepsetClient() as client:
+            try:
+                # Act
+                result = await client.integrations().get(IntegrationProvider.AWS_BEDROCK)
+
+                # Assert - if we get a result, verify its structure
+                assert hasattr(result, "invalid")
+                assert hasattr(result, "model_registry_token_id")
+                assert hasattr(result, "provider")
+                assert hasattr(result, "provider_domain")
+                assert isinstance(result.invalid, bool)
+                assert result.provider == IntegrationProvider.AWS_BEDROCK
+                assert isinstance(result.provider_domain, str)
+
+            except Exception as e:
+                # If the integration doesn't exist, we expect a 404-like error
+                # The exact error type depends on the API implementation
+                # This is acceptable for integration tests
+                assert "404" in str(e) or "not found" in str(e).lower() or "Not Found" in str(e)

test/unit/api/integrations/__init__.py

@@ -0,0 +1 @@
+"""Unit tests for integrations API."""