feat: elicitation, icons, jsonrpc errors, and docs for MCP protocol capabilities (#112)

* feat: add elicitation, icons, client logging, progress, and docs

Complete Issue #102 implementation with documentation for all 6 MCP
protocol capability features: resource templates, progress
notifications, client logging, elicitation (cost estimation, PII
consent), icons middleware, and resource links.

Update middleware reference with 8-layer chain diagram, add config
sections to server and reference docs, update llms.txt and
llms-full.txt indexes.

* feat: use jsonrpc.Error sentinels for malformed request errors

Replace tool-level error results with protocol-level JSON-RPC errors
(CodeInvalidParams) for truly malformed requests in middleware. Auth and
authz failures remain as tool-level errors for better agent handling.

Author: cjimti

configs/platform.yaml

@@ -300,6 +300,34 @@ tuning:
 # client_logging:
 #   enabled: true
 
+# Elicitation (user confirmation prompts)
+# Requests user confirmation before expensive queries or PII access.
+# Requires client-side elicitation support (e.g., Claude Desktop).
+# Gracefully degrades to no-op if the client doesn't support elicitation.
+# elicitation:
+#   enabled: true
+#   cost_estimation:
+#     enabled: true
+#     row_threshold: 1000000    # prompt when EXPLAIN IO estimates > 1M rows
+#   pii_consent:
+#     enabled: true             # prompt when query accesses PII-tagged columns
+
+# Icons (tool/resource/prompt visual metadata)
+# Override or add icons to MCP list responses.
+# Upstream toolkits provide default icons; use this to customize.
+# icons:
+#   enabled: true
+#   tools:
+#     trino_query:
+#       src: "https://example.com/custom-trino.svg"
+#       mime_type: "image/svg+xml"
+#   resources:
+#     "schema://{catalog}.{schema}/{table}":
+#       src: "https://example.com/schema.svg"
+#   prompts:
+#     knowledge_capture:
+#       src: "https://example.com/knowledge.svg"
+
 # Audit logging
 audit:
   enabled: false

docs/llms-full.txt

@@ -32,6 +32,10 @@ The only requirement is DataHub (https://datahubproject.io/). Add Trino (https:/
 
 - **Client Logging**: Server-to-client log messages for platform decisions (enrichment, timing) via MCP `logging/setLevel` protocol. Zero overhead if the client hasn't opted in.
 
+- **Elicitation**: User confirmation prompts before expensive queries (EXPLAIN IO cost estimation) or PII access (sensitive column detection). Requires client-side elicitation support; gracefully degrades when unavailable.
+
+- **Icons**: Visual metadata for tools, resources, and prompts. Upstream toolkits provide default icons; deployers can override via configuration.
+
 ---
 
 # The Data Stack: DataHub + Trino + S3
@@ -321,6 +325,29 @@ When enabled, Trino query tools send three progress notifications per query: bef
 
 When enabled, the platform sends log notifications to clients after enrichment is applied (tool name, duration). Uses MCP `logging/setLevel` protocol — zero overhead if the client hasn't called `setLevel`.
 
+## Elicitation Configuration
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `elicitation.enabled` | bool | `false` | Enable user confirmation prompts |
+| `elicitation.cost_estimation.enabled` | bool | `false` | Prompt when EXPLAIN IO estimates exceed the row threshold |
+| `elicitation.cost_estimation.row_threshold` | int | `1000000` | Row estimate threshold for cost prompts |
+| `elicitation.pii_consent.enabled` | bool | `false` | Prompt when query accesses PII-tagged columns |
+
+Elicitation requires client-side support (MCP `elicitation/create` capability). When the client doesn't support it, elicitation gracefully degrades to a no-op. If a user declines the confirmation, the tool returns an informational message instead of executing the query.
+
+## Icons Configuration
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `icons.enabled` | bool | `false` | Enable icon injection middleware |
+| `icons.tools.<name>.src` | string | - | Icon URI for a tool |
+| `icons.tools.<name>.mime_type` | string | - | Icon MIME type |
+| `icons.resources.<uri>.src` | string | - | Icon URI for a resource template |
+| `icons.prompts.<name>.src` | string | - | Icon URI for a prompt |
+
+Upstream toolkits (Trino, DataHub, S3) provide default icons on all tools. This configuration overrides or adds icons for tools, resource templates, and prompts in list responses.
+
 ## Audit Configuration
 
 | Field | Type | Default | Description |

docs/llms.txt

@@ -11,7 +11,7 @@
 - [Home](index.md): Introduction, quick start, and key features
 - [Server Overview](server/overview.md): What the platform does, architecture, request flow
 - [Installation](server/installation.md): Install via go install, Homebrew, Docker, or from source
-- [Configuration](server/configuration.md): YAML configuration with environment variable expansion, config versioning (apiVersion field, version lifecycle, migrate-config CLI), config store options (file vs database mode), tool visibility filtering (allow/deny patterns for tools/list token reduction), resource templates, progress notifications, client logging, admin API and portal, database, audit, and session configuration
+- [Configuration](server/configuration.md): YAML configuration with environment variable expansion, config versioning (apiVersion field, version lifecycle, migrate-config CLI), config store options (file vs database mode), tool visibility filtering (allow/deny patterns for tools/list token reduction), resource templates, progress notifications, client logging, elicitation (cost estimation, PII consent), icons (tool/resource/prompt visual metadata), admin API and portal, database, audit, and session configuration
 - [Operating Modes](server/operating-modes.md): Three deployment modes — standalone (no database), full-config file + database, bootstrap + database config. Feature availability by mode, example configurations, decision guide
 - [Admin Portal](server/admin-portal.md): Built-in web dashboard for monitoring and managing the platform. Dashboard with activity timelines, performance percentiles, error monitoring. Tools overview with connection grid and tool inventory. Interactive tool explorer with semantic enrichment display. Searchable audit log with event detail drawer. Knowledge insight governance with approve/reject workflow and changeset tracking. Local dev with MSW mock data
 - [Admin API](server/admin-api.md): REST endpoints for system info, config management, personas, auth keys, audit, knowledge. Authentication, operating mode behavior, request/response reference. Interactive Swagger UI at `/api/v1/admin/docs/`
@@ -73,7 +73,7 @@
 - [Tools API](reference/tools-api.md): Complete tool specifications with parameters and responses
 - [Configuration](reference/configuration.md): Full YAML schema with all options
 - [Providers](reference/providers.md): Semantic, query, and storage provider interfaces
-- [Middleware](reference/middleware.md): Request processing chain including tool visibility middleware, client logging, progress notifications
+- [Middleware](reference/middleware.md): Request processing chain including tool visibility middleware, icon injection middleware, client logging, progress notifications
 
 ## Support
 

docs/reference/configuration.md

@@ -488,6 +488,72 @@ tools:
 
 No patterns configured means all tools are visible. When both are set, allow is evaluated first, then deny removes from the result. Patterns use `filepath.Match` syntax (`*` matches any sequence of characters).
 
+## Elicitation Configuration
+
+Elicitation prompts users for confirmation before expensive queries or when accessing PII-tagged columns. Requires client-side elicitation support (MCP `elicitation/create` capability). Gracefully degrades to a no-op if the client doesn't support it.
+
+```yaml
+elicitation:
+  enabled: true
+  cost_estimation:
+    enabled: true
+    row_threshold: 1000000
+  pii_consent:
+    enabled: true
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `elicitation.enabled` | bool | `false` | Master switch for elicitation |
+| `elicitation.cost_estimation.enabled` | bool | `false` | Prompt when EXPLAIN IO estimates exceed the row threshold |
+| `elicitation.cost_estimation.row_threshold` | int | `1000000` | Row estimate threshold for cost prompts |
+| `elicitation.pii_consent.enabled` | bool | `false` | Prompt when query accesses columns tagged as PII/sensitive |
+
+Elicitation is implemented as Trino toolkit middleware. When a user declines the prompt, the tool call returns an informational message instead of executing the query.
+
+## Icons Configuration
+
+Override or add icons to MCP `tools/list`, `resources/templates/list`, and `prompts/list` responses. Upstream toolkits (Trino, DataHub, S3) provide default icons; this configuration overrides them.
+
+```yaml
+icons:
+  enabled: true
+  tools:
+    trino_query:
+      src: "https://example.com/custom-trino.svg"
+      mime_type: "image/svg+xml"
+  resources:
+    "schema://{catalog}.{schema}/{table}":
+      src: "https://example.com/schema.svg"
+  prompts:
+    knowledge_capture:
+      src: "https://example.com/knowledge.svg"
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `icons.enabled` | bool | `false` | Enable icon injection middleware |
+| `icons.tools` | map | `{}` | Tool name to icon mapping |
+| `icons.resources` | map | `{}` | Resource template URI to icon mapping |
+| `icons.prompts` | map | `{}` | Prompt name to icon mapping |
+| `icons.*.src` | string | - | Icon source URI (HTTPS URL or data URI) |
+| `icons.*.mime_type` | string | - | Icon MIME type (e.g., `image/svg+xml`) |
+
+## Resource Links Configuration
+
+DataHub search results and entity responses automatically include MCP resource links when resource templates are enabled. These links allow clients to navigate directly to related schema, glossary, and availability resources.
+
+```yaml
+resources:
+  enabled: true
+```
+
+When `resources.enabled: true`, DataHub tools include links to:
+
+- `schema://{catalog}.{schema}/{table}` — table schema details
+- `glossary://{term}` — glossary term definitions
+- `availability://{catalog}.{schema}/{table}` — query availability status
+
 ## Admin API Configuration
 
 ```yaml
@@ -696,6 +762,15 @@ injection:
     enabled: true
     mode: reference
 
+resources:
+  enabled: true
+
+elicitation:
+  enabled: true
+  cost_estimation:
+    enabled: true
+    row_threshold: 1000000
+
 knowledge:
   enabled: true
   apply:

docs/reference/middleware.md

@@ -6,23 +6,27 @@ Middleware processes requests and responses at the MCP protocol level. Each midd
 
 ```mermaid
 graph LR
-    Request --> ToolVisibility
+    Request --> Icons
+    Icons --> ToolVisibility
     ToolVisibility --> AppsMetadata
     AppsMetadata --> MCPToolCall
     MCPToolCall --> MCPAudit
-    MCPAudit --> MCPRules
+    MCPAudit --> ClientLogging
+    ClientLogging --> MCPRules
     MCPRules --> MCPEnrichment
     MCPEnrichment --> Handler
     Handler --> MCPEnrichment
     MCPEnrichment --> MCPRules
-    MCPRules --> MCPAudit
+    MCPRules --> ClientLogging
+    ClientLogging --> MCPAudit
     MCPAudit --> MCPToolCall
     MCPToolCall --> AppsMetadata
     AppsMetadata --> ToolVisibility
-    ToolVisibility --> Response
+    ToolVisibility --> Icons
+    Icons --> Response
 ```
 
-The platform registers up to six middleware layers. Execution flows left-to-right for requests and right-to-left for responses.
+The platform registers up to eight middleware layers. Execution flows left-to-right for requests and right-to-left for responses.
 
 ## MCP Middleware Interface
 
@@ -197,6 +201,36 @@ func MCPToolVisibilityMiddleware(allow, deny []string) mcp.Middleware
 
 This is a **visibility filter**, not a security boundary. Persona-level tool filtering via MCPToolCallMiddleware continues to gate `tools/call` independently.
 
+### MCPIconMiddleware
+
+Injects config-driven icons into `tools/list`, `resources/templates/list`, and `prompts/list` responses. Upstream toolkits provide default icons; this middleware allows deployers to override or add custom icons via configuration.
+
+```go
+func MCPIconMiddleware(cfg IconsMiddlewareConfig) mcp.Middleware
+```
+
+**Behavior:**
+
+1. Intercepts list responses (`tools/list`, `resources/templates/list`, `prompts/list`)
+2. Matches tools/resources/prompts by name or URI
+3. Appends configured icons to matching entries
+4. Passes through all other methods unchanged
+
+Only registered when `icons.enabled: true` in configuration.
+
+### MCPClientLoggingMiddleware
+
+Sends server-to-client log messages via the MCP `logging/setLevel` protocol. Reports enrichment decisions, timing data, and platform diagnostics. Zero overhead if the client hasn't called `setLevel`.
+
+**Behavior:**
+
+1. Only active for `tools/call` requests
+2. Sends log messages using the server session's `LoggingMessage` method
+3. Messages include enrichment details, query timing, and semantic cache hits
+4. No-op if the client hasn't subscribed via `logging/setLevel`
+
+Only registered when `client_logging.enabled: true` in configuration.
+
 ### ToolMetadataMiddleware (MCP Apps)
 
 Injects `_meta.ui` fields into `tools/list` responses for tools that have associated MCP Apps.

docs/server/configuration.md

@@ -555,6 +555,112 @@ mcpapps:
 
 See [MCP Apps Configuration](../mcpapps/configuration.md) for complete options.
 
+## Resource Templates Configuration
+
+Resource templates expose platform data as browseable, parameterized MCP resources using RFC 6570 URI templates.
+
+```yaml
+resources:
+  enabled: true
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `enabled` | bool | `false` | Enable resource templates |
+
+When enabled, the platform registers these resource templates:
+
+- `schema://{catalog}.{schema}/{table}` — Table schema with column types and descriptions
+- `glossary://{term}` — Glossary term definitions
+- `availability://{catalog}.{schema}/{table}` — Query availability and row counts
+
+Clients that support resource browsing (e.g., Claude Desktop) will show these as navigable resources alongside tools.
+
+## Progress Notifications Configuration
+
+Progress notifications send granular updates to MCP clients during long-running Trino queries. The client must include `_meta.progressToken` in the request to receive updates.
+
+```yaml
+progress:
+  enabled: true
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `enabled` | bool | `false` | Enable progress notifications |
+
+When enabled, Trino query execution sends progress updates including rows scanned, bytes processed, and query stage information. Clients that don't send a `progressToken` receive no notifications (zero overhead).
+
+## Client Logging Configuration
+
+Client logging sends server-to-client log messages via the MCP `logging/setLevel` protocol. Messages include enrichment decisions, timing data, and platform diagnostics.
+
+```yaml
+client_logging:
+  enabled: true
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `enabled` | bool | `false` | Enable client logging |
+
+Zero overhead if the client hasn't subscribed via `logging/setLevel`. When active, log messages report semantic cache hits/misses, enrichment timing, and cross-injection decisions.
+
+## Elicitation Configuration
+
+Elicitation requests user confirmation before potentially expensive or sensitive operations. Requires client-side elicitation support (e.g., Claude Desktop). Gracefully degrades to a no-op if the client doesn't support elicitation.
+
+```yaml
+elicitation:
+  enabled: true
+  cost_estimation:
+    enabled: true
+    row_threshold: 1000000
+  pii_consent:
+    enabled: true
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `enabled` | bool | `false` | Enable elicitation |
+| `cost_estimation.enabled` | bool | `false` | Prompt before expensive queries |
+| `cost_estimation.row_threshold` | int | `1000000` | Row count threshold from `EXPLAIN` IO estimates |
+| `pii_consent.enabled` | bool | `false` | Prompt when query accesses PII-tagged columns |
+
+!!! note "Client support required"
+    Elicitation uses the MCP `elicitation/create` capability. Clients that don't support elicitation will not receive prompts — queries proceed without confirmation.
+
+## Icons Configuration
+
+Icons add visual metadata to tools, resources, and prompts in MCP list responses. Upstream toolkits (Trino, DataHub, S3) provide default icons; this configuration overrides or extends them.
+
+```yaml
+icons:
+  enabled: true
+  tools:
+    trino_query:
+      src: "https://example.com/custom-trino.svg"
+      mime_type: "image/svg+xml"
+  resources:
+    "schema://{catalog}.{schema}/{table}":
+      src: "https://example.com/schema.svg"
+  prompts:
+    knowledge_capture:
+      src: "https://example.com/knowledge.svg"
+```
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `enabled` | bool | `false` | Enable icon injection middleware |
+| `tools` | map | - | Icon overrides keyed by tool name |
+| `resources` | map | - | Icon overrides keyed by resource URI |
+| `prompts` | map | - | Icon overrides keyed by prompt name |
+| `*.src` | string | - | Icon source URL |
+| `*.mime_type` | string | - | Icon MIME type (e.g., `image/svg+xml`) |
+
+!!! tip "Default icons"
+    Each upstream toolkit provides a default icon for all its tools. You only need this configuration if you want to customize or override those defaults.
+
 ## Environment Variables
 
 Common environment variables:
@@ -663,6 +769,21 @@ injection:
   datahub_query_enrichment: true
   s3_semantic_enrichment: true
 
+resources:
+  enabled: true
+
+progress:
+  enabled: true
+
+client_logging:
+  enabled: true
+
+elicitation:
+  enabled: true
+  cost_estimation:
+    enabled: true
+    row_threshold: 1000000
+
 personas:
   definitions:
     analyst:
@@ -688,3 +809,4 @@ personas:
 - [Authentication](../auth/overview.md) - Add authentication
 - [Personas](../personas/overview.md) - Role-based access control
 - [MCP Apps](../mcpapps/overview.md) - Interactive UI for tool results
+- [Middleware Reference](../reference/middleware.md) - Request processing chain details