mcp-trino-v1.0.0

mcp-trino v1.0.0 — First Stable Release

v1.0.0 marks the project's first stable, production-ready release. The public library API (pkg/client, pkg/tools) is now considered stable under Go module semver guarantees.

---

What's New in v1.0.0

Human-Readable Tool Titles (Tool.Title)

All 8 tools now declare a Title field that MCP clients (Claude Desktop, etc.) display instead of the raw machine name.

Tool	Display title
trino_query	Execute SQL Query
trino_execute	Execute SQL (Write)
trino_explain	Explain Query Plan
trino_list_catalogs	List Catalogs
trino_list_schemas	List Schemas
trino_list_tables	List Tables
trino_describe_table	Describe Table
trino_list_connections	List Connections

Titles follow the same 3-level override pattern as descriptions, annotations, and icons:

// Per-registration (highest priority)
toolkit.RegisterWith(server, tools.ToolQuery,
    tools.WithTitle("Query the Retail Warehouse"),
)

// Toolkit-level (overrides default, overridden by per-registration)
toolkit := tools.NewToolkit(client, cfg,
    tools.WithTitles(map[tools.ToolName]string{
        tools.ToolQuery:   "Query Retail Warehouse",
        tools.ToolExplain: "Check Query Performance",
    }),
)

OpenWorldHint Corrected to true

All tools now correctly declare OpenWorldHint: true. Every tool communicates with an external Trino cluster — the previous false value was semantically incorrect per the MCP spec. This signals to clients that tool calls may interact with infrastructure outside the server's direct control.

OutputSchema via Typed Handlers

All tools already declare a typed OutputSchema automatically — the go-sdk infers it from the typed handler's output type at registration time. No configuration needed.

Go SDK Bump

Updated to github.com/modelcontextprotocol/go-sdk v1.3.1.

---

Full Feature Summary

Everything that ships in v1.0.0, accumulated across all prior releases:

Tools

Tool	Description
trino_query	Read-only SELECT/SHOW/DESCRIBE. Annotated ReadOnlyHint: true — clients can auto-approve. Enforced at the handler level; write SQL is rejected before it reaches Trino.
trino_execute	Unrestricted SQL including writes (INSERT, UPDATE, DELETE, CREATE, DROP, ALTER). Annotated DestructiveHint: true — clients will prompt for confirmation.
trino_explain	Returns the Trino execution plan for a query. Supports logical, distributed, io, and validate plan types.
trino_list_catalogs	Lists all catalogs in the connected Trino cluster.
trino_list_schemas	Lists all schemas in a catalog.
trino_list_tables	Lists all tables in a schema, with optional LIKE filter.
trino_describe_table	Returns column names, types, nullability, and optional sample rows. Enriched with semantic metadata when a provider is configured.
trino_list_connections	Lists all configured Trino server connections (multi-server mode).

Composable Library API

mcp-trino is designed to be imported as a library into your own MCP server, not just run standalone:

import (
    "github.com/txn2/mcp-trino/pkg/client"
    "github.com/txn2/mcp-trino/pkg/tools"
)

trinoClient, _ := client.New(client.FromEnv())
toolkit := tools.NewToolkit(trinoClient, tools.DefaultConfig())
toolkit.RegisterAll(yourMCPServer)

Middleware, Interceptors, and Transformers

Full extensibility stack for cross-cutting concerns:

toolkit := tools.NewToolkit(client, cfg,
    // Global middleware: Before/After hooks for every tool call
    tools.WithMiddleware(loggingMiddleware),
    tools.WithMiddleware(metricsMiddleware),

    // Per-tool middleware
    tools.WithToolMiddleware(tools.ToolExecute, authMiddleware),

    // SQL interceptors: transform or reject SQL before execution
    tools.WithQueryInterceptor(tenantIsolationInterceptor),
    tools.WithQueryInterceptor(auditInterceptor),

    // Result transformers: post-process tool output
    tools.WithResultTransformer(redactionTransformer),
)

Operator Overrides

All tool metadata is overridable without forking:

toolkit := tools.NewToolkit(client, cfg,
    tools.WithTitles(map[tools.ToolName]string{...}),
    tools.WithDescriptions(map[tools.ToolName]string{...}),
    tools.WithAnnotations(map[tools.ToolName]*mcp.ToolAnnotations{...}),
    tools.WithIcons(map[tools.ToolName][]mcp.Icon{...}),
)
// Or per-registration:
toolkit.RegisterWith(server, tools.ToolQuery,
    tools.WithTitle("..."),
    tools.WithDescription("..."),
    tools.WithAnnotation(&mcp.ToolAnnotations{...}),
    tools.WithIcon([]mcp.Icon{...}),
)

Typed Structured Outputs

All tool handlers return typed output structs as their second return value, enabling downstream consumers to access structured data without parsing text:

// Output types: QueryOutput, ExplainOutput, ListCatalogsOutput,
// ListSchemasOutput, ListTablesOutput, DescribeTableOutput, ListConnectionsOutput

Progress Notifications

Inject a ProgressNotifier via context to receive granular in-flight updates during query execution (useful for bridging to _meta.progressToken in MCP clients):

ctx = tools.WithProgressNotifier(ctx, myNotifier)
// handler calls Notify(0/3, "Executing..."), Notify(1/3, "N rows returned..."), Notify(2/3, "Complete")

Semantic Layer

Enrich schema discovery with business metadata from external catalogs (DataHub, Atlan, OpenMetadata, static YAML files). When a provider is configured, trino_describe_table and trino_list_tables return descriptions, owners, tags, sensitivity classifications, glossary terms, and data quality scores alongside raw Trino schema data.

toolkit := tools.NewToolkit(client, cfg,
    tools.WithSemanticProvider(datahub.New(datahub.FromEnv())),
    tools.WithSemanticCache(semantic.DefaultCacheConfig()),
)

Multi-Server Support

Connect to multiple Trino clusters and route queries by connection name:

mgr := multiserver.NewManager([]multiserver.ConnectionConfig{
    {Name: "prod", Host: "prod.trino.example.com", ...},
    {Name: "dev",  Host: "dev.trino.example.com",  ...},
})
toolkit := tools.NewToolkitWithManager(mgr, tools.DefaultConfig())

Extensions

Built-in extensions for common deployment patterns (opt-in via separate package):

• ReadOnlyInterceptor — block all write SQL; activate with MCP_TRINO_EXT_READONLY=true
• MaxRowsInterceptor — hard cap on rows returned regardless of client request
• YAMLSemanticProvider — file-based semantic layer with no external dependency

---

Breaking Changes from v0.x

• trino_query no longer accepts write SQL. Use trino_execute for INSERT, UPDATE, DELETE, CREATE, DROP, ALTER, and other write operations. Any application relying on trino_query for writes must switch to trino_execute.
• QueryStats.Duration was renamed to QueryStats.DurationMs and now correctly contains milliseconds (previously the field was named duration_ms but contained nanoseconds).

---

Installation

Claude Desktop (macOS / Windows)

Download the .mcpb bundle for your platform and double-click to install:

• macOS Apple Silicon (M1/M2/M3/M4): mcp-trino_1.0.0_darwin_arm64.mcpb
• macOS Intel: mcp-trino_1.0.0_darwin_amd64.mcpb
• Windows: mcp-trino_1.0.0_windows_amd64.mcpb

Homebrew (macOS)

brew install txn2/tap/mcp-trino

Claude Code CLI

claude mcp add trino \
  -e TRINO_HOST=your-trino-host \
  -e TRINO_USER=your-user \
  -- mcp-trino

Docker

docker pull ghcr.io/txn2/mcp-trino:v1.0.0
docker run --rm \
  -e TRINO_HOST=your-trino-host \
  -e TRINO_USER=your-user \
  ghcr.io/txn2/mcp-trino:v1.0.0

Go (as a library)

go get github.com/txn2/mcp-trino@v1.0.0

Environment Variables

Variable	Description	Default
TRINO_HOST	Trino server hostname	—
TRINO_PORT	Trino server port	443
TRINO_USER	Username (required)	—
TRINO_PASSWORD	Password	—
TRINO_CATALOG	Default catalog	—
TRINO_SCHEMA	Default schema	—
TRINO_SSL	Enable SSL	true
TRINO_TIMEOUT	Query timeout (seconds)	120

---

Artifact Verification

All release artifacts are signed with Cosign. Verify with:

cosign verify-blob \
  --bundle mcp-trino_1.0.0_linux_amd64.tar.gz.sigstore.json \
  mcp-trino_1.0.0_linux_amd64.tar.gz