This is an automated email from the ASF dual-hosted git repository.
aminghadersohi pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/superset.git
The following commit(s) were added to refs/heads/master by this push:
new 96d31ee3e35 docs(mcp): document deleted_state trash listing for
list_charts/list_dashboards (#44128)
96d31ee3e35 is described below
commit 96d31ee3e358de2860f2876f165ed8a4c19c5be3
Author: Evan Rusackas <[email protected]>
AuthorDate: Thu Sep 24 15:37:23 2026 -0700
docs(mcp): document deleted_state trash listing for
list_charts/list_dashboards (#44128)
Co-authored-by: Claude Sonnet 5 <[email protected]>
---
docs/admin_docs/configuration/mcp-server.mdx | 17 +++++++++++++++++
superset/mcp_service/chart/schemas.py | 8 ++++++--
superset/mcp_service/dashboard/schemas.py | 8 ++++++--
3 files changed, 29 insertions(+), 4 deletions(-)
diff --git a/docs/admin_docs/configuration/mcp-server.mdx
b/docs/admin_docs/configuration/mcp-server.mdx
index a8bb4d6a92c..a0a3e3db147 100644
--- a/docs/admin_docs/configuration/mcp-server.mdx
+++ b/docs/admin_docs/configuration/mcp-server.mdx
@@ -1020,6 +1020,23 @@ while True:
page += 1
```
+## Trash Listing (Soft-Deleted Objects)
+
+When the `SOFT_DELETE` feature flag is enabled, deleting a chart or dashboard
moves it to trash rather than removing it outright. The `list_charts` and
`list_dashboards` tools accept a `deleted_state` parameter to surface those
trashed objects:
+
+- `deleted_state="only"` — return only trashed objects
+- `deleted_state="include"` — return live and trashed objects together
+- Omitted (default) — live objects only; trashed objects are excluded
+
+```python
+# List only trashed charts
+result = mcp.list_charts(request={"deleted_state": "only"})
+```
+
+Trashed rows carry a non-null `deleted_at` timestamp in the response
(populated only when `deleted_state` is used). Visibility follows the same
restore-audience scoping as the equivalent REST API filters
(`chart_deleted_state` / `dashboard_deleted_state`): a non-admin caller sees
only the trashed objects they can edit (the same audience that can restore
them), not merely the ones they own; admins see all trashed objects. That
scoping is narrower than the true restore audience in two case [...]
+
+`deleted_state` is only defined on `list_charts` and `list_dashboards`. Other
list tools don't declare the field at all, so passing it is silently ignored
rather than rejected — it never returns trashed objects.
+
## Disabling built-in tools
If you have deployed a custom tool via a Superset extension that supersedes
one of the built-in Superset tools, you can suppress the built-in version so AI
clients only discover your replacement. Disabled tools are removed from the
server at startup and are never advertised during tool discovery.
diff --git a/superset/mcp_service/chart/schemas.py
b/superset/mcp_service/chart/schemas.py
index 5cfd4820898..ada93209cab 100644
--- a/superset/mcp_service/chart/schemas.py
+++ b/superset/mcp_service/chart/schemas.py
@@ -3806,8 +3806,12 @@ class ListChartsRequest(
"trashed charts, 'include' returns live and trashed charts "
"together. Omit for live charts only (default). Trashed rows "
"carry a non-null deleted_at and are limited to charts the "
- "caller owns (admins see all); requires the SOFT_DELETE "
- "feature flag to have produced trashed rows."
+ "caller can edit (the same audience that can restore them, "
+ "not merely the ones they own; admins see all). This omits "
+ "EXTRA_EDITORS_RESOLVER-granted and guest role-derived "
+ "editorship, so some restorable charts may be under-"
+ "enumerated. Requires the SOFT_DELETE feature flag to have "
+ "produced trashed rows."
),
),
]
diff --git a/superset/mcp_service/dashboard/schemas.py
b/superset/mcp_service/dashboard/schemas.py
index 935b268ea80..8b7dfee325b 100644
--- a/superset/mcp_service/dashboard/schemas.py
+++ b/superset/mcp_service/dashboard/schemas.py
@@ -207,8 +207,12 @@ class ListDashboardsRequest(
"just trashed dashboards, 'include' returns live and trashed "
"together. Omit for live dashboards only (default). Trashed "
"rows carry a non-null deleted_at and are limited to "
- "dashboards the caller owns (admins see all); requires the "
- "SOFT_DELETE feature flag to have produced trashed rows."
+ "dashboards the caller can edit (the same audience that can "
+ "restore them, not merely the ones they own; admins see "
+ "all). This omits EXTRA_EDITORS_RESOLVER-granted and guest "
+ "role-derived editorship, so some restorable dashboards may "
+ "be under-enumerated. Requires the SOFT_DELETE feature flag "
+ "to have produced trashed rows."
),
),
]
