feat: add resource templates, progress notifications, and client logging (#111)

Implements Phases 3 and 4 of the MCP protocol capabilities expansion
(#102). Resource templates expose platform data as browseable RFC 6570
URI resources. Progress notifications provide real-time feedback during
long-running Trino queries. Client logging sends enrichment decisions
to MCP clients that opt in via setLevel.

Phase 3 — Resource Templates:
- schema://{catalog}.{schema}/{table} — merged query + semantic schema
- glossary://{term} — glossary term definitions from semantic provider
- availability://{catalog}.{schema}/{table} — query availability info
- URI variable parsing via uritemplate/v3 library
- All templates gated by resources.enabled config

Phase 4 — Progress Notifications & Client Logging:
- MCPProgressNotifier adapter bridges ServerSession.NotifyProgress()
  to mcp-trino ProgressNotifier interface via ToolMiddleware injection
- Three granular progress points in query handler (0/3, 1/3, 2/3)
- ServerSession + progress token context propagation in MCP middleware
- Client logging middleware emits enrichment info after semantic
  enrichment runs, silent no-op when client hasn't called setLevel
- New pkg/mcpcontext package breaks import cycle between middleware
  and toolkits/trino for shared context keys

Dependency: mcp-trino v0.6.1 (ProgressNotifier interface)

Author: cjimti

README.md

@@ -113,6 +113,15 @@ Every tool call is logged with user identity, persona, request details, and timi
 ### Knowledge Capture
 AI sessions generate valuable domain knowledge: column meanings, data quality issues, business rules. The `capture_insight` tool records these observations during sessions, and `apply_knowledge` provides admins with a structured review workflow. Approved insights are written back to DataHub with full changeset tracking and rollback. An [Admin REST API](https://txn2.github.io/mcp-data-platform/knowledge/admin-api/) supports integration with existing governance tools. See the [Knowledge Capture documentation](https://txn2.github.io/mcp-data-platform/knowledge/overview/) for details.
 
+### Resource Templates
+Browse platform data as parameterized MCP resources using RFC 6570 URI templates. Three built-in templates expose table schemas (`schema://catalog.schema/table`), glossary terms (`glossary://term`), and data availability (`availability://catalog.schema/table`) without making tool calls.
+
+### Progress Notifications
+Long-running Trino queries send granular progress updates to MCP clients (executing, formatting, complete). Clients that provide a `_meta.progressToken` receive real-time status. Zero overhead when disabled.
+
+### Client Logging
+Server-to-client log messages give AI agents visibility into platform decisions (enrichment applied, timing). Uses the MCP `logging/setLevel` protocol — zero overhead if the client hasn't opted in.
+
 ### Extensible Middleware Architecture
 Add custom authentication, rate limiting, or logging. Swap providers to integrate different semantic layers or query engines. The Go library exposes everything—build the platform your organization needs.
 
@@ -367,6 +376,7 @@ database:
 | `pkg/semantic` | Semantic metadata provider abstraction |
 | `pkg/query` | Query execution provider abstraction |
 | `pkg/middleware` | Request/response middleware chain |
+| `pkg/mcpcontext` | MCP session/progress context helpers |
 | `pkg/registry` | Toolkit registration and management |
 | `pkg/audit` | Audit logging with PostgreSQL storage |
 | `pkg/tuning` | Prompts, hints, and operational rules |

configs/platform.yaml

@@ -280,6 +280,26 @@ tuning:
 #   persona: admin              # persona required for admin access (default: "admin")
 #   path_prefix: /api/v1/admin  # URL prefix for admin endpoints
 
+# Resource templates (RFC 6570 URI templates)
+# Exposes platform data as browseable, parameterized MCP resources.
+# Templates: schema://{catalog}.{schema}/{table}, glossary://{term},
+#            availability://{catalog}.{schema}/{table}
+# resources:
+#   enabled: true
+
+# Progress notifications
+# Sends granular progress updates to MCP clients during long-running
+# Trino queries (requires client to send _meta.progressToken).
+# progress:
+#   enabled: true
+
+# Client logging
+# Sends server-to-client log messages (enrichment decisions, timing)
+# via MCP logging/setLevel protocol. Zero overhead if client hasn't
+# called setLevel.
+# client_logging:
+#   enabled: true
+
 # Audit logging
 audit:
   enabled: false

docs/llms-full.txt

@@ -26,6 +26,12 @@ The only requirement is DataHub (https://datahubproject.io/). Add Trino (https:/
 
 - **Personas**: Define who can use which tools. Analysts get read access. Admins get everything. Map from your identity provider's roles.
 
+- **Resource Templates**: Browse platform data as parameterized MCP resources using RFC 6570 URI templates. Three built-in templates: table schemas (`schema://catalog.schema/table`), glossary terms (`glossary://term`), and data availability (`availability://catalog.schema/table`).
+
+- **Progress Notifications**: Long-running Trino queries send granular progress updates (executing, formatting, complete) to clients that provide `_meta.progressToken`. Zero overhead when disabled.
+
+- **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.
+
 ---
 
 # The Data Stack: DataHub + Trino + S3
@@ -288,6 +294,33 @@ No patterns configured means all tools are visible. When both are set, allow is
 
 When `admin.portal: true`, an interactive web dashboard is served at the admin path prefix. It provides audit log exploration, tool execution testing, and system monitoring.
 
+## Resource Templates Configuration
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `resources.enabled` | bool | `false` | Enable MCP resource templates |
+
+When enabled, three RFC 6570 URI templates are registered:
+- `schema://{catalog}.{schema_name}/{table}` — Table schema with semantic context
+- `glossary://{term}` — Glossary term definition and related assets
+- `availability://{catalog}.{schema_name}/{table}` — Data availability status and row count
+
+## Progress Notifications Configuration
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `progress.enabled` | bool | `false` | Enable progress notifications for Trino queries |
+
+When enabled, Trino query tools send three progress notifications per query: before execution, after query returns, and after formatting. Clients must include `_meta.progressToken` in their tool call to receive notifications.
+
+## Client Logging Configuration
+
+| Field | Type | Default | Description |
+|-------|------|---------|-------------|
+| `client_logging.enabled` | bool | `false` | Enable server-to-client log messages |
+
+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`.
+
 ## Audit Configuration
 
 | Field | Type | Default | Description |
@@ -1001,6 +1034,7 @@ Use the library when you need to:
 | `pkg/semantic` | Semantic provider interface |
 | `pkg/query` | Query provider interface |
 | `pkg/middleware` | Request/response processing |
+| `pkg/mcpcontext` | MCP session/progress context helpers |
 | `pkg/persona` | Role-based tool filtering |
 | `pkg/auth` | OIDC and API key validation |
 | `pkg/admin` | Admin REST API for knowledge management |

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), 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, 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
+- [Middleware](reference/middleware.md): Request processing chain including tool visibility middleware, client logging, progress notifications
 
 ## Support
 

go.mod

@@ -16,7 +16,8 @@ require (
 	github.com/testcontainers/testcontainers-go/modules/postgres v0.40.0
 	github.com/txn2/mcp-datahub v0.7.0
 	github.com/txn2/mcp-s3 v0.2.0
-	github.com/txn2/mcp-trino v0.5.0
+	github.com/txn2/mcp-trino v0.6.1
+	github.com/yosida95/uritemplate/v3 v3.0.2
 	golang.org/x/crypto v0.48.0
 	gopkg.in/yaml.v3 v3.0.1
 )
@@ -102,7 +103,6 @@ require (
 	github.com/tklauser/go-sysconf v0.3.12 // indirect
 	github.com/tklauser/numcpus v0.6.1 // indirect
 	github.com/trinodb/trino-go-client v0.333.0 // indirect
-	github.com/yosida95/uritemplate/v3 v3.0.2 // indirect
 	github.com/yusufpapurcu/wmi v1.2.4 // indirect
 	go.opentelemetry.io/auto/sdk v1.2.1 // indirect
 	go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp v0.61.0 // indirect

go.sum

@@ -268,8 +268,8 @@ github.com/txn2/mcp-datahub v0.7.0 h1:gzBGJmYzjy7GBB0HGXm4o6pZdvVrPrhVbNEC3c5fpX
 github.com/txn2/mcp-datahub v0.7.0/go.mod h1:UyXoTLT9H5DFkrdi/k0G82x+fZN5N4PSjom6FPGTkI0=
 github.com/txn2/mcp-s3 v0.2.0 h1:hycUsa8j6hz1rHDIr0OOe6wbDxW/aJgrCYTvqrAcgSM=
 github.com/txn2/mcp-s3 v0.2.0/go.mod h1:ygY1Bz6aXO4/3jvhfooR6y/BTXJ35Rsvwsl75zKktXg=
-github.com/txn2/mcp-trino v0.5.0 h1:xxJ8kDVNbNVvWajQYuID96ywbppcRMhO+f/VxNpODwI=
-github.com/txn2/mcp-trino v0.5.0/go.mod h1:6m5jlHTExGTr2swFRFp2McDBHti8l/F7mHi2b1cYHk4=
+github.com/txn2/mcp-trino v0.6.1 h1:IZnBlyccHXftIfiKZciltRvQ/JtOPEz8Bxa4CxfwB7A=
+github.com/txn2/mcp-trino v0.6.1/go.mod h1:6m5jlHTExGTr2swFRFp2McDBHti8l/F7mHi2b1cYHk4=
 github.com/xeipuuv/gojsonpointer v0.0.0-20190905194746-02993c407bfb h1:zGWFAtiMcyryUHoUjUJX0/lt1H2+i2Ka2n+D3DImSNo=
 github.com/xeipuuv/gojsonpointer v0.0.0-20190905194746-02993c407bfb/go.mod h1:N2zxlSyiKSe5eX1tZViRH5QA0qijqEDrYZiPEAiq3wU=
 github.com/xeipuuv/gojsonreference v0.0.0-20180127040603-bd5ef7bd5415 h1:EzJWgHovont7NscjpAxXsDA8S8BMYve8Y5+7cuRE7R0=

pkg/mcpcontext/mcpcontext.go

@@ -0,0 +1,39 @@
+// Package mcpcontext provides context helpers for MCP session state.
+// These are in a separate package to avoid import cycles between
+// middleware and toolkit packages.
+package mcpcontext
+
+import (
+	"context"
+
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+)
+
+// contextKey is a private type for context keys.
+type contextKey int
+
+const (
+	serverSessionKey contextKey = iota
+	progressTokenKey
+)
+
+// WithServerSession adds a ServerSession to the context.
+func WithServerSession(ctx context.Context, ss *mcp.ServerSession) context.Context {
+	return context.WithValue(ctx, serverSessionKey, ss)
+}
+
+// GetServerSession retrieves the ServerSession from the context.
+func GetServerSession(ctx context.Context) *mcp.ServerSession {
+	ss, _ := ctx.Value(serverSessionKey).(*mcp.ServerSession)
+	return ss
+}
+
+// WithProgressToken adds a progress token to the context.
+func WithProgressToken(ctx context.Context, token any) context.Context {
+	return context.WithValue(ctx, progressTokenKey, token)
+}
+
+// GetProgressToken retrieves the progress token from the context.
+func GetProgressToken(ctx context.Context) any {
+	return ctx.Value(progressTokenKey)
+}

pkg/mcpcontext/mcpcontext_test.go

@@ -0,0 +1,58 @@
+package mcpcontext
+
+import (
+	"context"
+	"testing"
+
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+)
+
+func TestServerSessionContext(t *testing.T) {
+	t.Run("not set returns nil", func(t *testing.T) {
+		got := GetServerSession(context.Background())
+		if got != nil {
+			t.Error("expected nil for empty context")
+		}
+	})
+
+	t.Run("nil session stored", func(t *testing.T) {
+		ctx := WithServerSession(context.Background(), (*mcp.ServerSession)(nil))
+		got := GetServerSession(ctx)
+		if got != nil {
+			t.Error("expected nil for nil *ServerSession stored in context")
+		}
+	})
+}
+
+func TestProgressTokenContext(t *testing.T) {
+	t.Run("round-trip string token", func(t *testing.T) {
+		ctx := WithProgressToken(context.Background(), "tok-123")
+		got := GetProgressToken(ctx)
+		if got != "tok-123" {
+			t.Errorf("GetProgressToken() = %v, want %q", got, "tok-123")
+		}
+	})
+
+	t.Run("round-trip int token", func(t *testing.T) {
+		ctx := WithProgressToken(context.Background(), 42)
+		got := GetProgressToken(ctx)
+		if got != 42 {
+			t.Errorf("GetProgressToken() = %v, want %d", got, 42)
+		}
+	})
+
+	t.Run("not set returns nil", func(t *testing.T) {
+		got := GetProgressToken(context.Background())
+		if got != nil {
+			t.Errorf("GetProgressToken() = %v, want nil", got)
+		}
+	})
+
+	t.Run("nil token stored", func(t *testing.T) {
+		ctx := WithProgressToken(context.Background(), nil)
+		got := GetProgressToken(ctx)
+		if got != nil {
+			t.Errorf("GetProgressToken() = %v, want nil", got)
+		}
+	})
+}

pkg/middleware/context.go

@@ -4,6 +4,10 @@ package middleware
 import (
 	"context"
 	"time"
+
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+
+	"github.com/txn2/mcp-data-platform/pkg/mcpcontext"
 )
 
 // contextKey is a private type for context keys.
@@ -94,3 +98,27 @@ func GetToken(ctx context.Context) string {
 	}
 	return ""
 }
+
+// WithServerSession adds a ServerSession to the context.
+// Delegates to mcpcontext to share context keys with toolkit packages.
+func WithServerSession(ctx context.Context, ss *mcp.ServerSession) context.Context {
+	return mcpcontext.WithServerSession(ctx, ss)
+}
+
+// GetServerSession retrieves the ServerSession from the context.
+// Delegates to mcpcontext to share context keys with toolkit packages.
+func GetServerSession(ctx context.Context) *mcp.ServerSession {
+	return mcpcontext.GetServerSession(ctx)
+}
+
+// WithProgressToken adds a progress token to the context.
+// Delegates to mcpcontext to share context keys with toolkit packages.
+func WithProgressToken(ctx context.Context, token any) context.Context {
+	return mcpcontext.WithProgressToken(ctx, token)
+}
+
+// GetProgressToken retrieves the progress token from the context.
+// Delegates to mcpcontext to share context keys with toolkit packages.
+func GetProgressToken(ctx context.Context) any {
+	return mcpcontext.GetProgressToken(ctx)
+}

pkg/middleware/context_test.go

@@ -3,6 +3,8 @@ package middleware
 import (
 	"context"
 	"testing"
+
+	"github.com/modelcontextprotocol/go-sdk/mcp"
 )
 
 func TestPlatformContext(t *testing.T) {
@@ -90,3 +92,56 @@ func TestTokenContext(t *testing.T) {
 		}
 	})
 }
+
+func TestServerSessionContext(t *testing.T) {
+	t.Run("round-trip", func(t *testing.T) {
+		// We can't construct a real ServerSession (private fields), but we can
+		// verify nil handling and type safety of the context helpers.
+		ctx := context.Background()
+		got := GetServerSession(ctx)
+		if got != nil {
+			t.Error("expected nil for empty context")
+		}
+	})
+
+	t.Run("nil session stored", func(t *testing.T) {
+		ctx := WithServerSession(context.Background(), (*mcp.ServerSession)(nil))
+		got := GetServerSession(ctx)
+		if got != nil {
+			t.Error("expected nil for nil *ServerSession stored in context")
+		}
+	})
+}
+
+func TestProgressTokenContext(t *testing.T) {
+	t.Run("round-trip string token", func(t *testing.T) {
+		ctx := WithProgressToken(context.Background(), "tok-123")
+		got := GetProgressToken(ctx)
+		if got != "tok-123" {
+			t.Errorf("GetProgressToken() = %v, want %q", got, "tok-123")
+		}
+	})
+
+	t.Run("round-trip int token", func(t *testing.T) {
+		ctx := WithProgressToken(context.Background(), 42)
+		got := GetProgressToken(ctx)
+		if got != 42 {
+			t.Errorf("GetProgressToken() = %v, want %d", got, 42)
+		}
+	})
+
+	t.Run("not set returns nil", func(t *testing.T) {
+		got := GetProgressToken(context.Background())
+		if got != nil {
+			t.Errorf("GetProgressToken() = %v, want nil", got)
+		}
+	})
+
+	t.Run("nil token stored", func(t *testing.T) {
+		ctx := WithProgressToken(context.Background(), nil)
+		got := GetProgressToken(ctx)
+		if got != nil {
+			t.Errorf("GetProgressToken() = %v, want nil", got)
+		}
+	})
+}