feat: add IndexResource for listing and retrieving indexes (#39)

* feat: create indexes package

* feat: add Index models

* feat: add IndexResource

* feat: import index models in protocols

* feat: add indexes method to AsyncClientProtocol

* feat: add IndexResourceProtocol

* feat: import IndexResource in client

* feat: add indexes method to AsyncDeepsetClient

* test: add IndexResource tests

* test: add IndexResource integration tests

* fix: tests, linting, types

Author: mathislucka

src/deepset_mcp/api/client.py

@@ -3,6 +3,7 @@
 from typing import Any, Self, TypeVar, overload
 
 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
@@ -134,3 +135,7 @@ def haystack_service(self) -> HaystackServiceResource:
     def pipeline_templates(self, workspace: str) -> PipelineTemplateResource:
         """Resource to interact with pipeline templates in the specified workspace."""
         return PipelineTemplateResource(client=self, workspace=workspace)
+
+    def indexes(self, workspace: str) -> IndexResource:
+        """Resource to interact with indexes in the specified workspace."""
+        return IndexResource(client=self, workspace=workspace)

src/deepset_mcp/api/indexes/__init__.py

@@ -0,0 +1,44 @@
+from datetime import datetime
+from typing import Any
+
+from pydantic import BaseModel
+
+from deepset_mcp.api.shared_models import DeepsetUser
+
+
+class IndexStatus(BaseModel):
+    """Status information about documents in an index."""
+
+    pending_file_count: int
+    failed_file_count: int
+    indexed_no_documents_file_count: int
+    indexed_file_count: int
+    total_file_count: int
+
+
+class Index(BaseModel):
+    """A deepset index."""
+
+    pipeline_index_id: str
+    name: str
+    description: str | None = None
+    config_yaml: str
+    workspace_id: str
+    settings: dict[str, Any]
+    desired_status: str
+    deployed_at: datetime | None = None
+    last_edited_at: datetime | None = None
+    max_index_replica_count: int
+    created_at: datetime
+    updated_at: datetime | None = None
+    created_by: DeepsetUser
+    last_edited_by: DeepsetUser | None = None
+    status: IndexStatus
+
+
+class IndexList(BaseModel):
+    """Response model for listing indexes."""
+
+    data: list[Index]
+    has_more: bool
+    total: int

src/deepset_mcp/api/indexes/models.py

@@ -0,0 +1,48 @@
+from deepset_mcp.api.indexes.models import Index, IndexList
+from deepset_mcp.api.protocols import AsyncClientProtocol
+from deepset_mcp.api.transport import raise_for_status
+
+
+class IndexResource:
+    """Resource for interacting with deepset indexes."""
+
+    def __init__(self, client: AsyncClientProtocol, workspace: str) -> None:
+        """Initialize the index resource.
+
+        :param client: The async REST client.
+        :param workspace: The workspace to use.
+        """
+        self._client = client
+        self._workspace = workspace
+
+    async def list(self, limit: int = 10, page_number: int = 1) -> IndexList:
+        """List all indexes.
+
+        :param limit: Maximum number of indexes to return.
+        :param page_number: Page number for pagination.
+
+        :returns: List of indexes.
+        """
+        params = {
+            "limit": limit,
+            "page_number": page_number,
+        }
+
+        response = await self._client.request(f"/api/v1/workspaces/{self._workspace}/indexes", params=params)
+
+        raise_for_status(response)
+
+        return IndexList.model_validate(response.json)
+
+    async def get(self, index_name: str) -> Index:
+        """Get a specific index.
+
+        :param index_name: Name of the index.
+
+        :returns: Index details.
+        """
+        response = await self._client.request(f"/api/v1/workspaces/{self._workspace}/indexes/{index_name}")
+
+        raise_for_status(response)
+
+        return Index.model_validate(response.json)

src/deepset_mcp/api/indexes/resource.py

@@ -3,6 +3,8 @@
 
 from pydantic import BaseModel, Field
 
+from deepset_mcp.api.shared_models import DeepsetUser
+
 
 class PipelineServiceLevel(StrEnum):
     """Describes the service level of a pipeline."""
@@ -12,15 +14,6 @@ class PipelineServiceLevel(StrEnum):
     DRAFT = "DRAFT"
 
 
-class DeepsetUser(BaseModel):
-    """Model representing a user on the deepset platform."""
-
-    id: str = Field(alias="user_id")
-    given_name: str | None = None
-    family_name: str | None = None
-    email: str | None = None
-
-
 class DeepsetPipeline(BaseModel):
     """Model representing a pipeline on the deepset platform."""
 

src/deepset_mcp/api/pipeline/models.py

@@ -1,6 +1,7 @@
 from types import TracebackType
 from typing import Any, Protocol, Self, TypeVar, overload
 
+from deepset_mcp.api.indexes.models import Index, IndexList
 from deepset_mcp.api.pipeline.models import DeepsetPipeline, NoContentResponse, PipelineValidationResult
 from deepset_mcp.api.pipeline_template.models import PipelineTemplate
 from deepset_mcp.api.transport import TransportResponse
@@ -87,6 +88,22 @@ def pipeline_templates(self, workspace: str) -> "PipelineTemplateResourceProtoco
         """Access pipeline templates in the specified workspace."""
         ...
 
+    def indexes(self, workspace: str) -> "IndexResourceProtocol":
+        """Access indexes in the specified workspace."""
+        ...
+
+
+class IndexResourceProtocol(Protocol):
+    """Protocol defining the implementation for IndexResource."""
+
+    async def list(self, limit: int = 10, page_number: int = 1) -> IndexList:
+        """List indexes in the configured workspace."""
+        ...
+
+    async def get(self, index_name: str) -> Index:
+        """Fetch a single index by its name."""
+        ...
+
 
 class PipelineTemplateResourceProtocol(Protocol):
     """Protocol defining the implementation for PipelineTemplateResource."""

src/deepset_mcp/api/protocols.py

@@ -0,0 +1,10 @@
+from pydantic import BaseModel, Field
+
+
+class DeepsetUser(BaseModel):
+    """Model representing a user on the deepset platform."""
+
+    id: str = Field(alias="user_id")
+    given_name: str | None = None
+    family_name: str | None = None
+    email: str | None = None

src/deepset_mcp/api/shared_models.py

@@ -0,0 +1,149 @@
+import json
+from typing import Any
+
+import pytest
+
+from deepset_mcp.api.exceptions import ResourceNotFoundError, UnexpectedAPIError
+from deepset_mcp.api.indexes.models import Index, IndexList
+from deepset_mcp.api.indexes.resource import IndexResource
+from deepset_mcp.api.transport import TransportResponse
+from test.unit.conftest import BaseFakeClient
+
+
+@pytest.fixture()
+def fake_client() -> BaseFakeClient:
+    return BaseFakeClient()
+
+
+@pytest.fixture
+def index_response() -> dict[str, Any]:
+    """Sample response for an index."""
+    return {
+        "pipeline_index_id": "my-id",
+        "name": "test-index",
+        "description": None,
+        "config_yaml": "yaml: content",
+        "workspace_id": "my-workspace",
+        "settings": {},
+        "desired_status": "DEPLOYED",
+        "deployed_at": "2025-01-01T00:00:00Z",
+        "last_edited_at": "2025-01-01T00:00:00Z",
+        "max_index_replica_count": 10,
+        "created_at": "2025-01-01T00:00:00Z",
+        "updated_at": "2025-01-01T00:00:00Z",
+        "created_by": {"given_name": "Test", "family_name": "User", "user_id": "test-id"},
+        "last_edited_by": {"given_name": "Test", "family_name": "User", "user_id": "test-id"},
+        "status": {
+            "pending_file_count": 0,
+            "failed_file_count": 0,
+            "indexed_no_documents_file_count": 0,
+            "indexed_file_count": 0,
+            "total_file_count": 0,
+        },
+    }
+
+
+@pytest.fixture
+def index_list_response(index_response: dict[str, Any]) -> dict[str, Any]:
+    """Sample response for listing indexes."""
+    return {"data": [index_response], "has_more": False, "total": 1}
+
+
+@pytest.fixture
+def workspace() -> str:
+    """Sample workspace ID."""
+    return "test-workspace"
+
+
+@pytest.fixture()
+def fake_list_successful_response(
+    fake_client: BaseFakeClient, index_list_response: dict[str, Any], workspace: str
+) -> None:
+    """Configure the fake client to return a successful response."""
+    fake_client.responses[f"/api/v1/workspaces/{workspace}/indexes"] = TransportResponse(
+        status_code=200,
+        json=index_list_response,
+        text=json.dumps(index_list_response),
+    )
+
+
+@pytest.fixture()
+def fake_get_successful_response(fake_client: BaseFakeClient, index_response: dict[str, Any], workspace: str) -> None:
+    """Configure the fake client to return a successful response."""
+    fake_client.responses[f"/api/v1/workspaces/{workspace}/indexes/test-index"] = TransportResponse(
+        status_code=200,
+        json=index_response,
+        text=json.dumps(index_response),
+    )
+
+
+@pytest.fixture()
+def fake_get_404_response(fake_client: BaseFakeClient, workspace: str) -> None:
+    """Configure fake client to return a 404 response."""
+    fake_client.responses[f"/api/v1/workspaces/{workspace}/indexes/nonexistent-index"] = TransportResponse(
+        status_code=404,
+        json={"detail": "Resource not found"},
+        text=json.dumps({"detail": "Resource not found"}),
+    )
+
+
+@pytest.fixture()
+def fake_get_500_response(fake_client: BaseFakeClient, workspace: str) -> None:
+    """Configure fake client to return a 500 response."""
+    fake_client.responses[f"/api/v1/workspaces/{workspace}/indexes/server-error-index"] = TransportResponse(
+        status_code=500,
+        json={"detail": "Internal server error"},
+        text=json.dumps({"detail": "Internal server error"}),
+    )
+
+
+class TestIndexResource:
+    """Test the IndexResource."""
+
+    async def test_get_index_returns_index(
+        self, fake_client: BaseFakeClient, workspace: str, fake_get_successful_response: None
+    ) -> None:
+        """Test that getting an index returns an Index instance."""
+        resource = IndexResource(fake_client, workspace)
+        result = await resource.get("test-index")
+        assert isinstance(result, Index)
+        assert result.name == "test-index"
+
+    async def test_list_indexes_returns_list(
+        self, fake_client: BaseFakeClient, workspace: str, fake_list_successful_response: None
+    ) -> None:
+        """Test that listing indexes returns an IndexList instance."""
+        resource = IndexResource(fake_client, workspace)
+        result = await resource.list()
+        assert isinstance(result, IndexList)
+        assert len(result.data) == 1
+        assert isinstance(result.data[0], Index)
+        assert result.total == 1
+        assert result.has_more is False
+
+    async def test_get_nonexistent_index_raises_404(
+        self, fake_client: BaseFakeClient, workspace: str, fake_get_404_response: None
+    ) -> None:
+        """Test that getting a nonexistent index raises ResourceNotFoundError."""
+        resource = IndexResource(fake_client, workspace)
+        with pytest.raises(ResourceNotFoundError):
+            await resource.get("nonexistent-index")
+
+    async def test_get_server_error_raises_500(
+        self, fake_client: BaseFakeClient, workspace: str, fake_get_500_response: None
+    ) -> None:
+        """Test that server error raises UnexpectedAPIError."""
+        resource = IndexResource(fake_client, workspace)
+        with pytest.raises(UnexpectedAPIError):
+            await resource.get("server-error-index")
+
+    async def test_list_indexes_passes_params(
+        self, fake_client: BaseFakeClient, workspace: str, fake_list_successful_response: None
+    ) -> None:
+        """Test that parameters are passed to the client in list method."""
+        resource = IndexResource(fake_client, workspace)
+        await resource.list(limit=20, page_number=2)
+
+        # Check the last request's parameters
+        last_request = fake_client.requests[-1]
+        assert last_request["params"] == {"limit": 20, "page_number": 2}

test/unit/api/indexes/__init__.py

@@ -5,6 +5,7 @@
 from deepset_mcp.api.protocols import (
     AsyncClientProtocol,
     HaystackServiceProtocol,
+    IndexResourceProtocol,
     PipelineResourceProtocol,
     PipelineTemplateResourceProtocol,
 )
@@ -140,3 +141,7 @@ def haystack_service(self) -> HaystackServiceProtocol:
     def pipeline_templates(self, workspace: str) -> PipelineTemplateResourceProtocol:
         """Overwrite this method when testing PipelineTemplateResource."""
         raise NotImplementedError
+
+    def indexes(self, workspace: str) -> IndexResourceProtocol:
+        """Overwrite this method when testing IndexResource."""
+        raise NotImplementedError