fix(api): expose alternateRowBackground on raw SQL table tiles via MCP

The dashboard authoring MCP schema declared alternateRowBackground on
builder table tiles but not on raw SQL table tiles, so save_dashboard and
patch_dashboard silently stripped the flag from raw SQL tables even though
the UI and REST API both accept it.

- Declare alternateRowBackground on the raw SQL MCP tile schema
- Add REST raw SQL table omit / explicit-false round-trip coverage
- Add MCP raw SQL table save + patch round-trip coverage for the flag
- Add MCP-to-REST table schema parity tests (builder + raw SQL)
- Use an explicit property for the field in the builder table converter so a
  rename is a compile error, not a silent runtime drop
- List the MCP tile schemas in the shared-schema sync checklist comment

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: alex-fedotyev

packages/api/src/mcp/__tests__/dashboards/saveDashboard.int.test.ts

@@ -426,6 +426,7 @@ describe('MCP Dashboard Tools - clickstack_save_dashboard', () => {
                 displayType: 'table' as const,
                 connectionId,
                 sqlTemplate: 'SELECT 1 AS value LIMIT 1',
+                alternateRowBackground: true,
               },
             },
           ],
@@ -441,6 +442,13 @@ describe('MCP Dashboard Tools - clickstack_save_dashboard', () => {
         (t: { name: string }) => t.name === 'SLO',
       );
       expect(savedSqlNumberTile.config).toMatchObject(sqlNumberConfig);
+      // Raw SQL table tile: the zebra-stripe flag must survive the MCP save
+      // path. It was silently stripped before the raw SQL MCP tile schema
+      // declared alternateRowBackground.
+      const savedSqlTableTile = saved.tiles.find(
+        (t: { name: string }) => t.name === 'Other Tile',
+      );
+      expect(savedSqlTableTile.config.alternateRowBackground).toBe(true);
 
       const getResult = await callTool(
         ctx.client!,
@@ -492,6 +500,12 @@ describe('MCP Dashboard Tools - clickstack_save_dashboard', () => {
         (t: { name: string }) => t.name === 'SLO',
       );
       expect(refetchedSqlNumberTile.config).toMatchObject(sqlNumberConfig);
+      // "Other Tile" was the one updated (new sqlTemplate); its zebra-stripe
+      // flag must survive the MCP update (patch) path too.
+      const refetchedSqlTableTile = refetched.tiles.find(
+        (t: { name: string }) => t.name === 'Other Tile',
+      );
+      expect(refetchedSqlTableTile.config.alternateRowBackground).toBe(true);
     });
 
     it('should create a dashboard with a heatmap tile on a Trace source', async () => {

packages/api/src/mcp/__tests__/dashboards/schema-parity.test.ts

@@ -0,0 +1,37 @@
+// The MCP dashboard authoring tile schemas (what save_dashboard / patch_dashboard
+// accept) are a hand-maintained mirror of the external REST dashboard schemas,
+// with no shared type or derivation. A field added to a REST table config but not
+// to the matching MCP tile schema is silently stripped on MCP writes, which is the
+// failure mode that let alternateRowBackground drop on raw SQL table tiles. These
+// tests assert each MCP table config declares every field its REST counterpart
+// accepts, so field-presence drift fails here instead of escaping review.
+import {
+  mcpSqlTileSchema,
+  mcpTableTileSchema,
+} from '@/mcp/tools/dashboards/schemas';
+import {
+  externalDashboardTableChartConfigSchema,
+  externalDashboardTableRawSqlChartConfigSchema,
+} from '@/utils/zod';
+
+describe('MCP dashboard tile schema parity with the external REST schemas', () => {
+  it('builder table: MCP config declares every field the REST builder table schema accepts', () => {
+    const restFields = Object.keys(
+      externalDashboardTableChartConfigSchema.shape,
+    );
+    const mcpFields = new Set(
+      Object.keys(mcpTableTileSchema.shape.config.shape),
+    );
+
+    expect(restFields.filter(field => !mcpFields.has(field))).toEqual([]);
+  });
+
+  it('raw SQL table: MCP config declares every field the REST raw SQL table schema accepts', () => {
+    const restFields = Object.keys(
+      externalDashboardTableRawSqlChartConfigSchema.shape,
+    );
+    const mcpFields = new Set(Object.keys(mcpSqlTileSchema.shape.config.shape));
+
+    expect(restFields.filter(field => !mcpFields.has(field))).toEqual([]);
+  });
+});

packages/api/src/mcp/tools/dashboards/schemas.ts

@@ -655,7 +655,7 @@ const mcpBarTileSchema = mcpTileLayoutSchema.extend({
   }),
 });
 
-const mcpTableTileSchema = mcpTileLayoutSchema.extend({
+export const mcpTableTileSchema = mcpTileLayoutSchema.extend({
   config: z.object({
     ...rejectedTileWhereFields,
     displayType: z.literal('table').describe('Tabular aggregated data'),
@@ -947,7 +947,7 @@ const mcpMarkdownTileSchema = mcpTileLayoutSchema.extend({
   }),
 });
 
-const mcpSqlTileSchema = mcpTileLayoutSchema.extend({
+export const mcpSqlTileSchema = mcpTileLayoutSchema.extend({
   config: z.object({
     configType: z
       .literal('sql')
@@ -1023,6 +1023,13 @@ GROUP BY ServiceName, ts
     color: ChartPaletteTokenSchema.optional().describe(
       rawSqlNumberTileColorDescription,
     ),
+    alternateRowBackground: z
+      .boolean()
+      .optional()
+      .describe(
+        'Zebra-stripe the table by tinting alternating rows, which aids scanning on wide tables. ' +
+          'Valid only when displayType is "table", ignored otherwise. Default false.',
+      ),
     onClick: mcpOnClickSchema.optional(),
   }),
 });

packages/api/src/routers/external-api/__tests__/dashboards.int.test.ts

@@ -2789,6 +2789,57 @@ describe('External API v2 Dashboards - new format', () => {
       );
     });
 
+    it('omits alternateRowBackground on a raw SQL table tile when not provided, and persists explicit false', async () => {
+      const connectionId = connection._id.toString();
+      const sourceId = traceSource._id.toString();
+      const sqlTemplate = 'SELECT count() FROM otel_logs WHERE {timeFilter}';
+
+      const tableNoStripe: ExternalDashboardTile = {
+        name: 'Raw SQL table without stripe setting',
+        x: 0,
+        y: 0,
+        w: 6,
+        h: 3,
+        config: {
+          configType: 'sql',
+          displayType: 'table',
+          connectionId,
+          sqlTemplate,
+          sourceId,
+        },
+      };
+
+      const tableStripeOff: ExternalDashboardTile = {
+        name: 'Raw SQL table with stripe explicitly off',
+        x: 6,
+        y: 0,
+        w: 6,
+        h: 3,
+        config: {
+          configType: 'sql',
+          displayType: 'table',
+          connectionId,
+          sqlTemplate,
+          sourceId,
+          alternateRowBackground: false,
+        },
+      };
+
+      const response = await authRequest('post', BASE_URL)
+        .send({
+          name: 'Dashboard raw SQL table stripe defaults',
+          tiles: [tableNoStripe, tableStripeOff],
+        })
+        .expect(200);
+
+      expect(response.body.data.tiles[0].config).not.toHaveProperty(
+        'alternateRowBackground',
+      );
+      expect(response.body.data.tiles[1].config.alternateRowBackground).toBe(
+        false,
+      );
+    });
+
     // Schema-level rejections that exercise pure Zod constraints
     // (discriminated-union absence, `min(1)` on valueExpression, and
     // `length(1)` on the select array). The non-Trace-source case

packages/api/src/routers/external-api/v2/utils/dashboards.ts

@@ -423,11 +423,13 @@ const convertToExternalTileChartConfig = (
           'having',
           'numberFormat',
           'groupByColumnsOnLeft',
-          'alternateRowBackground',
           'onClick',
         ]),
         displayType: config.displayType,
         sourceId,
+        // Explicit property (not via `pick`) so a future rename is a compile
+        // error rather than a silent runtime drop; matches the raw SQL arm.
+        alternateRowBackground: config.alternateRowBackground,
         asRatio:
           config.seriesReturnType === 'ratio' &&
           Array.isArray(config.select) &&

packages/api/src/utils/zod.ts

@@ -332,7 +332,7 @@ const externalDashboardBarRawSqlChartConfigSchema =
     seriesLimit: z.number().int().nonnegative().optional(),
   });
 
-const externalDashboardTableChartConfigSchema = z.object({
+export const externalDashboardTableChartConfigSchema = z.object({
   displayType: z.literal('table'),
   sourceId: objectIdSchema,
   select: z.array(externalDashboardSelectItemSchema).min(1).max(20),
@@ -348,7 +348,7 @@ const externalDashboardTableChartConfigSchema = z.object({
   showOperandSeries: externalShowOperandSeriesSchema,
 });
 
-const externalDashboardTableRawSqlChartConfigSchema =
+export const externalDashboardTableRawSqlChartConfigSchema =
   externalDashboardRawSqlChartConfigBaseSchema.extend({
     displayType: z.literal('table'),
     alternateRowBackground: z.boolean().optional(),

packages/common-utils/src/types.ts

@@ -1416,9 +1416,11 @@ export const BackgroundChartSchema = z.object({
 export type BackgroundChart = z.infer<typeof BackgroundChartSchema>;
 
 // When making changes here, consider if they need to be made to the external API
-// as well: the Zod schema (packages/api/src/utils/zod.ts) and the hand-written
+// as well: the Zod schema (packages/api/src/utils/zod.ts), the hand-written
 // OpenAPI JSDoc (packages/api/src/routers/external-api/v2/dashboards.ts), which
-// duplicates this shape for the generated spec.
+// duplicates this shape for the generated spec, and the MCP dashboard authoring
+// tile schemas (packages/api/src/mcp/tools/dashboards/schemas.ts), a separate
+// hand-maintained mirror that gates what save_dashboard / patch_dashboard accept.
 /**
  * Schema describing settings which are shared between Raw SQL
  * chart configs and Structured ChartBuilder chart configs