MCP: Tweaks (#4055)

## Changes

* add aliases to `--warehouse`
* Improve app creation in planning mode
* Add more hints on parametrising datas in SQL

## 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

experimental/apps-mcp/cmd/init_template.go

@@ -185,10 +185,18 @@ After initialization:
 
 	cmd.Flags().StringVar(&name, "name", "", "Project name (required)")
 	cmd.Flags().StringVar(&warehouse, "warehouse", "", "SQL warehouse ID")
+	cmd.Flags().StringVar(&warehouse, "warehouse-id", "", "SQL warehouse ID (alias for --warehouse)")
+	cmd.Flags().StringVar(&warehouse, "sql-warehouse-id", "", "SQL warehouse ID (alias for --warehouse)")
+	cmd.Flags().StringVar(&warehouse, "sql_warehouse_id", "", "SQL warehouse ID (alias for --warehouse)")
 	cmd.Flags().StringVar(&description, "description", "", "App description")
 	cmd.Flags().StringVar(&outputDir, "output-dir", "", "Directory to write the initialized template to")
 	cmd.Flags().BoolVar(&describe, "describe", false, "Display template schema without initializing")
 
+	// Hide the alias flags from help
+	cmd.Flags().MarkHidden("warehouse-id")
+	cmd.Flags().MarkHidden("sql-warehouse-id")
+	cmd.Flags().MarkHidden("sql_warehouse_id")
+
 	cmd.PreRunE = root.MustWorkspaceClient
 	cmd.RunE = func(cmd *cobra.Command, args []string) error {
 		ctx := cmd.Context()

experimental/apps-mcp/lib/prompts/apps.tmpl

@@ -9,6 +9,21 @@
 DATABRICKS APPS DEVELOPMENT
 ============================
 
+When building or planning a new Databricks app, use the following steps:
+
+1. MUST start by scaffolding a new Databricks app using command: invoke_databricks_cli 'experimental apps-mcp tools init-template --name my-app-name --description "My app description"'
+   MUST run this command before planning the app. You must understand tge generated file structure and the purpose of the files.
+2. MUST read the CLAUDE.md file in the app directory.
+3. SHOULD run `npm install`, run `npm run dev` in the background, and open http://localhost:8000 in your browser before making changes to the app.
+4. MUST run `cd <project_name>` to navigate to the app directory. MUST execute all commands from this directory.
+4. If applicable, create SQL query files in the ./config/queries directory.
+5. If applicable, create tRPC endpoints in the ./server/trpc.ts file.
+6. If applicable, build UI components in the ./client/src directory.
+7. MUST update the ./client/src/App.tsx file
+8. MUST update smoke test in the ./tests/smoke.spec.ts file
+9. MUST run validation using command: invoke_databricks_cli 'experimental apps-mcp tools validate ./'
+10. USER CONSENT: Only deploy the app with explicit consent from the user. Deployment using command: invoke_databricks_cli 'experimental apps-mcp tools deploy'
+
 # Initialization
 
 ⚠️ ALWAYS start by scaffolding a new Databricks app using command:

experimental/apps-mcp/templates/appkit/template/{{.project_name}}/.gitignore.tmpl

@@ -1,4 +1,5 @@
 node_modules/
+client/dist/
 dist/
 build/
 .env

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

@@ -204,7 +204,8 @@ export const querySchemas = {
 
 - Parameters use colon prefix: `:parameter_name`
 - Databricks infers types from values automatically
-- For optional parameters, use pattern: `(:param = '' OR column = :param)`
+- For optional string parameters, use pattern: `(:param = '' OR column = :param)`
+- **For optional date parameters, use sentinel dates** (`'1900-01-01'` and `'9999-12-31'`) instead of empty strings (see Date Parameters section below)
 
 #### Frontend Parameter Passing:
 
@@ -219,7 +220,7 @@ const { data } = useAnalyticsQuery('filtered_data', {
 
 #### Date Parameters:
 
-For dates, use `YYYY-MM-DD` format in frontend, `DATE()` function in SQL:
+For dates, use `YYYY-MM-DD` format in frontend, `CAST()` function in SQL:
 
 ```typescript
 // Date helper for query params
@@ -230,13 +231,62 @@ const startDate = daysAgo(7);  // 7 days ago
 
 ```sql
 -- SQL
-WHERE DATE(timestamp_column) >= :start_date
+WHERE timestamp_column >= CAST(:start_date AS DATE)
 ```
 
+**⚠️ IMPORTANT: Optional Date Parameters - Use Sentinel Dates**
+
+Databricks App Kit validates parameter types before query execution. **DO NOT use empty strings (`''`) for optional date parameters** as this causes validation errors.
+
+**✅ CORRECT - Use Sentinel Dates:**
+
+```typescript
+// 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 || '',
+};
+```
+
+```sql
+-- SQL: Simple comparison since sentinel dates are always valid
+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: '',
+};
+```
+
+```sql
+-- ❌ DON'T DO THIS - even with conditional logic, validation happens first
+WHERE (:start_date = '' OR b.check_in >= CAST(:start_date AS 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
+
+**When to Use Real Dates vs Sentinel Dates:**
+- **Sentinel dates**: When you want "no filter" by default (e.g., show all time periods)
+- **Real dates**: When you have actual date pickers or filters that users can set
+
 **Parameter Types:**
 - **Strings/Numbers**: Use directly in SQL with `:param_name`
-- **Dates**: Format as `YYYY-MM-DD`, use with `DATE()` in SQL
-- **Optional**: Use empty string default, check with `(:param = '' OR column = :param)`
+- **Dates**: Format as `YYYY-MM-DD`, 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
 
 ## SQL Type Handling
 

experimental/apps-mcp/templates/appkit/template/{{.project_name}}/client/vite.config.ts

@@ -11,7 +11,7 @@ export default defineConfig({
     middlewareMode: true,
   },
   build: {
-    outDir: path.resolve(__dirname, '../dist/client'),
+    outDir: path.resolve(__dirname, './client/dist'),
     emptyOutDir: true,
   },
   optimizeDeps: {

experimental/apps-mcp/templates/appkit/template/{{.project_name}}/package.json

@@ -18,7 +18,7 @@
     "test:e2e": "playwright test",
     "test:e2e:ui": "playwright test --ui",
     "test:smoke": "playwright install chromium && playwright test tests/smoke.spec.ts",
-    "clean": "rm -rf client/dist build node_modules .smoke-test test-results playwright-report"
+    "clean": "rm -rf client/dist dist build node_modules .smoke-test test-results playwright-report"
   },
   "keywords": [],
   "author": "",