fix(mcp): resolve dashboard permalinks

[aminghadersohi]

SUMMARY

Dashboard lookup tools can resolve shared /dashboard/p/<key>/ links and bare permalink keys, returning the dashboard identifier together with the permalink's active-tab and filter state. This extends the existing tools rather than adding a resolver round trip: their response models already carry dashboard metadata and state, so transparent resolution keeps the workflow discoverable without losing context.

Invalid or expired permalinks return an actionable error asking for a fresh shared link. Numeric IDs, UUIDs, and slugs retain their existing lookup path; ambiguous bare strings are attempted as permalinks only after ordinary identifier lookup fails.

BEFORE/AFTER SCREENSHOTS OR ANIMATED GIF

Not applicable; this changes MCP tool behavior and schemas only.

TESTING INSTRUCTIONS

ruff format superset/mcp_service/dashboard/schemas.py superset/mcp_service/dashboard/permalink.py superset/mcp_service/dashboard/tool/get_dashboard_info.py superset/mcp_service/dashboard/tool/get_dashboard_layout.py tests/unit_tests/mcp_service/dashboard/tool/test_dashboard_tools.py tests/unit_tests/mcp_service/dashboard/tool/test_get_dashboard_layout.py
ruff check superset/mcp_service/dashboard/schemas.py superset/mcp_service/dashboard/permalink.py superset/mcp_service/dashboard/tool/get_dashboard_info.py superset/mcp_service/dashboard/tool/get_dashboard_layout.py tests/unit_tests/mcp_service/dashboard/tool/test_dashboard_tools.py tests/unit_tests/mcp_service/dashboard/tool/test_get_dashboard_layout.py
pytest -q tests/unit_tests/mcp_service/dashboard/
pre-commit run --files superset/mcp_service/app.py superset/mcp_service/dashboard/schemas.py superset/mcp_service/dashboard/permalink.py superset/mcp_service/dashboard/tool/get_dashboard_info.py superset/mcp_service/dashboard/tool/get_dashboard_layout.py tests/unit_tests/mcp_service/dashboard/tool/test_dashboard_tools.py tests/unit_tests/mcp_service/dashboard/tool/test_get_dashboard_layout.py

The dashboard MCP unit suite passes (362 tests). Changed-file pre-commit passes. The repository-wide pre-commit run was also attempted; unrelated existing type/lint failures and missing frontend dependencies prevent that full-tree gate from completing.

ADDITIONAL INFORMATION

• Has associated issue:
• Required feature flags:
• Changes UI
• Includes DB Migration (follow approval process in SIP-59)
  • Migration is atomic, supports rollback & is backwards-compatible
  • Confirm DB migration upgrade and downgrade tested
  • Runtime estimates and downtime expectations provided
• Introduces new feature or API
• Removes existing feature or API

Blast radius

Apache Superset's optional MCP service only. No migrations, feature flags, authentication changes, workspace isolation changes, or database query behavior changes.

Risk and rollback

The main risk is interpreting an unknown slug-like identifier as a permalink after normal lookup fails. Existing identifiers are resolved first, and reverting this commit restores the previous behavior.

Eval evidence

The deployment-backed agent eval suite was not run for this draft because no deployed build is available. The deterministic MCP unit coverage exercises permalink resolution, active-tab/filter context, invalid links, and existing identifier forms.

Cost and latency delta

No model, prompt-routing, or token changes. A bare permalink key can add one permalink lookup after an unsuccessful ordinary identifier lookup; explicit permalink inputs and shared URLs resolve directly. Deployment-backed latency measurements were not available for this draft.

Prompt / non-determinism

Tool descriptions were updated to identify /dashboard/p/<key>/ links and direct agents to the lookup tools. The resolution behavior is deterministic; no model prompt or routing behavior changed.

Review guidance

Start with dashboard/permalink.py and the request/response schema changes, then review how each lookup tool reuses the resolved dashboard ID and safely exposes permalink state. The most important behavior is the ordinary-identifier-first fallback for bare strings.

[codecov]

Codecov Report

❌ Patch coverage is 22.33010% with 80 lines in your changes missing coverage. Please review.
✅ Project coverage is 65.42%. Comparing base (035eaa8) to head (61e3141).
⚠️ Report is 6 commits behind head on master.

Files with missing lines	Patch %	Lines
superset/mcp_service/dashboard/permalink.py	28.57%	25 Missing ⚠️
...mcp_service/dashboard/tool/get_dashboard_layout.py	10.71%	25 Missing ⚠️
...t/mcp_service/dashboard/tool/get_dashboard_info.py	7.69%	24 Missing ⚠️
superset/mcp_service/dashboard/schemas.py	57.14%	6 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master   #42659      +/-   ##
==========================================
- Coverage   65.44%   65.42%   -0.03%     
==========================================
  Files        2810     2811       +1     
  Lines      159366   159452      +86     
  Branches    36374    36394      +20     
==========================================
+ Hits       104302   104321      +19     
- Misses      53022    53088      +66     
- Partials     2042     2043       +1     

Flag	Coverage Δ
hive	38.07% <22.33%> (-0.02%)	⬇️
mysql	57.79% <22.33%> (-0.04%)	⬇️
postgres	57.83% <22.33%> (-0.04%)	⬇️
presto	39.96% <22.33%> (-0.02%)	⬇️
python	59.21% <22.33%> (-0.05%)	⬇️
sqlite	57.46% <22.33%> (-0.04%)	⬇️
unit	100.00% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.