chore(mcp): update CLAUDE.md to reflect current codebase patterns by aminghadersohi · Pull Request #39348 · apache/superset

aminghadersohi · 2026-04-14T16:05:49Z

SUMMARY

Updates superset/mcp_service/CLAUDE.md to reflect the current state of the MCP codebase after 90+ merged PRs since Jan 2025. This doc is used by LLM agents to understand MCP service conventions.

Key changes:

Remove stale @parse_request decorator references (removed in fix(mcp): remove @parse_request decorator for cleaner tool schemas #38918)
Fix decorator import path to superset_core.mcp.decorators (was incorrectly documented as superset_core.api.mcp)
Add ToolAnnotations pattern (required since feat(mcp): Add tool annotations for MCP directory compliance #38641)
Add RBAC permission checking docs (feat(mcp): implement RBAC permission checking for MCP tools #38407)
Add event_logger instrumentation pattern (feat(mcp): add event_logger instrumentation to MCP tools #37859)
Add middleware documentation (feat(mcp): register GlobalErrorHandlerMiddleware and LoggingMiddleware #38523)
Add compile check pattern for chart creation (feat(mcp): add compile check to validate chart queries before returning #38408)
Update auth docs: mcp_auth_hook is only for resources, @tool handles tool auth
Update config section with MCP_RBAC_ENABLED, cache, and store configs
Update testing conventions: async Client pattern, conftest fixtures
Update architecture tree with all current modules (database, sql_lab, explore, etc.)
Add dependency injection architecture explanation
Remove stale line number references that break on every PR
Fix broken pitfall Multi delete action on datasources #9 (had identical good/bad examples)

BEFORE/AFTER SCREENSHOTS OR ANIMATED GIF

N/A - documentation only

TESTING INSTRUCTIONS

Read through the updated superset/mcp_service/CLAUDE.md
Verify the documented patterns match what exists in the codebase (e.g., grep for from superset_core.mcp.decorators import tool)
Confirm no references to removed patterns like @parse_request or superset_core.api.mcp

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

bito-code-review · 2026-04-14T16:06:00Z

Bito Automatic Review Skipped - Files Excluded

Bito didn't auto-review this change because all changed files are in the exclusion list for automatic reviews. No action is needed if you didn't intend for the agent to review it. Otherwise, to manually trigger a review, type /review in a comment and save.
You can change the excluded files settings here, or contact your Bito workspace admin at evan@preset.io.

netlify · 2026-04-14T16:10:40Z

✅ Deploy Preview for superset-docs-preview ready!

Name	Link
🔨 Latest commit	`82354d1`
🔍 Latest deploy log	https://app.netlify.com/projects/superset-docs-preview/deploys/69de9c707866ed00071f21f5
😎 Deploy Preview	https://deploy-preview-39348--superset-docs-preview.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

Copilot

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Updates superset/mcp_service/CLAUDE.md to align MCP agent-facing documentation with current MCP service implementation patterns (decorator injection, RBAC, middleware, logging, and testing) after many merged changes since Jan 2025.

Changes:

Refreshes architecture/module map and explains dependency injection startup flow.
Replaces stale decorator/auth patterns with current superset_core.mcp.decorators + ToolAnnotations, RBAC guidance, and event_logger instrumentation.
Updates conventions for middleware, config, flexible input parsing, and async testing via fastmcp.Client.

codecov · 2026-04-14T16:31:05Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 64.45%. Comparing base (3e25f02) to head (9ffb504).
⚠️ Report is 9 commits behind head on master.

❌ Your project status has failed because the head coverage (99.81%) is below the target coverage (100.00%). You can increase the head coverage or adjust the target coverage.

Additional details and impacted files

@@           Coverage Diff           @@
##           master   #39348   +/-   ##
=======================================
  Coverage   64.45%   64.45%           
=======================================
  Files        2555     2555           
  Lines      132721   132747   +26     
  Branches    30802    30810    +8     
=======================================
+ Hits        85539    85568   +29     
+ Misses      45696    45688    -8     
- Partials     1486     1491    +5

Flag	Coverage Δ
hive	`39.94% <ø> (-0.02%)`	⬇️
mysql	`60.62% <ø> (+0.02%)`	⬆️
postgres	`60.70% <ø> (+0.02%)`	⬆️
presto	`41.73% <ø> (-0.02%)`	⬇️
python	`62.29% <ø> (+0.02%)`	⬆️
sqlite	`60.33% <ø> (+0.02%)`	⬆️
unit	`100.00% <ø> (ø)`

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

☔ View full report in Codecov by Sentry.
📢 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.

Copilot

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated 3 comments.

@tool

Remove stale references and sync with 90+ merged MCP PRs since Jan 2025: - Remove @parse_request decorator references (removed in apache#38918) - Fix decorator import path: superset_core.mcp.decorators (not api.mcp) - Add ToolAnnotations pattern (required since apache#38641) - Add RBAC permission checking docs (apache#38407) - Add event_logger instrumentation pattern (apache#37859) - Add middleware documentation (apache#38523) - Add compile check pattern for chart creation (apache#38408) - Update auth docs: mcp_auth_hook only for resources, @tool handles tools - Update config section with MCP_RBAC_ENABLED, cache, store configs - Update testing conventions: async Client pattern, conftest fixtures - Update architecture tree with all current modules - Add dependency injection architecture explanation - Remove stale line number references - Fix broken pitfall #9 (identical good/bad examples) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- Remove nonexistent database/ module from architecture tree and test org - Fix caching docs: in-memory by default, Redis only when store enabled - Add missing `from typing import Any` import in type hints example - Use `model_dump()` instead of deprecated `dict()` (Pydantic v2)

Makes the excluded_tools config snippet copy/paste-safe by replacing Python ellipsis literal with a descriptive comment.

github-actions · 2026-04-15T09:51:54Z

🎪 Showtime is building environment on GHA for 82354d1

sadpandajoe · 2026-04-15T10:04:42Z

🎪 ⚡ showtime-trigger-start

github-actions · 2026-04-15T10:11:08Z

🎪 Showtime deployed environment on GHA for 82354d1

• Environment: http://54.68.169.30:8080 (admin/admin)
• Lifetime: 48h auto-cleanup
• Updates: New commits create fresh environments automatically

- Replace markdown tables with bullet lists to fix rendering issues - Make @mcp_auth_hook usage more explicit in resource example

aminghadersohi · 2026-04-15T14:38:14Z

This is jus a claude.md change. it doesnt change the code. not sure why we need to test the environtment as this is really only for the development cycle.

github-actions · 2026-04-15T14:42:39Z

🎪 Showtime is building environment on GHA for 9ffb504

github-actions · 2026-04-15T15:02:10Z

🎪 Showtime deployed environment on GHA for 9ffb504

• Environment: http://44.248.57.88:8080 (admin/admin)
• Lifetime: 48h auto-cleanup
• Updates: New commits create fresh environments automatically

bito-code-review · 2026-04-15T15:44:24Z

Bito Automatic Review Skipped – PR Already Merged

Bito scheduled an automatic review for this pull request, but the review was skipped because this PR was merged before the review could be run.
No action is needed if you didn't intend to review it. To get a review, you can type /review in a comment and save it

Copilot AI review requested due to automatic review settings April 14, 2026 16:05

pull-request-size bot added the size/XL label Apr 14, 2026

dosubot bot added the doc:developer Developer documentation label Apr 14, 2026

codeant-ai-for-open-source bot reviewed Apr 14, 2026

View reviewed changes

Comment thread superset/mcp_service/CLAUDE.md Outdated

Comment thread superset/mcp_service/CLAUDE.md Outdated

Copilot AI reviewed Apr 14, 2026

View reviewed changes

Comment thread superset/mcp_service/CLAUDE.md Outdated

Comment thread superset/mcp_service/CLAUDE.md Outdated

Comment thread superset/mcp_service/CLAUDE.md

Comment thread superset/mcp_service/CLAUDE.md Outdated

aminghadersohi requested a review from Copilot April 14, 2026 17:01

Copilot AI reviewed Apr 14, 2026

View reviewed changes

Comment thread superset/mcp_service/CLAUDE.md Outdated

Comment thread superset/mcp_service/CLAUDE.md Outdated

Comment thread superset/mcp_service/CLAUDE.md Outdated

Copilot started reviewing on behalf of aminghadersohi April 14, 2026 17:58 View session

Copilot started reviewing on behalf of aminghadersohi April 14, 2026 18:22 View session

aminghadersohi and others added 3 commits April 14, 2026 15:58

fix: replace ellipsis with comment in config example

82354d1

Makes the excluded_tools config snippet copy/paste-safe by replacing Python ellipsis literal with a descriptive comment.

aminghadersohi force-pushed the amin/update-mcp-claude-md branch from 38c7629 to 82354d1 Compare April 14, 2026 19:58

sadpandajoe added 🎪 ⚡ showtime-trigger Trigger showtime deployment 🎪 ⚡ showtime-trigger-start Create new ephemeral environment for this PR and removed 🎪 ⚡ showtime-trigger Trigger showtime deployment labels Apr 15, 2026

github-actions bot added 🎪 ⌛ 48h Environment expires after 48 hours (default) 🎪 82354d1 🚦 deploying Environment 82354d1 status: deploying and removed 🎪 82354d1 🚦 building Environment 82354d1 status: building labels Apr 15, 2026

github-actions bot added 🎪 82354d1 🚦 running Environment 82354d1 status: running and removed 🎪 82354d1 🚦 deploying Environment 82354d1 status: deploying labels Apr 15, 2026

fix: address all remaining review comments on MCP CLAUDE.md

9ffb504

- Replace markdown tables with bullet lists to fix rendering issues - Make @mcp_auth_hook usage more explicit in resource example

github-actions bot added 🎪 9ffb504 🚦 building Environment 9ffb504 status: building 🎪 9ffb504 📅 2026-04-15T14-42 Environment 9ffb504 created at 2026-04-15T14-42 🎪 9ffb504 🤡 aminghadersohi Environment 9ffb504 requested by aminghadersohi labels Apr 15, 2026

dpgaspar approved these changes Apr 15, 2026

View reviewed changes

aminghadersohi merged commit 724f148 into apache:master Apr 15, 2026
64 of 65 checks passed

Conversation

aminghadersohi commented Apr 14, 2026

SUMMARY

BEFORE/AFTER SCREENSHOTS OR ANIMATED GIF

TESTING INSTRUCTIONS

ADDITIONAL INFORMATION

Uh oh!

bito-code-review bot commented Apr 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

netlify bot commented Apr 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for superset-docs-preview ready!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

codecov bot commented Apr 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Apr 15, 2026

Uh oh!

sadpandajoe commented Apr 15, 2026

Uh oh!

github-actions bot commented Apr 15, 2026

Uh oh!

aminghadersohi commented Apr 15, 2026

Uh oh!

github-actions bot commented Apr 15, 2026

Uh oh!

github-actions bot commented Apr 15, 2026

Uh oh!

Uh oh!

bito-code-review bot commented Apr 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

bito-code-review bot commented Apr 14, 2026 •

edited

Loading

netlify bot commented Apr 14, 2026 •

edited

Loading

codecov bot commented Apr 14, 2026 •

edited

Loading