Extend get_entities tool to support minimized context with detailed parameter (#43)

* Initial plan for issue

* Initial assessment: Plan to implement detailed parameter support for get_entities

Co-authored-by: Matanga1-2 <24847398+Matanga1-2@users.noreply.github.com>

* Implement detailed parameter support for get_entities tool

Co-authored-by: Matanga1-2 <24847398+Matanga1-2@users.noreply.github.com>

* debug logs

* Address reviewer feedback: change default detailed=False, remove redundant comments, upgrade to v0.2.17

Co-authored-by: Matanga1-2 <24847398+Matanga1-2@users.noreply.github.com>

* Work around PyPort bug by reverting to get_entities method with client-side filtering

Co-authored-by: Matanga1-2 <24847398+Matanga1-2@users.noreply.github.com>

* upgrade pyport

* Move business logic from client to tool layer and update detailed parameter description

Co-authored-by: Matanga1-2 <24847398+Matanga1-2@users.noreply.github.com>

* Implement search_entities API with query building in tool layer

Co-authored-by: Matanga1-2 <24847398+Matanga1-2@users.noreply.github.com>

* Remove comments in get_entities.py

Remove comments

* Fix failing tests by adding missing search_entities AsyncMock to test client

Co-authored-by: Matanga1-2 <24847398+Matanga1-2@users.noreply.github.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: Matanga1-2 <24847398+Matanga1-2@users.noreply.github.com>
Co-authored-by: Matanga1-2 <matangrady@gmail.com>

Author: Copilot

CHANGELOG.md

@@ -4,8 +4,19 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+=======
 
-## [0.2.16] - 2025-01-17
+## [0.2.17] - 2025-06-17
+
+### Added
+- Added `detailed` parameter support to `get_entities` tool for minimized context
+- Tool now returns only identifier and title when `detailed=False` for reduced context usage
+
+### Changed
+- Switched from `get_entities` to `search_blueprint_entities` API call for field filtering support
+- Upgrade Pyport pacackeg to 0.3.3.
+
+## [0.2.16] - 2025-06-17
 
 ### Added
 - Added custom User-Agent header to all HTTP requests sent via the MCP server

poetry.lock

@@ -1,6 +1,6 @@
 [project]
 name = "mcp-server-port"
-version = "0.2.16"
+version = "0.2.17"
 authors = [
   { name = "Matan Grady", email = "matan.grady@getport.io" }
 ]
@@ -11,7 +11,7 @@ dependencies = [
     "httpx>=0.28.1",
     "mcp[cli]>=1.6.0",
     "python-dotenv>=1.0.1",
-    "pyport (>=0.3.2,<=0.3.2)",
+    "pyport (>=0.3.3,<=0.3.3)",
     "loguru>=0.7.2",
     "pydantic (>=2.11.3,<3.0.0)"
 ]
@@ -32,7 +32,7 @@ include = [
 ]
 [tool.poetry]
 name = "mcp-server-port"
-version = "0.2.16"
+version = "0.2.17"
 description = "Port's MCP server"
 packages = [
     { include = "src" }

pyproject.toml

@@ -122,6 +122,9 @@ async def get_entity(self, blueprint_identifier: str, entity_identifier: str) ->
     async def get_entities(self, blueprint_identifier: str) -> list[EntityResult]:
         return await self.wrap_request(lambda: self.entities.get_entities(blueprint_identifier))
 
+    async def search_entities(self, blueprint_identifier: str, search_query: dict[str, Any]) -> list[EntityResult]:
+        return await self.wrap_request(lambda: self.entities.search_entities(blueprint_identifier, search_query))
+
     async def create_entity(
         self, blueprint_identifier: str, entity_data: dict[str, Any], query: dict[str, Any]
     ) -> EntityResult:

src/client/client.py

@@ -29,6 +29,21 @@ async def get_entities(self, blueprint_identifier: str) -> list[EntityResult]:
             logger.debug("Skipping API validation for entities")
             return [EntityResult.construct(**entity_data) for entity_data in entities_data]
 
+    async def search_entities(self, blueprint_identifier: str, search_query: dict[str, Any]) -> list[EntityResult]:
+        logger.info(f"Searching entities for blueprint '{blueprint_identifier}' from Port")
+        logger.debug(f"Search query: {search_query}")
+
+        entities_data = self._client.entities.search_blueprint_entities(blueprint_identifier, search_query)
+
+        logger.info(f"Got {len(entities_data)} entities for blueprint '{blueprint_identifier}' from Port")
+        logger.debug(f"Response for search entities: {entities_data}")
+        if config.api_validation_enabled:
+            logger.debug("Validating entities")
+            return [EntityResult(**entity_data) for entity_data in entities_data]
+        else:
+            logger.debug("Skipping API validation for entities")
+            return [EntityResult.construct(**entity_data) for entity_data in entities_data]
+
     async def get_entity(self, blueprint_identifier: str, entity_identifier: str) -> EntityResult:
         logger.info(f"Getting entity '{entity_identifier}' from blueprint '{blueprint_identifier}' from Port")
 

src/client/entities.py

@@ -13,7 +13,7 @@ class GetEntitiesToolSchema(BaseModel):
     blueprint_identifier: str = Field(..., description="The identifier of the blueprint to get entities for")
     detailed: bool = Field(
         default=False,
-        description="If True, returns complete entity details including properties. If False (default), returns summary information only.",
+        description="Controls whether to return extended entity information. If True, returns complete entity details including all properties. If False (default), returns only identifier and title to keep context minimal. Prefer False unless specifically asked for detailed information.",
     )
 
 
@@ -48,7 +48,18 @@ async def get_entities(self, props: GetEntitiesToolSchema) -> dict[str, Any]:
         if not blueprint_identifier:
             raise ValueError("Blueprint identifier is required")
 
-        raw_entities = await self.port_client.get_entities(blueprint_identifier)
+        detailed = args.get("detailed", False)
+        
+        search_query = {
+            "query": {
+                "$blueprint": {"=": blueprint_identifier}
+            }
+        }
+        
+        if not detailed:
+            search_query["include"] = ["$identifier", "$title"]
+
+        raw_entities = await self.port_client.search_entities(blueprint_identifier, search_query)
         processed_entities = [entity.model_dump(exclude_unset=True, exclude_none=True) for entity in raw_entities]
 
         response = GetEntitiesToolResponse.construct(entities=processed_entities)

src/tools/entity/get_entities.py

@@ -17,6 +17,7 @@ def mock_client():
 
     client.get_entity = AsyncMock()
     client.get_entities = AsyncMock()
+    client.search_entities = AsyncMock()
     client.create_entity = AsyncMock()
     client.update_entity = AsyncMock()
     client.delete_entity = AsyncMock()

tests/unit/tools/conftest.py

@@ -7,22 +7,56 @@
 @pytest.fixture
 def mock_client_with_entities(mock_client):
     """Add specific return values for this test"""
-    mock_client.get_entities.return_value = [EntityResult(identifier="test-entity", blueprint="test-blueprint")]
+    mock_client.search_entities.return_value = [EntityResult(identifier="test-entity", blueprint="test-blueprint")]
     return mock_client
 
 
 @pytest.mark.asyncio
-async def test_get_entities_tool(mock_client_with_entities):
-    """Test the GetEntitiesTool's metadata and function execution."""
-    # Create the tool
+async def test_get_entities_tool_detailed_true(mock_client_with_entities):
+    """Test the GetEntitiesTool's metadata and function execution with detailed=True."""
     tool = GetEntitiesTool(mock_client_with_entities)
 
-    # Test tool metadata
     assert tool.name == "get_entities"
     assert "entities" in tool.description.lower()
 
-    # Test function execution
     schema = {"blueprint_identifier": "test-blueprint", "detailed": True}
     result = await tool.get_entities(tool.validate_input(schema))
-    mock_client_with_entities.get_entities.assert_awaited_once_with("test-blueprint")
+    
+    # Verify search_entities was called with correct query (no include filter for detailed=True)
+    expected_query = {"query": {"$blueprint": {"=": "test-blueprint"}}}
+    mock_client_with_entities.search_entities.assert_awaited_once_with("test-blueprint", expected_query)
+    assert result is not None
+
+
+@pytest.mark.asyncio
+async def test_get_entities_tool_detailed_false(mock_client_with_entities):
+    """Test the GetEntitiesTool's function execution with detailed=False."""
+    tool = GetEntitiesTool(mock_client_with_entities)
+
+    schema = {"blueprint_identifier": "test-blueprint", "detailed": False}
+    result = await tool.get_entities(tool.validate_input(schema))
+    
+    # Verify search_entities was called with correct query (include filter for detailed=False)
+    expected_query = {
+        "query": {"$blueprint": {"=": "test-blueprint"}},
+        "include": ["$identifier", "$title"]
+    }
+    mock_client_with_entities.search_entities.assert_awaited_once_with("test-blueprint", expected_query)
+    assert result is not None
+
+
+@pytest.mark.asyncio
+async def test_get_entities_tool_default_detailed(mock_client_with_entities):
+    """Test the GetEntitiesTool's function execution with default detailed value."""
+    tool = GetEntitiesTool(mock_client_with_entities)
+
+    schema = {"blueprint_identifier": "test-blueprint"}
+    result = await tool.get_entities(tool.validate_input(schema))
+    
+    # Verify search_entities was called with correct query (include filter for default detailed=False)
+    expected_query = {
+        "query": {"$blueprint": {"=": "test-blueprint"}},
+        "include": ["$identifier", "$title"]
+    }
+    mock_client_with_entities.search_entities.assert_awaited_once_with("test-blueprint", expected_query)
     assert result is not None