MCP: Update AppKit and use typed SQL parameters (#4116)

## Changes

- use AppKit from npm (no longer bundling it)
- Use typed SQL queries

## Why
<!-- Why are these changes needed? Provide the context that the reviewer
might be missing.
For example, were there any decisions behind the change that are not
reflected in the code itself? -->

## Tests
<!-- How have you tested the changes? -->

<!-- If your PR needs to be included in the release notes for next
release,
add a separate entry in NEXT_CHANGELOG.md as part of your PR. -->

Author: fjakobs

.wsignore

@@ -11,7 +11,6 @@ python/docs/images/databricks-logo.svg
 **/*.zip
 **/*.whl
 **/*.png
-**/*.tgz
 
 # new lines are recorded differently on windows and unix.
 # In unix: "raw_body": "hello, world\n"

experimental/apps-mcp/templates/.gitignore

@@ -1,9 +1,9 @@
-appkit/node_modules/
-appkit/dist/
-appkit/build/
-appkit/.env
-appkit/.databricks/
-appkit/.claude/
-appkit/.smoke-test/
-appkit/test-results/
-appkit/playwright-report/
+appkit/**/node_modules/
+appkit/**/dist/
+appkit/**/build/
+appkit/**/.env
+appkit/**/.databricks/
+appkit/**/.claude/
+appkit/**/.smoke-test/
+appkit/**/test-results/
+appkit/**/playwright-report/

experimental/apps-mcp/templates/appkit/databricks_template_schema.json

@@ -25,5 +25,5 @@
         "order": 4
       }
     },
-    "success_message": "\nYour new project has been created in the '{{.project_name}}' directory!\nYOU MUST read {{.project_name}}/CLAUDE.md immediately."
+    "success_message": "\nYour new project has been created in the '{{.project_name}}' directory!"
   }

experimental/apps-mcp/templates/appkit/template/{{.project_name}}/client/src/App.tsx

@@ -1,4 +1,5 @@
 import { useAnalyticsQuery, AreaChart, LineChart, RadarChart } from '@databricks/app-kit-ui/react';
+import { sql } from "@databricks/app-kit-ui/js";
 import { Line, XAxis, YAxis, CartesianGrid, Tooltip } from 'recharts';
 import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
 import { Skeleton } from '@/components/ui/skeleton';
@@ -9,7 +10,7 @@ import { useState, useEffect } from 'react';
 
 function App() {
   const { data, loading, error } = useAnalyticsQuery('hello_world', {
-    message: 'hello world',
+    message: sql.string('hello world'),
   });
 
   const [health, setHealth] = useState<{
@@ -48,7 +49,7 @@ function App() {
 
   const [maxMonthNum, setMaxMonthNum] = useState<number>(12);
 
-  const salesParameters = { max_month_num: maxMonthNum };
+  const salesParameters = { max_month_num: sql.number(maxMonthNum) };
 
   return (
     <div className="min-h-screen bg-background flex flex-col items-center justify-center p-4 w-full">

experimental/apps-mcp/templates/appkit/template/{{.project_name}}/config/queries/schema.ts

@@ -8,12 +8,11 @@
  * Example:
  *   SQL: SELECT name, age FROM users WHERE city = :city
  *   Schema: z.array(z.object({ name: z.string(), age: z.number() }))
- *   Usage: useAnalyticsQuery('users', { city: 'NYC' })
+ *   Usage: useAnalyticsQuery('users', { city: sql.string('NYC') })
  *                                       ^ input params   ^ schema validates this result
  */
 
 import { z } from 'zod';
-
 export const querySchemas = {
   mocked_sales: z.array(
     z.object({

experimental/apps-mcp/templates/appkit/template/{{.project_name}}/docs/app-kit-sdk.md

@@ -51,7 +51,10 @@ import { Skeleton } from '@/components/ui/skeleton';
 interface QueryResult { column_name: string; value: number; }
 
 function CustomDisplay() {
-  const { data, loading, error } = useAnalyticsQuery<QueryResult[]>('query_name', {});
+  const { data, loading, error } = useAnalyticsQuery<QueryResult[]>('query_name', {
+    start_date: sql.date(Date.now()),
+    category: sql.string("tools")
+  });
 
   if (loading) return <Skeleton className="h-4 w-3/4" />;
   if (error) return <div className="text-destructive">Error: {error}</div>;
@@ -74,7 +77,7 @@ function CustomDisplay() {
 ```typescript
 const { data, loading, error } = useAnalyticsQuery<T>(
   queryName: string,                        // SQL file name without .sql extension
-  params: Record<string, string | number>   // Query parameters
+  params: Record<string, SQLTypeMarker>     // Query parameters
 );
 // Returns: { data: T | null, loading: boolean, error: string | null }
 ```

experimental/apps-mcp/templates/appkit/template/{{.project_name}}/docs/frontend.md

@@ -11,6 +11,7 @@ Available: `AreaChart`, `BarChart`, `LineChart`, `PieChart`, `RadarChart`, `Data
 ```typescript
 import { BarChart, LineChart, DataTable } from '@databricks/app-kit-ui/react';
 import { Card, CardContent, CardHeader, CardTitle } from '@/components/ui/card';
+import { sql } from "@databricks/app-kit-ui/js";
 
 function MyDashboard() {
   return (
@@ -25,7 +26,7 @@ function MyDashboard() {
       <Card>
         <CardHeader><CardTitle>Revenue Trend</CardTitle></CardHeader>
         <CardContent>
-          <LineChart queryKey="revenue_over_time" parameters={{ months: 12 }} />
+          <LineChart queryKey="revenue_over_time" parameters={{ months: sql.number(12) }} />
         </CardContent>
       </Card>
     </div>

experimental/apps-mcp/templates/appkit/template/{{.project_name}}/docs/sql-queries.md

@@ -98,28 +98,64 @@ WHERE column_value >= :min_value
 ### Frontend Parameter Passing
 
 ```typescript
+import { sql } from "@databricks/app-kit-ui/js";
+
 const { data } = useAnalyticsQuery('filtered_data', {
-  min_value: minValue,
-  max_value: maxValue,
-  category: category,
-  optional_filter: optionalFilter || '',  // empty string for optional params
+  min_value: sql.number(minValue),
+  max_value: sql.number(maxValue),
+  category: sql.string(category),
+  optional_filter: sql.string(optionalFilter || ''),  // empty string for optional params
 });
 ```
 
 ### Date Parameters
 
-For dates, use `YYYY-MM-DD` format in frontend, `CAST()` function in SQL:
+Use `sql.date()` for date parameters with `YYYY-MM-DD` format strings.
+
+**Frontend - Using Date Parameters:**
 
 ```typescript
-// Date helper for query params
-const daysAgo = (n: number) => new Date(Date.now() - n * 86400000).toISOString().split('T')[0];
+import { sql } from '@databricks/app-kit-ui/js';
+import { useState } from 'react';
+
+function MyComponent() {
+  const [startDate, setStartDate] = useState<string>('2016-02-01');
+  const [endDate, setEndDate] = useState<string>('2016-02-29');
+
+  const queryParams = {
+    start_date: sql.date(startDate),  // Pass YYYY-MM-DD string to sql.date()
+    end_date: sql.date(endDate),
+  };
+
+  const { data } = useAnalyticsQuery('my_query', queryParams);
 
-const startDate = daysAgo(7);  // 7 days ago
+  // ...
+}
 ```
 
+**SQL - Date Filtering:**
+
 ```sql
--- SQL
-WHERE timestamp_column >= CAST(:start_date AS DATE)
+-- Filter by date range using DATE() function
+SELECT COUNT(*) as trip_count
+FROM samples.nyctaxi.trips
+WHERE DATE(tpep_pickup_datetime) >= :start_date
+  AND DATE(tpep_pickup_datetime) <= :end_date
+```
+
+**Date Helper Functions:**
+
+```typescript
+// Helper to get dates relative to today
+const daysAgo = (n: number) => {
+  const date = new Date(Date.now() - n * 86400000);
+  return sql.date(date)
+};
+
+const params = {
+  start_date: daysAgo(7),             // 7 days ago
+  end_date: sql.date(daysAgo(0)),     // Today
+};
 ```
 
 ### Optional Date Parameters - Use Sentinel Dates
@@ -132,10 +168,10 @@ Databricks App Kit validates parameter types before query execution. **DO NOT us
 // Frontend: Use sentinel dates for "no filter" instead of empty strings
 const revenueParams = {
   group_by: 'month',
-  start_date: '1900-01-01',  // Sentinel: effectively no lower bound
-  end_date: '9999-12-31',    // Sentinel: effectively no upper bound
-  country: country || '',
-  property_type: propertyType || '',
+  start_date: sql.date('1900-01-01'),  // Sentinel: effectively no lower bound
+  end_date: sql.date('9999-12-31'),    // Sentinel: effectively no upper bound
+  country: sql.string(country || ''),
+  property_type: sql.string(propertyType || ''),
 };
 ```
 
@@ -145,24 +181,15 @@ WHERE b.check_in >= CAST(:start_date AS DATE)
   AND b.check_in <= CAST(:end_date AS DATE)
 ```
 
-**❌ WRONG - Empty Strings Cause Validation Errors:**
-
-```typescript
-// ❌ DON'T DO THIS - causes "Invalid date format" error
-const params = {
-  start_date: '',  // Empty string triggers parameter validation error
-  end_date: '',
-};
-```
-
 **Why Sentinel Dates Work:**
 - `1900-01-01` is before any real data (effectively no lower bound filter)
 - `9999-12-31` is after any real data (effectively no upper bound filter)
 - Always valid DATE types, so no parameter validation errors
 - All real dates fall within this range, so no filtering occurs
 
 **Parameter Types Summary:**
+- ALWAYS use sql.* helper functions from the `@databricks/app-kit-ui/js` package to define SQL parameters
 - **Strings/Numbers**: Use directly in SQL with `:param_name`
-- **Dates**: Format as `YYYY-MM-DD`, use with `CAST(:param AS DATE)` in SQL
+- **Dates**: Use with `CAST(:param AS DATE)` in SQL
 - **Optional Strings**: Use empty string default, check with `(:param = '' OR column = :param)`
-- **Optional Dates**: Use sentinel dates (`'1900-01-01'` and `'9999-12-31'`) instead of empty strings
+- **Optional Dates**: Use sentinel dates (`sql.date('1900-01-01')` and `sql.date('9999-12-31')`) instead of empty strings