[PoC] aitools: Add SDK documentation query tool for MCP server

.claude/skills/sdk-docs/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: databricks-sdk-docs
+description: Use this skill when the user asks about Databricks SDK methods, API signatures, parameter types, return types, or how to use specific Databricks APIs programmatically. Triggers on questions like "how do I create a job", "what parameters does X take", "SDK method for Y", or "JobSettings fields".
+allowed-tools: mcp__databricks-mcp__databricks_query_sdk_docs
+---
+
+# Databricks SDK Documentation Skill
+
+When users ask about Databricks SDK usage, API methods, or type definitions, use the `databricks_query_sdk_docs` MCP tool to find accurate documentation.
+
+## When to Use This Skill
+
+- User asks "how do I create a job/cluster/pipeline using the SDK?"
+- User needs method signatures: "what's the signature for Jobs.Create?"
+- User asks about type fields: "what fields does CreateJob have?"
+- User needs enum values: "what are the possible run lifecycle states?"
+- User is confused about SDK API parameters or return types
+
+## How to Query
+
+Use the `databricks_query_sdk_docs` tool with these parameters:
+
+```json
+{
+  "query": "search terms",
+  "category": "methods|types|enums|services",  // optional filter
+  "service": "jobs|clusters|pipelines|...",    // optional filter
+  "limit": 10                                   // default 10, max 50
+}
+```
+
+## Example Queries
+
+| User Question | Tool Query |
+|---------------|------------|
+| "How do I create a job?" | `{"query": "create job", "category": "methods"}` |
+| "What fields does JobSettings have?" | `{"query": "JobSettings", "category": "types"}` |
+| "What are the run states?" | `{"query": "run lifecycle state", "category": "enums"}` |
+| "List all jobs API methods" | `{"query": "jobs", "service": "jobs", "category": "methods"}` |
+
+## Response Guidelines
+
+After querying, provide:
+1. The method signature with parameter types
+2. A brief description of what the method does
+3. Key parameters the user likely needs
+4. A simple code example if applicable
+
+Keep responses focused on what the user asked - don't dump all documentation.
+
+## CLI Fallback
+
+If MCP is unavailable, use the helper script:
+
+```bash
+# From the CLI repo root
+.claude/skills/sdk-docs/query-sdk-docs.sh "create job"
+.claude/skills/sdk-docs/query-sdk-docs.sh "JobSettings" types
+.claude/skills/sdk-docs/query-sdk-docs.sh "list" methods jobs 20
+```
+
+The script searches the embedded SDK docs index directly using `jq`.

.claude/skills/sdk-docs/query-sdk-docs.sh

@@ -0,0 +1,129 @@
+#!/usr/bin/env bash
+#
+# Query Databricks SDK documentation from the command line.
+# Usage: ./query-sdk-docs.sh <query> [category] [service] [limit]
+#
+# Examples:
+#   ./query-sdk-docs.sh "create job"
+#   ./query-sdk-docs.sh "JobSettings" types
+#   ./query-sdk-docs.sh "list" methods jobs
+#   ./query-sdk-docs.sh "cluster" methods compute 20
+#
+# Categories: methods, types, enums, services
+# Services: jobs, clusters, pipelines, workspace, etc.
+
+set -euo pipefail
+
+QUERY="${1:-}"
+CATEGORY="${2:-}"
+SERVICE="${3:-}"
+LIMIT="${4:-10}"
+
+if [[ -z "$QUERY" ]]; then
+    echo "Usage: $0 <query> [category] [service] [limit]"
+    echo ""
+    echo "Examples:"
+    echo "  $0 'create job'              # Search for 'create job'"
+    echo "  $0 'JobSettings' types       # Search types for 'JobSettings'"
+    echo "  $0 'list' methods jobs       # Search jobs service methods for 'list'"
+    echo ""
+    echo "Categories: methods, types, enums, services"
+    exit 1
+fi
+
+# Build the JSON input for the MCP tool
+build_json_input() {
+    local json="{\"query\": \"$QUERY\""
+
+    if [[ -n "$CATEGORY" ]]; then
+        json+=", \"category\": \"$CATEGORY\""
+    fi
+
+    if [[ -n "$SERVICE" ]]; then
+        json+=", \"service\": \"$SERVICE\""
+    fi
+
+    json+=", \"limit\": $LIMIT}"
+    echo "$json"
+}
+
+# Try to find the SDK docs index file for direct search
+SDK_DOCS_INDEX="${SDK_DOCS_INDEX:-}"
+if [[ -z "$SDK_DOCS_INDEX" ]]; then
+    # Look for the index in common locations
+    SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+    CLI_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd)"
+
+    POSSIBLE_PATHS=(
+        "$CLI_ROOT/experimental/aitools/lib/providers/sdkdocs/sdk_docs_index.json"
+        "./sdk_docs_index.json"
+    )
+
+    for path in "${POSSIBLE_PATHS[@]}"; do
+        if [[ -f "$path" ]]; then
+            SDK_DOCS_INDEX="$path"
+            break
+        fi
+    done
+fi
+
+# If we have jq and the index file, do a direct search
+if command -v jq &>/dev/null && [[ -n "$SDK_DOCS_INDEX" && -f "$SDK_DOCS_INDEX" ]]; then
+    echo "Searching SDK docs for: $QUERY"
+    echo "---"
+
+    QUERY_LOWER=$(echo "$QUERY" | tr '[:upper:]' '[:lower:]')
+
+    # Search methods
+    if [[ -z "$CATEGORY" || "$CATEGORY" == "methods" ]]; then
+        echo ""
+        echo "## Methods"
+        jq -r --arg q "$QUERY_LOWER" --arg svc "$SERVICE" '
+            .services | to_entries[] |
+            select($svc == "" or .key == $svc) |
+            .key as $service |
+            .value.methods // {} | to_entries[] |
+            select(
+                (.key | ascii_downcase | contains($q)) or
+                (.value.description // "" | ascii_downcase | contains($q))
+            ) |
+            "- \($service).\(.key): \(.value.description // "No description")[signature: \(.value.signature // "N/A")]"
+        ' "$SDK_DOCS_INDEX" 2>/dev/null | head -n "$LIMIT" || echo "  (no matches)"
+    fi
+
+    # Search types
+    if [[ -z "$CATEGORY" || "$CATEGORY" == "types" ]]; then
+        echo ""
+        echo "## Types"
+        jq -r --arg q "$QUERY_LOWER" '
+            .types // {} | to_entries[] |
+            select(
+                (.key | ascii_downcase | contains($q)) or
+                (.value.description // "" | ascii_downcase | contains($q))
+            ) |
+            "- \(.key): \(.value.description // "No description")"
+        ' "$SDK_DOCS_INDEX" 2>/dev/null | head -n "$LIMIT" || echo "  (no matches)"
+    fi
+
+    # Search enums
+    if [[ -z "$CATEGORY" || "$CATEGORY" == "enums" ]]; then
+        echo ""
+        echo "## Enums"
+        jq -r --arg q "$QUERY_LOWER" '
+            .enums // {} | to_entries[] |
+            select(
+                (.key | ascii_downcase | contains($q)) or
+                (.value.description // "" | ascii_downcase | contains($q))
+            ) |
+            "- \(.key): \(.value.values // [] | join(", "))"
+        ' "$SDK_DOCS_INDEX" 2>/dev/null | head -n "$LIMIT" || echo "  (no matches)"
+    fi
+else
+    # Fallback: show how to use the MCP tool
+    echo "SDK docs index not found locally. Use the MCP tool instead:"
+    echo ""
+    echo "databricks_query_sdk_docs with input:"
+    build_json_input
+    echo ""
+    echo "Or set SDK_DOCS_INDEX environment variable to point to sdk_docs_index.json"
+fi

experimental/aitools/lib/prompts/flow.tmpl

@@ -9,6 +9,7 @@
 - **databricks_discover**: MUST call first - returns scaffolding commands
 - **invoke_databricks_cli**: Execute CLI commands including init-template for scaffolding
 - **databricks_configure_auth**: Switch workspace profile/host
+- **databricks_query_sdk_docs**: Search SDK documentation for methods, types, and examples
 
 ## Critical Workflow Rules
 1. ALWAYS call databricks_discover FIRST to get scaffolding guidance

experimental/aitools/lib/providers/sdkdocs/index.go

@@ -0,0 +1,127 @@
+package sdkdocs
+
+import (
+	"embed"
+	"encoding/json"
+	"fmt"
+)
+
+//go:embed sdk_docs_index.json
+var indexFS embed.FS
+
+// SDKDocsIndex represents the complete SDK documentation index.
+type SDKDocsIndex struct {
+	Version     string                 `json:"version"`
+	GeneratedAt string                 `json:"generated_at"`
+	Services    map[string]*ServiceDoc `json:"services"`
+	Types       map[string]*TypeDoc    `json:"types"`
+	Enums       map[string]*EnumDoc    `json:"enums"`
+}
+
+// ServiceDoc represents documentation for an API service.
+type ServiceDoc struct {
+	Name        string                `json:"name"`
+	Description string                `json:"description"`
+	Package     string                `json:"package"`
+	Methods     map[string]*MethodDoc `json:"methods"`
+}
+
+// MethodDoc represents documentation for an API method.
+type MethodDoc struct {
+	Name        string      `json:"name"`
+	Description string      `json:"description"`
+	Signature   string      `json:"signature"`
+	Parameters  []ParamDoc  `json:"parameters"`
+	Returns     *ReturnDoc  `json:"returns,omitempty"`
+	Example     string      `json:"example,omitempty"`
+	HTTPMethod  string      `json:"http_method,omitempty"`
+	HTTPPath    string      `json:"http_path,omitempty"`
+}
+
+// ParamDoc represents documentation for a method parameter.
+type ParamDoc struct {
+	Name        string `json:"name"`
+	Type        string `json:"type"`
+	Description string `json:"description"`
+	Required    bool   `json:"required"`
+}
+
+// ReturnDoc represents documentation for a method return type.
+type ReturnDoc struct {
+	Type        string `json:"type"`
+	Description string `json:"description"`
+}
+
+// TypeDoc represents documentation for a data type.
+type TypeDoc struct {
+	Name        string               `json:"name"`
+	Package     string               `json:"package"`
+	Description string               `json:"description"`
+	Fields      map[string]*FieldDoc `json:"fields"`
+}
+
+// FieldDoc represents documentation for a struct field.
+type FieldDoc struct {
+	Name        string `json:"name"`
+	Type        string `json:"type"`
+	Description string `json:"description"`
+	Required    bool   `json:"required"`
+	OutputOnly  bool   `json:"output_only,omitempty"`
+	Deprecated  bool   `json:"deprecated,omitempty"`
+}
+
+// EnumDoc represents documentation for an enum type.
+type EnumDoc struct {
+	Name        string   `json:"name"`
+	Package     string   `json:"package"`
+	Description string   `json:"description"`
+	Values      []string `json:"values"`
+}
+
+// LoadIndex loads the embedded SDK documentation index.
+func LoadIndex() (*SDKDocsIndex, error) {
+	data, err := indexFS.ReadFile("sdk_docs_index.json")
+	if err != nil {
+		return nil, fmt.Errorf("failed to read embedded SDK docs index: %w", err)
+	}
+
+	var index SDKDocsIndex
+	if err := json.Unmarshal(data, &index); err != nil {
+		return nil, fmt.Errorf("failed to parse SDK docs index: %w", err)
+	}
+
+	return &index, nil
+}
+
+// GetMethod retrieves a method by its path (e.g., "jobs.Create").
+func (idx *SDKDocsIndex) GetMethod(serviceName, methodName string) *MethodDoc {
+	service, ok := idx.Services[serviceName]
+	if !ok {
+		return nil
+	}
+	return service.Methods[methodName]
+}
+
+// GetType retrieves a type by its full path (e.g., "jobs.CreateJob").
+func (idx *SDKDocsIndex) GetType(typePath string) *TypeDoc {
+	return idx.Types[typePath]
+}
+
+// GetEnum retrieves an enum by its full path.
+func (idx *SDKDocsIndex) GetEnum(enumPath string) *EnumDoc {
+	return idx.Enums[enumPath]
+}
+
+// GetService retrieves a service by name.
+func (idx *SDKDocsIndex) GetService(serviceName string) *ServiceDoc {
+	return idx.Services[serviceName]
+}
+
+// ListServices returns all service names.
+func (idx *SDKDocsIndex) ListServices() []string {
+	names := make([]string, 0, len(idx.Services))
+	for name := range idx.Services {
+		names = append(names, name)
+	}
+	return names
+}