Merge pull request #45 from netboxlabs/support_brief

feat(tools): add support for brief to netbox_get_objects and netbox_get_object_by_id

Author: ltucker

server.py

@@ -269,6 +269,7 @@ def netbox_get_objects(
     object_type: str,
     filters: dict,
     fields: list[str] | None = None,
+    brief: bool = False,
     limit: Annotated[int, Field(default=5, ge=1, le=100)] = 5,
     offset: Annotated[int, Field(default=0, ge=0)] = 0,
     ordering: str | list[str] | None = None,
@@ -307,6 +308,9 @@ def netbox_get_objects(
                 Uses NetBox's native field filtering via ?fields= parameter.
                 **Always specify only the fields you actually need.**
 
+        brief: returns only a minimal representation of each object in the response.
+               This is useful when you need only a list of available objects without any related data.
+
         limit: Maximum results to return (default 5, max 100)
                Start with default, increase only if needed
 
@@ -444,6 +448,9 @@ def netbox_get_objects(
     if fields:
         params["fields"] = ",".join(fields)
 
+    if brief:
+        params["brief"] = "1"
+
     if ordering:
         if isinstance(ordering, list):
             ordering = ",".join(ordering)
@@ -456,7 +463,7 @@ def netbox_get_objects(
 
 @mcp.tool
 def netbox_get_object_by_id(
-    object_type: str, object_id: int, fields: list[str] | None = None
+    object_type: str, object_id: int, fields: list[str] | None = None, brief: bool = False
 ):
     """
     Get detailed information about a specific NetBox object by its ID.
@@ -478,6 +485,8 @@ def netbox_get_object_by_id(
 
                 Uses NetBox's native field filtering via ?fields= parameter.
                 **Always specify only the fields you actually need.**
+        brief: returns only a minimal representation of the object in the response.
+               This is useful when you need only a summary of the object without any related data.
 
     Returns:
         Object dict (complete or with only requested fields based on fields parameter)
@@ -494,6 +503,9 @@ def netbox_get_object_by_id(
     if fields:
         params["fields"] = ",".join(fields)
 
+    if brief:
+        params["brief"] = "1"
+
     return netbox.get(endpoint, params=params)
 
 

tests/test_brief.py

@@ -0,0 +1,87 @@
+"""Tests for brief parameter validation and behavior."""
+
+from unittest.mock import patch
+
+from server import netbox_get_object_by_id, netbox_get_objects
+
+
+@patch("server.netbox")
+def test_brief_false_omits_parameter_get_objects(mock_netbox):
+    """When brief=False (default), should not include brief in API params for netbox_get_objects."""
+    mock_netbox.get.return_value = {"count": 0, "results": [], "next": None, "previous": None}
+
+    netbox_get_objects.fn(object_type="sites", filters={}, brief=False)
+
+    call_args = mock_netbox.get.call_args
+    params = call_args[1]["params"]
+
+    # brief should not be in params when False
+    assert "brief" not in params
+
+
+@patch("server.netbox")
+def test_brief_default_omits_parameter_get_objects(mock_netbox):
+    """When brief not specified (uses default False), should not include brief in API params."""
+    mock_netbox.get.return_value = {"count": 0, "results": [], "next": None, "previous": None}
+
+    netbox_get_objects.fn(object_type="sites", filters={})
+
+    call_args = mock_netbox.get.call_args
+    params = call_args[1]["params"]
+
+    # brief should not be in params when using default
+    assert "brief" not in params
+
+
+@patch("server.netbox")
+def test_brief_true_includes_parameter_get_objects(mock_netbox):
+    """When brief=True, should pass 'brief': '1' to API params for netbox_get_objects."""
+    mock_netbox.get.return_value = {"count": 0, "results": [], "next": None, "previous": None}
+
+    netbox_get_objects.fn(object_type="sites", filters={}, brief=True)
+
+    call_args = mock_netbox.get.call_args
+    params = call_args[1]["params"]
+
+    assert params["brief"] == "1"
+
+
+@patch("server.netbox")
+def test_brief_false_omits_parameter_get_by_id(mock_netbox):
+    """When brief=False (default), should not include brief in API params for netbox_get_object_by_id."""
+    mock_netbox.get.return_value = {"id": 1, "name": "Test Site"}
+
+    netbox_get_object_by_id.fn(object_type="sites", object_id=1, brief=False)
+
+    call_args = mock_netbox.get.call_args
+    params = call_args[1]["params"]
+
+    # brief should not be in params when False
+    assert "brief" not in params
+
+
+@patch("server.netbox")
+def test_brief_default_omits_parameter_get_by_id(mock_netbox):
+    """When brief not specified (uses default False), should not include brief in API params."""
+    mock_netbox.get.return_value = {"id": 1, "name": "Test Site"}
+
+    netbox_get_object_by_id.fn(object_type="sites", object_id=1)
+
+    call_args = mock_netbox.get.call_args
+    params = call_args[1]["params"]
+
+    # brief should not be in params when using default
+    assert "brief" not in params
+
+
+@patch("server.netbox")
+def test_brief_true_includes_parameter_get_by_id(mock_netbox):
+    """When brief=True, should pass 'brief': '1' to API params for netbox_get_object_by_id."""
+    mock_netbox.get.return_value = {"id": 1, "url": "http://example.com/api/dcim/sites/1/"}
+
+    netbox_get_object_by_id.fn(object_type="sites", object_id=1, brief=True)
+
+    call_args = mock_netbox.get.call_args
+    params = call_args[1]["params"]
+
+    assert params["brief"] == "1"