fix: improve create_card dataset_query schema for MCP compatibility

[Kai-Oesterling]

Problem

The create_card tool fails with HTTP 400 errors when called via MCP clients (Claude Desktop, etc.). The Metabase API rejects the request because the dataset_query object isn't properly structured.

Root Cause

The current schema definition:

dataset_query: z.object({}).passthrough().optional()

While passthrough() should allow additional properties, MCP clients don't properly serialize deeply nested objects when the base schema is an empty object {}.

Example Error

When trying to create a card with a native SQL query:

{
  "name": "Test Card",
  "dataset_query": {
    "type": "native",
    "database": 2,
    "native": { "query": "SELECT * FROM users" }
  }
}

The API returns: Request failed with status code 400

Solution

Define explicit Zod schemas for the two main query types:

1. Native SQL queries:

const nativeQuerySchema = z.object({
  type: z.literal("native"),
  database: z.number(),
  native: z.object({
    query: z.string(),
    "template-tags": z.record(z.any()).optional(),
  }).passthrough(),
}).passthrough();

2. MBQL queries:

const mbqlQuerySchema = z.object({
  type: z.literal("query"),
  database: z.number(),
  query: z.object({
    "source-table": z.number().optional(),
  }).passthrough(),
}).passthrough();

Combined with z.union() to accept either format.

Additional Improvements

• Enhanced tool description with examples of both query formats
• Added default values for display ("table") and visualization_settings ({})
• Listed available display types in description

Testing

Tested with:

• SQL Server database (native queries)
• Creating cards via direct API call with the same payload structure
• Card creation now succeeds where it previously failed

Breaking Changes

None. The schema is more specific but still accepts all valid Metabase query formats via passthrough().