django-smartbase-admin 2.3.2__tar.gz → 2.3.3__tar.gz

{django_smartbase_admin-2.3.2 → django_smartbase_admin-2.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: django-smartbase-admin
-Version: 2.3.2
+Version: 2.3.3
 Summary: 
 Home-page: https://smartbase-sk.github.io/django-smartbase-admin-docs/
 License: MIT

{django_smartbase_admin-2.3.2 → django_smartbase_admin-2.3.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "django-smartbase-admin"
-version = "2.3.2"
+version = "2.3.3"
 description = ""
 authors = ["SmartBase <info@smartbase.sk>"]
 readme = "README.md"

{django_smartbase_admin-2.3.2 → django_smartbase_admin-2.3.3}/src/django_smartbase_admin/mcp/instructions.py

@@ -13,6 +13,10 @@ allowed to.
 What you can do:
 * Discover the available admin views and, per view, their columns, filters,
   detail fields, inlines, filter presets, and actions (``list_admins``).
+  Scope it: start with ``list_admins(detail="index")`` for the list of
+  ``view_id``s, then ``list_admins(view_id="...")`` for that one view in full.
+  Reading every view in full can exceed your result budget, and post-filtering
+  an oversized payload silently drops keys you need — ``mcp_actions`` first.
 * Browse: filter (text, choice, boolean, number range, date range,
   related-record), full-text search, sort, and paginate (``list_rows``).
 * Apply a named or saved filter preset and replay it (``fetch_filter_preset``).
@@ -30,14 +34,17 @@ What you can do:
 * Run actions on a row, a detail page, the whole list, a selection, or an
   inline row (``invoke_*_action``); inspect a modal action's form first with
   ``fetch_action_form``. Object-only fieldset actions are discovered from
-  ``fetch_detail.detail_actions``. Submit forms and formsets through
-  ``component_values`` using the names returned under ``components``.
+  ``fetch_detail.detail_actions``, and actions with no UI button from
+  ``mcp_actions`` (on ``fetch_detail`` or ``list_admins``) — those are run with
+  ``invoke_action``. Submit forms and formsets through ``component_values``
+  using the names returned under ``components``.
 * Export a list or selection to a file.
 
 Safety: deletes and impactful actions return ``needs_confirmation`` with a
 preview first; re-call with ``confirmed=True`` to commit.
 
-Workflow: ``list_admins`` (discover ``view_id``, columns, filters, inlines) →
+Workflow: ``list_admins(detail="index")`` (find the ``view_id``) →
+``list_admins(view_id=...)`` (its columns, filters, inlines, actions) →
 ``list_rows`` / ``fetch_detail`` / ``fetch_add_form`` → ``autocomplete`` for
 labels → ``create_object`` or ``update_detail``.
 

{django_smartbase_admin-2.3.2 → django_smartbase_admin-2.3.3}/src/django_smartbase_admin/mcp/mcp.py

@@ -16,6 +16,7 @@ whoever ``DJANGO_MCP_AUTHENTICATION_CLASSES`` resolved.
 from __future__ import annotations
 
 import json
+from typing import Literal
 
 from django.core.exceptions import PermissionDenied
 from django.http import Http404
@@ -46,6 +47,7 @@ from django_smartbase_admin.engine.const import (
 from django_smartbase_admin.mcp.actions import (
     SBAdminMCPActionFormService,
     SBAdminMCPActionInvokeService,
+    collect_mcp_method_action_entries,
 )
 from django_smartbase_admin.mcp.service import SBAdminMCPDetailService
 from django_smartbase_admin.mcp.bridge import (
@@ -60,6 +62,7 @@ from django_smartbase_admin.mcp.resolvers import resolve_admin
 from django_smartbase_admin.mcp.actions import ACTION_INVOKERS
 from django_smartbase_admin.mcp.schema import (
     admin_entry,
+    admin_index_entry,
     detail_action_entries,
     get_widget_shapes,
 )
@@ -336,13 +339,43 @@ class SBAdminTools(MCPToolset):
     """
 
     @_guarded_tool_call
-    def list_admins(self) -> dict[str, list[dict] | dict[str, dict] | dict[str, str]]:
+    def list_admins(
+        self,
+        view_id: str | None = None,
+        detail: Literal["index", "full"] = "full",
+    ) -> dict[str, list[dict] | dict[str, dict] | dict[str, str]]:
         """List the admins the current user can view.
 
         Use this to discover the handles every other tool accepts —
         ``view_id``, field/filter names, ``widget_id``s, inline names,
         and ``action_id``s.
 
+        Scope the response instead of reading every admin in full. A
+        deployment with dozens of admins returns tens of thousands of
+        characters, which can exceed a caller's result budget and force
+        lossy post-filtering — projecting away keys that turn out to
+        matter. Prefer two cheap calls:
+
+          1. ``list_admins(detail="index")`` — ``view_id``, model and
+             display names for every visible admin, and nothing else.
+             Enough to choose the target.
+          2. ``list_admins(view_id="<chosen>")`` — that one admin's
+             complete record, typically an order of magnitude smaller
+             than the unscoped call.
+
+        Args:
+          view_id: return only this admin (still subject to view
+            permission). ``None`` returns every visible admin. An
+            unknown or invisible ``view_id`` raises ``LookupError``
+            rather than returning an empty list, so a typo is not
+            mistaken for "no such data".
+          detail: ``"full"`` (default) returns the schema documented
+            below; ``"index"`` returns only ``view_id``, ``app_label``,
+            ``model``, ``verbose_name``, ``verbose_name_plural`` and
+            ``description`` per admin. The ``widget_shapes`` and
+            ``action_invokers`` legends are omitted in ``"index"`` mode,
+            since the keys they explain are not returned.
+
         Returns ``{"admin_views": [...], "widget_shapes": {...}}``.
         ``widget_shapes`` is a legend keyed by widget category (the
         ``widget`` value on every filter entry); each value is
@@ -390,25 +423,51 @@ class SBAdminTools(MCPToolset):
           - ``selection_actions``: bulk buttons over selected rows.
 
         Methods explicitly decorated with ``mcp_components=...`` are reported
-        separately under ``mcp_actions``. Their request-aware ``components`` use
-        the same representation as admin and modal forms.
+        separately under ``mcp_actions`` — an action listed there and nowhere
+        else has no UI counterpart and is invoked with ``invoke_action``. This
+        is the key most easily lost to post-filtering, which is what the
+        ``view_id`` / ``detail`` scoping above exists to avoid.
 
         When configured by the host project, the top-level ``whoami`` entry
         points at the current user's profile target: ``{"view_id", "object_id"}``.
         """
         request = self.request
         ensure_sbadmin_request_data(request)
+        if detail not in ("index", "full"):
+            raise ValueError(f"detail must be 'index' or 'full', got {detail!r}.")
+
+        # Resolved against the same registry the unscoped call iterates, so
+        # scoping can only ever narrow that set — never reach a widget or
+        # inline view_id that ``admin_entry`` cannot describe.
+        candidates = [
+            admin
+            for admin in sb_admin_site._registry.values()
+            if isinstance(admin, SBAdminBaseListView)
+        ]
+        if view_id:
+            candidates = [admin for admin in candidates if admin.get_id() == view_id]
+            if not candidates:
+                # Fail loudly: an empty ``admin_views`` would read as "no such
+                # data" rather than "no such handle".
+                raise LookupError(
+                    f"No SBAdmin view registered with view_id={view_id!r}."
+                )
 
         admins: list[dict] = []
-        for admin in sb_admin_site._registry.values():
-            if not isinstance(admin, SBAdminBaseListView):
-                continue
+        for admin in candidates:
             try:
                 if not admin.has_view_permission(request):
                     continue
             except Exception:
                 continue  # one broken admin shouldn't break discovery
-            admins.append(admin_entry(admin, request))
+            admins.append(
+                admin_index_entry(admin)
+                if detail == "index"
+                else admin_entry(admin, request)
+            )
+
+        if view_id and not admins:
+            raise PermissionError(f"User has no view permission on admin {view_id!r}.")
 
         admins.sort(key=lambda entry: entry["view_id"])
         # ``widget_shapes`` is the legend keyed by the ``widget`` field
@@ -419,11 +478,15 @@ class SBAdminTools(MCPToolset):
         # ``action_invokers`` is a sibling legend to ``widget_shapes`` —
         # keyed by action-list name, value is the MCP tool to call.
         # Saves repeating ``invoke_with`` on every individual action.
-        result = {
-            "admin_views": admins,
-            "widget_shapes": get_widget_shapes(),
-            "action_invokers": ACTION_INVOKERS,
-        }
+        # Both are dropped from an index response: they explain filter and
+        # action keys an index entry doesn't carry, so they would be the
+        # bulk of a payload whose whole point is to be cheap.
+        result = {"admin_views": admins}
+        if detail == "full":
+            result |= {
+                "widget_shapes": get_widget_shapes(),
+                "action_invokers": ACTION_INVOKERS,
+            }
         try:
             whoami = request.request_data.configuration.get_whoami_target(request)
         except LookupError:
@@ -767,6 +830,13 @@ class SBAdminTools(MCPToolset):
             actions = detail_action_entries(admin, request, object_id=object_id)
             if actions:
                 result["detail_actions"] = actions
+            # An ``mcp_components`` method has no UI button, so it appears in
+            # no action list — without this it would be discoverable only
+            # inside a full ``list_admins``, the one call large deployments
+            # cannot afford to read whole.
+            mcp_actions = collect_mcp_method_action_entries(admin, request)
+            if mcp_actions:
+                result["mcp_actions"] = mcp_actions
             return result
         except PermissionDenied as exc:
             message = str(exc).strip() or (
@@ -832,6 +902,12 @@ class SBAdminTools(MCPToolset):
         object, including actions declared on object-dependent fieldsets.
         Invoke them with ``invoke_detail_action``.
 
+        ``mcp_actions`` contains this admin's methods exposed through
+        ``mcp_components`` — operations with no UI button, which therefore
+        appear in no other action list. Invoke them with ``invoke_action``,
+        passing this ``object_id``. Read them here rather than hunting for
+        them in a full ``list_admins``.
+
         ``widgets`` contains detail/dashboard widgets rendered in the
         detail fieldsets. Use each widget's ``data_tool`` to choose the
         next MCP call: ``list_rows`` with the widget ``view_id`` and

{django_smartbase_admin-2.3.2 → django_smartbase_admin-2.3.3}/src/django_smartbase_admin/mcp/schema.py

@@ -421,6 +421,26 @@ def _filter_preset_entries(admin, request) -> list[dict]:
     return entries
 
 
+def admin_index_entry(admin) -> dict:
+    """Identity-only schema entry: enough to pick an admin, nothing more.
+
+    Deliberately request-free — no field, filter, inline, preset or action
+    resolution runs — so indexing every admin in a large deployment stays
+    cheap. Follow up with ``admin_entry`` for the one that was chosen.
+    """
+    opts = admin.model._meta
+    entry: dict = {
+        "view_id": admin.get_id(),
+        "app_label": opts.app_label,
+        "model": opts.object_name,
+        "verbose_name": str(opts.verbose_name),
+        "verbose_name_plural": str(opts.verbose_name_plural),
+    }
+    if admin.mcp_description:
+        entry["description"] = str(admin.mcp_description)
+    return entry
+
+
 def admin_entry(admin, request) -> dict:
     """Schema entry for one registered SBAdmin admin."""
     model = admin.model

{django_smartbase_admin-2.3.2 → django_smartbase_admin-2.3.3}/src/django_smartbase_admin/mcp/tests/test_fetch_detail.py

@@ -721,3 +721,72 @@ class FetchDetailHtmlSanitizeTests(_FetchDetailTestBase):
         self.assertNotIn(".wrap{color:red}", value)
         self.assertNotIn("<script", value)
         self.assertNotIn("<style", value)
+
+
+class FolderMcpOnlyActionAdmin(FolderDetailTestAdmin):
+    """Admin whose only extra operation is MCP-exposed with no UI button."""
+
+    class RenameForm(forms.Form):
+        new_name = forms.CharField()
+
+    def get_rename_components(self, request):
+        return {"main": self.RenameForm()}
+
+    @sbadmin_action(
+        mcp_components="get_rename_components",
+        mcp_description="Rename the folder.",
+    )
+    def rename_folder(self, request, modifier, object_id=None):
+        return JsonResponse({"ok": True})
+
+
+@override_settings(
+    ROOT_URLCONF=__name__,
+    SB_ADMIN_CONFIGURATION="tests.sbadmin_config.MCPSBAdminConfiguration",
+)
+class FetchDetailMcpActionsTests(_FetchDetailTestBase):
+    """An ``mcp_components`` method on the admin itself has no UI button, so it
+    is in no action list — ``fetch_detail`` must carry it, otherwise a full
+    ``list_admins`` is the only way to find it."""
+
+    admin_class = FolderMcpOnlyActionAdmin
+
+    @classmethod
+    def setUpTestData(cls):
+        cls.folder = Folder.objects.create(name="target")
+
+    def test_admin_mcp_actions_surface_on_detail(self):
+        result = self._fetch(self.folder.pk)
+
+        entries = {entry["action_id"]: entry for entry in result["mcp_actions"]}
+        self.assertIn("rename_folder", entries)
+        entry = entries["rename_folder"]
+        self.assertEqual(entry["kind"], "method")
+        self.assertEqual(entry["description"], "Rename the folder.")
+        # The invocation contract ships with the discovery entry.
+        self.assertEqual(list(entry["components"]["main"]["fields"]), ["new_name"])
+
+    def test_mcp_only_action_is_in_no_ui_action_list(self):
+        result = self._fetch(self.folder.pk)
+
+        listed = {entry["action_id"] for entry in result.get("detail_actions", [])}
+        self.assertNotIn("rename_folder", listed)
+
+    def test_key_is_absent_when_the_admin_declares_none(self):
+        sb_admin_site._registry.pop(Folder, None)
+        sb_admin_site.register(Folder, FolderDetailTestAdmin)
+        MCPToolTestConfig().init_view_map()
+
+        self.assertNotIn("mcp_actions", self._fetch(self.folder.pk))
+
+    def test_detail_entry_matches_list_admins(self):
+        """The cheap route must report the same action as the expensive one."""
+        user = MagicMock(is_authenticated=True, is_superuser=True)
+        tools = SBAdminTools(request=build_mcp_request(user))
+        from_list = next(
+            e
+            for e in tools.list_admins(view_id="filer_folder")["admin_views"]
+            if e["view_id"] == "filer_folder"
+        )["mcp_actions"]
+
+        self.assertEqual(self._fetch(self.folder.pk)["mcp_actions"], from_list)

{django_smartbase_admin-2.3.2 → django_smartbase_admin-2.3.3}/src/django_smartbase_admin/mcp/tests/test_list_admins.py

@@ -412,3 +412,150 @@ class ListAdminsTests(TestCase):
             "DynamicPermissionInline",
             {inline["inline_name"] for inline in entry["inlines"]},
         )
+
+
+@override_settings(ROOT_URLCONF=__name__)
+class ListAdminsScopingTests(TestCase):
+    """``view_id`` / ``detail`` scoping — the escape from reading every admin
+    in full, which on a large deployment overflows a caller's result budget
+    and pushes it into lossy post-filtering."""
+
+    def setUp(self):
+        super().setUp()
+        self._original_admin = sb_admin_site._registry.pop(Folder, None)
+        sb_admin_site.register(Folder, FolderRichListAdminsTestAdmin)
+        MCPToolTestConfig.view_permission_for = None
+        MCPToolTestConfig().mcp_whoami_sbadmin = None
+
+    def tearDown(self):
+        MCPToolTestConfig.view_permission_for = None
+        MCPToolTestConfig().mcp_whoami_sbadmin = None
+        sb_admin_site._registry.pop(Folder, None)
+        if self._original_admin is not None:
+            sb_admin_site._registry[Folder] = self._original_admin
+        super().tearDown()
+
+    @staticmethod
+    def _tools():
+        user = MagicMock(is_authenticated=True, is_superuser=True)
+        return SBAdminTools(request=build_mcp_request(user))
+
+    def test_default_call_is_unchanged(self):
+        """No arguments must behave exactly as before the scoping was added."""
+        result = self._tools().list_admins()
+
+        self.assertIn("widget_shapes", result)
+        self.assertIn("action_invokers", result)
+        entry = next(e for e in result["admin_views"] if e["view_id"] == "filer_folder")
+        self.assertIn("fields", entry)
+        self.assertIn("detail_fields", entry)
+        self.assertGreater(len(result["admin_views"]), 1)
+
+    def test_view_id_returns_only_that_admin_in_full(self):
+        result = self._tools().list_admins(view_id="filer_folder")
+
+        self.assertEqual(
+            [e["view_id"] for e in result["admin_views"]], ["filer_folder"]
+        )
+        entry = result["admin_views"][0]
+        # Scoping narrows the set, it does not thin the entry.
+        self.assertIn("fields", entry)
+        self.assertIn("detail_fields", entry)
+        self.assertIn("inlines", entry)
+        self.assertIn("filter_presets", entry)
+        self.assertEqual(
+            entry["fields"][0]["filter"]["widget"], "MultipleChoiceFilterWidget"
+        )
+
+    def test_scoped_call_is_identical_to_the_entry_in_the_full_call(self):
+        """The cheap path must not be a different, lossier schema."""
+        tools = self._tools()
+        scoped = tools.list_admins(view_id="filer_folder")["admin_views"][0]
+        unscoped = next(
+            e
+            for e in self._tools().list_admins()["admin_views"]
+            if e["view_id"] == "filer_folder"
+        )
+
+        self.assertEqual(scoped, unscoped)
+
+    def test_index_returns_identity_only_and_drops_the_legends(self):
+        result = self._tools().list_admins(detail="index")
+
+        entry = next(e for e in result["admin_views"] if e["view_id"] == "filer_folder")
+        self.assertEqual(
+            set(entry),
+            {"view_id", "app_label", "model", "verbose_name", "verbose_name_plural"},
+        )
+        # Legends explain filter/action keys an index entry doesn't carry.
+        self.assertNotIn("widget_shapes", result)
+        self.assertNotIn("action_invokers", result)
+
+    def test_index_is_substantially_cheaper_than_full(self):
+        import json
+
+        tools = self._tools()
+        index = len(json.dumps(tools.list_admins(detail="index"), default=str))
+        full = len(json.dumps(self._tools().list_admins(), default=str))
+
+        self.assertLess(index, full / 2)
+
+    def test_index_still_lists_every_visible_admin(self):
+        tools = self._tools()
+        index_ids = [
+            e["view_id"] for e in tools.list_admins(detail="index")["admin_views"]
+        ]
+        full_ids = [e["view_id"] for e in self._tools().list_admins()["admin_views"]]
+
+        self.assertEqual(index_ids, full_ids)
+
+    def test_index_keeps_the_admin_description(self):
+        class FolderDescribedAdmin(SBAdmin):
+            model = Folder
+            list_display = ("id", "name")
+            mcp_description = "Folders of files."
+
+        sb_admin_site._registry.pop(Folder, None)
+        sb_admin_site.register(Folder, FolderDescribedAdmin)
+
+        result = self._tools().list_admins(view_id="filer_folder", detail="index")
+
+        self.assertEqual(result["admin_views"][0]["description"], "Folders of files.")
+
+    def test_unknown_view_id_raises_instead_of_returning_empty(self):
+        """An empty list would read as "no such data" rather than "no such handle"."""
+        with self.assertRaises(LookupError):
+            self._tools().list_admins(view_id="filer_nosuchthing")
+
+    def test_view_id_still_honours_view_permission(self):
+        MCPToolTestConfig.view_permission_for = set()
+        user = MagicMock(is_authenticated=True, is_superuser=False)
+        tools = SBAdminTools(request=build_mcp_request(user))
+
+        with self.assertRaises(PermissionError):
+            tools.list_admins(view_id="filer_folder")
+
+    def test_invalid_detail_is_rejected(self):
+        with self.assertRaises(ValueError):
+            self._tools().list_admins(detail="everything")
+
+    def test_whoami_survives_an_index_call(self):
+        folder = Folder.objects.create(name="profile")
+        user = MagicMock(
+            pk=folder.pk,
+            id=folder.pk,
+            is_authenticated=True,
+            is_anonymous=False,
+            is_superuser=True,
+        )
+        MCPToolTestConfig().mcp_whoami_sbadmin = SBAdminWhoamiConfig(
+            view_id="filer_folder"
+        )
+
+        result = SBAdminTools(request=build_mcp_request(user)).list_admins(
+            detail="index"
+        )
+
+        self.assertEqual(
+            result["whoami"], {"view_id": "filer_folder", "object_id": str(folder.pk)}
+        )