feat(mcp): add list and get tools for annotation layers and annotations

[aminghadersohi]

SUMMARY

Adds 4 new MCP tools in a new superset/mcp_service/annotation_layer/ domain:

• list_annotation_layers — list annotation layers with filtering, search, and 1-based pagination
• get_annotation_layer_info — get annotation layer details by ID
• list_layer_annotations — list annotations within a layer (requires layer_id to scope results)
• get_layer_annotation_info — get a single annotation by layer_id + annotation_id, with layer-membership verification

The annotation tools mirror the pattern used by database/, dashboard/, and dataset/ domains: Pydantic request/response schemas, ModelListCore for listings, DAO-based lookups, ToolAnnotations, and event_logger instrumentation.

For annotations, layer_id is a required parameter that scopes all results to the parent layer — mirroring the Superset REST API structure (GET /annotation_layer/{layer_pk}/annotation/).

BEFORE/AFTER SCREENSHOTS OR ANIMATED GIF

N/A (backend-only MCP tool additions)

TESTING INSTRUCTIONS

1. Run unit tests:

   pytest tests/unit_tests/mcp_service/annotation_layer/
   

2. Connect an MCP client and call:
   • list_annotation_layers({}) — lists all annotation layers
   • get_annotation_layer_info({"id": <id>}) — retrieves a specific layer
   • list_layer_annotations({"layer_id": <id>}) — lists annotations in a layer
   • get_layer_annotation_info({"layer_id": <id>, "annotation_id": <id>}) — retrieves a specific annotation

ADDITIONAL INFORMATION

• Has associated issue:
• Required feature flags:
• Changes UI
• Includes DB Migration
• Introduces new feature or API
• Removes existing feature or API

[codecov]

Codecov Report

❌ Patch coverage is 65.62500% with 88 lines in your changes missing coverage. Please review.
✅ Project coverage is 63.83%. Comparing base (73f66e4) to head (6e71872).
⚠️ Report is 71 commits behind head on master.

Files with missing lines	Patch %	Lines
...annotation_layer/tool/get_layer_annotation_info.py	29.03%	22 Missing ⚠️
...ce/annotation_layer/tool/list_layer_annotations.py	39.39%	20 Missing ⚠️
superset/mcp_service/annotation_layer/schemas.py	87.31%	16 Missing and 1 partial ⚠️
...ce/annotation_layer/tool/list_annotation_layers.py	42.85%	16 Missing ⚠️
...annotation_layer/tool/get_annotation_layer_info.py	43.47%	13 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master   #40303      +/-   ##
==========================================
- Coverage   64.14%   63.83%   -0.32%     
==========================================
  Files        2592     2598       +6     
  Lines      138846   140183    +1337     
  Branches    32201    32492     +291     
==========================================
+ Hits        89069    89488     +419     
- Misses      48245    49131     +886     
- Partials     1532     1564      +32     

Flag	Coverage Δ
hive	39.15% <65.62%> (-0.18%)	⬇️
mysql	58.28% <65.62%> (-0.58%)	⬇️
postgres	58.36% <65.62%> (-0.58%)	⬇️
presto	40.79% <65.62%> (-0.21%)	⬇️
python	59.89% <65.62%> (-0.62%)	⬇️
sqlite	58.01% <65.62%> (-0.58%)	⬇️
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.

[aminghadersohi]

Superseded by #40342 (branch renamed to follow amin/ convention).

[bito-code-review]

Code Review Agent Run #f2741b

Actionable Suggestions - 3

• superset/mcp_service/annotation_layer/tool/list_layer_annotations.py - 1

  • Exception swallows middleware error handling · Line 140-149
• tests/unit_tests/mcp_service/annotation_layer/tool/test_annotation_layer_tools.py - 1

  • Weak test assertion · Line 330-347
• superset/mcp_service/annotation_layer/tool/get_layer_annotation_info.py - 1

  • Avoid catching blind Exception · Line 120-120

Additional Suggestions - 2

• superset/mcp_service/annotation_layer/tool/list_layer_annotations.py - 1

  • Unused function parameter dead code · Line 100-101
    The `_serialize` function accepts a `cols` parameter but never uses it. This is dead code that creates maintenance confusion. Compare with `list_annotation_layers.py` which uses a local function without the unused parameter.
    Code suggestion

    --- superset/mcp_service/annotation_layer/tool/list_layer_annotations.py
    +++ superset/mcp_service/annotation_layer/tool/list_layer_annotations.py
     @@ -97,7 +97,7 @@ async def list_layer_annotations(
              )
              combined_filters: list[ColumnOperator] = [layer_filter] + list(request.filters)
     
    -        def _serialize(obj: object, cols: list[str] | None) -> AnnotationInfo | None:
    +        def _serialize(obj: object) -> AnnotationInfo | None:
                  return serialize_annotation(obj)

• superset/mcp_service/annotation_layer/tool/get_annotation_layer_info.py - 1

  • Inconsistent error factory method · Line 93-96
    Inconsistent error construction pattern: lines 93-96 manually construct AnnotationLayerError with a manual timestamp, while get_layer_annotation_info.py uses AnnotationLayerError.create() which handles timestamp automatically. Use AnnotationLayerError.create(error='...', error_type='InternalError') for consistency.
    Code suggestion

    --- superset/mcp_service/annotation_layer/tool/get_annotation_layer_info.py
    +++ superset/mcp_service/annotation_layer/tool/get_annotation_layer_info.py
     @@ -90,8 +90,6 @@ async def get_annotation_layer_info(
                  % (request.id, str(e), type(e).__name__)
              )
    -        return AnnotationLayerError(
    -            error=f"Failed to get annotation layer info: {str(e)}",
    -            error_type="InternalError",
    -            timestamp=datetime.now(timezone.utc),
    -        )
    +        return AnnotationLayerError.create(
    +            error=f"Failed to get annotation layer info: {str(e)}",
    +            error_type="InternalError",
    +        )

Filtered by Review Rules

Bito filtered these suggestions based on rules created automatically for your feedback. Manage rules.

• superset/mcp_service/annotation_layer/tool/list_annotation_layers.py - 1

  • Missing humanized timestamp fields · Line 77-80
• tests/unit_tests/mcp_service/annotation_layer/tool/test_annotation_layer_tools.py - 1

  • Incorrect mock assertion · Line 234-234

Review Details

• Files reviewed - 11 · Commit Range: de1a231..6e71872

  • superset/mcp_service/annotation_layer/__init__.py
  • superset/mcp_service/annotation_layer/schemas.py
  • superset/mcp_service/annotation_layer/tool/__init__.py
  • superset/mcp_service/annotation_layer/tool/get_annotation_layer_info.py
  • superset/mcp_service/annotation_layer/tool/get_layer_annotation_info.py
  • superset/mcp_service/annotation_layer/tool/list_annotation_layers.py
  • superset/mcp_service/annotation_layer/tool/list_layer_annotations.py
  • superset/mcp_service/app.py
  • tests/unit_tests/mcp_service/annotation_layer/__init__.py
  • tests/unit_tests/mcp_service/annotation_layer/tool/__init__.py
  • tests/unit_tests/mcp_service/annotation_layer/tool/test_annotation_layer_tools.py
• Files skipped - 0
• Tools

  • Whispers (Secret Scanner) - ✔︎ Successful
  • Detect-secrets (Secret Scanner) - ✔︎ Successful
  • MyPy (Static Code Analysis) - ✔︎ Successful
  • Astral Ruff (Static Code Analysis) - ✔︎ Successful

---

Bito Usage Guide

Commands

Type the following command in the pull request comment and save the comment.

• /review - Manually triggers a full AI review.

• /pause - Pauses automatic reviews on this pull request.

• /resume - Resumes automatic reviews.

• /resolve - Marks all Bito-posted review comments as resolved.

• /abort - Cancels all in-progress reviews.

Refer to the documentation for additional commands.

Configuration

This repository uses Superset You can customize the agent settings here or contact your Bito workspace admin at evan@preset.io.

Documentation & Help

• Customize agent settings
• Review rules
• General documentation
• FAQ

AI Code Review powered by