mcp-trino-v1.2.0

mcp-trino v1.2.0 — Dynamic Connection Management

v1.2.0 adds runtime connection management to multiserver.Manager, enabling downstream projects to add and remove Trino connections without restarting the server. This release also removes the premature deprecation subsystem and resolves all outstanding lint issues.

---

New Features

Dynamic Connection Management

The multiserver.Manager now supports adding and removing Trino connections at runtime:

import "github.com/txn2/mcp-trino/pkg/multiserver"

mgr, _ := multiserver.NewManagerFromEnv()
toolkit := tools.NewToolkitWithManager(mgr, tools.DefaultConfig())

// Add a connection at runtime
mgr.AddConnection("analytics", multiserver.ConnectionConfig{
    Host:    "analytics.trino.example.com",
    Catalog: "iceberg",
})

// Remove a connection (closes any cached client)
mgr.RemoveConnection("analytics")

AddConnection(name string, conn ConnectionConfig) error

• Adds or replaces a named connection configuration
• Closes any cached client so a fresh connection is created on next access
• Returns error if name is empty or matches the default connection

RemoveConnection(name string) error

• Removes a connection and closes its cached client
• Returns error if the connection doesn't exist or is the default

Both methods are fully thread-safe. All read-path methods (Connections, ConnectionInfos, ConnectionCount, HasConnection, Config) now also hold RLock for safe concurrent use with mutations.

---

Breaking Changes

Deprecation subsystem removed

The following types, fields, and functions have been removed:

Removed	Package
Deprecation struct	pkg/semantic
TableContext.Deprecation field	pkg/semantic
SearchFilter.IncludeDeprecated field	pkg/semantic
formatDeprecation()	pkg/tools
matchesDeprecation()	pkg/semantic/providers/static
mapDeprecation()	pkg/semantic/providers/datahub
deprecationData struct	pkg/semantic/providers/datahub
TableEntry.Deprecated, .DeprecationNote, .ReplacedBy fields	pkg/semantic/providers/static

Migration: Remove any references to these types from your code. If you were setting IncludeDeprecated: true on SearchFilter, remove that field — all tables are now always included.

The deprecation field has also been removed from the DataHub GraphQL query and from static YAML file parsing. YAML files with deprecated, deprecation_note, or replaced_by fields will still parse without error (unknown fields are ignored), but the values will have no effect.

---

Fixes

• Lint: Fixed gosec G706 false positives in server.go (operator-controlled env var in log format string)
• Lint: Replaced WriteString(fmt.Sprintf(...)) with fmt.Fprintf(...) across schema.go (staticcheck QF1012)
• CI: Bumped golangci-lint from v2.1.6 to v2.11.4 for Go 1.25 compatibility

Dependency Updates

• github.com/modelcontextprotocol/go-sdk bumped (2 updates)
• GitHub Actions group bumped (3 updates, 9 actions total)

Documentation

• Added "Dynamic Connections" section to multi-server docs
• Updated library quickstart with correct multiserver.Manager API
• Removed all deprecation references from README, semantic docs, and tool docs

---

Full Changelog: v1.1.0...v1.2.0

mcp-trino-v1.1.0

mcp-trino v1.1.0 — Consolidated Catalog Browsing

v1.1.0 consolidates the three hierarchical navigation tools into a single, parameterized trino_browse tool. This reduces the tool count from 8 to 6 while preserving all functionality, freeing tool slots for future capabilities.

---

Breaking Changes

This release removes three tool names with no aliases or deprecation period:

Removed tool	Replacement
trino_list_catalogs	trino_browse (no parameters)
trino_list_schemas	trino_browse with catalog
trino_list_tables	trino_browse with catalog + schema

Migration guide

MCP clients (Claude Desktop, Claude Code, etc.): Update any tool references in prompts or configurations. The new tool is auto-discovered; no manual registration changes are needed for end users.

Library consumers (pkg/tools importers):

• Replace tools.ToolListCatalogs, tools.ToolListSchemas, tools.ToolListTables constants with tools.ToolBrowse
• Replace tools.ListCatalogsInput, tools.ListSchemasInput, tools.ListTablesInput structs with tools.BrowseInput
• Replace tools.ListCatalogsOutput, tools.ListSchemasOutput, tools.ListTablesOutput structs with tools.BrowseOutput
• AllTools() now returns 6 tools (was 8); SchemaTools() returns 2 (was 4)

Structured output changes

The three separate output types are replaced by a single unified BrowseOutput:

{
  "level": "tables",
  "catalog": "hive",
  "schema": "sales",
  "items": ["customers", "orders", "order_items"],
  "count": 3,
  "pattern": "%order%"
}

• level indicates the browsing mode: "catalogs", "schemas", or "tables"
• items replaces the type-specific fields (catalogs, schemas, tables)
• catalog, schema, and pattern are omitted when not applicable

---

New: trino_browse Tool

Browse the Trino catalog hierarchy with a single tool. The browsing level is determined by which parameters are provided:

Parameters	Action
(none)	List all catalogs
catalog	List schemas in that catalog
catalog + schema	List tables in that schema
catalog + schema + pattern	List tables matching a SQL LIKE pattern

Input validation

Input	Error
schema without catalog	"schema requires catalog"
pattern without catalog + schema	"pattern requires both catalog and schema"

Pattern filtering

The pattern parameter supports standard SQL LIKE syntax:

Pattern	Matches
order%	Tables starting with "order"
%log	Tables ending with "log"
%event%	Tables containing "event"
user_	5-character tables starting with "user" (_ = single character)

Annotations

trino_browse carries the same MCP annotations as the tools it replaces: ReadOnlyHint: true, IdempotentHint: true, OpenWorldHint: true.

---

Tool Summary (v1.1.0)

Tool	Display Title	Description
trino_query	Execute SQL Query	Execute read-only SQL (SELECT/SHOW/DESCRIBE)
trino_execute	Execute SQL (Write)	Execute any SQL including write operations
trino_explain	Explain Query Plan	Get execution plans
trino_browse	Browse Catalog Hierarchy	Browse catalogs, schemas, or tables
trino_describe_table	Describe Table	Get columns, sample data, and semantic context
trino_list_connections	List Connections	List configured server connections

---

Stats

• 28 files changed across code, tests, and documentation
• Net reduction of ~290 lines (543 added, 830 removed)
• All existing tests updated; new browse-specific test suite added
• Full documentation refresh across README, CLAUDE.md, mkdocs site, and API reference

---

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.1.0_darwin_arm64.mcpb
• macOS Intel: mcp-trino_1.1.0_darwin_amd64.mcpb
• Windows: mcp-trino_1.1.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.1.0

Verification

All release artifacts are signed with Cosign. Verify with:

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

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

mcp-trino-v0.8.0

What's New

Read-Only trino_query and New trino_execute Tool

trino_query is now strictly read-only. Write operations (INSERT, UPDATE, DELETE, CREATE, DROP, ALTER, TRUNCATE, GRANT, REVOKE, MERGE, CALL) are rejected before they reach Trino, with a clear error message directing users to the new trino_execute tool.

The new trino_execute tool handles all write operations without restrictions.

Before (v0.7.x):

• trino_query could run both reads and writes — MCP clients had no way to know which calls were safe

After (v0.8.0):

• trino_query — read-only, annotated with ReadOnlyHint: true — MCP clients can auto-approve
• trino_execute — unrestricted, annotated with DestructiveHint: true — MCP clients will prompt for confirmation

MCP Tool Annotations

Both tools now carry proper MCP annotations so AI clients can make informed decisions about auto-approval:

Tool	ReadOnlyHint	DestructiveHint	IdempotentHint
trino_query	true	-	true
trino_execute	-	true	-

Write Detection

Write SQL is detected by matching statement-initial keywords, handling:

• Case-insensitive matching (INSERT, insert, Insert)
• Leading whitespace and tabs
• SQL comments (-- comment and /* block */) before the keyword
• All 12 write keywords: INSERT, UPDATE, DELETE, DROP, CREATE, ALTER, TRUNCATE, GRANT, REVOKE, MERGE, CALL, EXECUTE

The detection is exposed as a public IsWriteSQL() function for use in custom middleware and interceptors.

Three Layers of Write Control

1. Tool semantics (this release) — trino_query always rejects writes, trino_execute always allows them
2. Instance-level ReadOnly interceptor — when MCP_TRINO_EXT_READONLY=true, blocks writes on both trino_query and trino_execute
3. Custom interceptors — add your own QueryInterceptor for tenant isolation, audit, or policy enforcement

For Library Users

If you import mcp-trino as a Go library, the new tool registers automatically via RegisterAll(). No code changes required.

// trino_execute is registered alongside trino_query
toolkit := tools.NewToolkit(client, tools.DefaultConfig())
toolkit.RegisterAll(server) // registers all 8 tools including trino_execute

To use IsWriteSQL() in custom middleware:

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

if tools.IsWriteSQL(sql) {
    // handle write operation
}

Breaking Changes

• trino_query now rejects write SQL that it previously accepted. If you have workflows that use trino_query for writes, switch them to trino_execute.
• AllTools() returns 8 tools (was 7). QueryTools() returns 3 (was 2).

Files Changed

File	Change
pkg/tools/execute.go	New — trino_execute handler and ExecuteInput type
pkg/tools/query.go	Add IsWriteSQL(), writePattern regex, read-only enforcement in handleQuery
pkg/tools/names.go	Add ToolExecute constant, update AllTools() and QueryTools()
pkg/tools/annotations.go	ToolQuery gets ReadOnlyHint: true, ToolExecute gets DestructiveHint: true
pkg/tools/descriptions.go	Updated descriptions for both tools
pkg/tools/toolkit.go	Register ToolExecute in registerTool()
pkg/tools/options.go	Updated docs to reference ToolExecute
pkg/extensions/readonly.go	ReadOnly interceptor now checks ToolExecute

Upgrading

go get github.com/txn2/mcp-trino@v0.8.0

If you use trino_query for write operations, update those calls to use trino_execute instead.

Changelog

• feat: split trino_query into read-only query and unrestricted execute tools (#39)

Full diff: v0.6.2...v0.8.0

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_0.8.0_darwin_arm64.mcpb
• macOS Intel: mcp-trino_0.8.0_darwin_amd64.mcpb
• Windows: mcp-trino_0.8.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:v0.8.0

Verification

All release artifacts are signed with Cosign. Verify with:

cosign verify-blob --bundle mcp-trino_0.8.0_linux_amd64.tar.gz.sigstore.json \
  mcp-trino_0.8.0_linux_amd64.tar.gz

mcp-trino-v0.6.2

What's New

Default Icons for All Tools

All 7 Trino tools now include a default SVG icon in tools/list responses. MCP clients that support icons (e.g., Claude Desktop) will render these alongside tool names, improving visual discoverability.

Tools with icons: trino_query, trino_explain, trino_list_catalogs, trino_list_schemas, trino_list_tables, trino_describe_table, trino_list_connections

Icon Customization API

A new 3-level priority chain lets consumers override icons at any level:

1. Per-tool via WithIcon() tool option — highest priority
2. Toolkit-wide via WithIcons() toolkit option — override specific tools by name
3. Built-in default — all tools get the Trino SVG automatically

// Override a specific tool's icon at registration time
toolkit := tools.NewToolkit(client, cfg,
    tools.WithIcons(map[tools.ToolName][]mcp.Icon{
        tools.ToolQuery: {{Source: "https://example.com/custom.svg", MIMEType: "image/svg+xml"}},
    }),
)

This follows the same resolution pattern already used by WithDescriptions() and WithAnnotations().

For mcp-data-platform Users

The mcp-data-platform icons middleware can override these defaults via YAML configuration — no code changes needed:

icons:
  enabled: true
  tools:
    trino_query:
      src: "https://example.com/custom-trino.svg"
      mime_type: "image/svg+xml"

Files Changed

File	Change
icons/trino.svg	New — default Trino tool icon
pkg/tools/icons.go	New — icon resolution with 3-level priority chain
pkg/tools/icons_test.go	New — comprehensive tests for all priority levels
pkg/tools/toolkit.go	Add icons map to Toolkit struct
pkg/tools/options.go	Add WithIcons() and WithIcon() options
pkg/tools/options_test.go	Tests for new options
pkg/tools/{query,explain,connections,schema}.go	Add Icons field to all 7 tool registrations

Upgrading

This is a backward-compatible minor release. No configuration changes are required. Icons appear automatically in tools/list responses — clients that don't support icons simply ignore the field.

go get github.com/txn2/mcp-trino@v0.6.2

Changelog

• feat: add default icons for all tools (#38)

Full diff: v0.6.1...v0.6.2

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_0.6.2_darwin_arm64.mcpb
• macOS Intel: mcp-trino_0.6.2_darwin_amd64.mcpb
• Windows: mcp-trino_0.6.2_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:v0.6.2

Verification

All release artifacts are signed with Cosign. Verify with:

cosign verify-blob --bundle mcp-trino_0.6.2_linux_amd64.tar.gz.sigstore.json \
  mcp-trino_0.6.2_linux_amd64.tar.gz

mcp-trino-v0.6.1

Changelog

Note: This release supersedes v0.6.0, which was published with missing MCPB bundle assets due to a release pipeline issue (immutable release prevented post-build asset uploads).

Features

• feat: add ProgressNotifier interface for granular query progress (#36) — Long-running Trino queries can now send progress notifications to MCP clients via the ProgressNotifier interface. Clients that provide a _meta.progressToken receive real-time status updates (executing, formatting, complete).

Bug Fixes

• fix: create release as draft to allow MCPB bundle uploads (#37) — GoReleaser now creates releases as drafts, uploads all assets (including MCPB bundles and signatures), then publishes. Fixes HTTP 422: Cannot upload assets to an immutable release.

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_0.6.1_darwin_arm64.mcpb
• macOS Intel: mcp-trino_0.6.1_darwin_amd64.mcpb
• Windows: mcp-trino_0.6.1_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:v0.6.1

Verification

All release artifacts are signed with Cosign. Verify with:

cosign verify-blob --bundle mcp-trino_0.6.1_linux_amd64.tar.gz.sigstore.json \
  mcp-trino_0.6.1_linux_amd64.tar.gz

mcp-trino-v0.6.0

Changelog

Features

• 3aec300: feat: add ProgressNotifier interface for granular query progress (#36) (@cjimti)

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_0.6.0_darwin_arm64.mcpb
• macOS Intel: mcp-trino_0.6.0_darwin_amd64.mcpb
• Windows: mcp-trino_0.6.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:v0.6.0

Verification

All release artifacts are signed with Cosign. Verify with:

cosign verify-blob --bundle mcp-trino_0.6.0_linux_amd64.tar.gz.sigstore.json \
  mcp-trino_0.6.0_linux_amd64.tar.gz

mcp-trino-v0.5.0

Summary

This release adds MCP tool annotations and typed structured outputs to all tools. Annotations declare behavioral hints (readOnlyHint, destructiveHint, idempotentHint, openWorldHint) so AI agents understand tool side effects without executing them. Structured outputs return typed data alongside human-readable text, enabling downstream consumers to access results programmatically without parsing.

Implements Phases 1 and 2 of txn2/mcp-data-platform#102.

New Features

Tool Annotations

All 7 tools now declare MCP behavioral annotations with sensible defaults. Schema-browsing tools are marked read-only and idempotent; trino_query is marked non-destructive but not read-only (since SQL content varies). Without annotations, agents treat every tool call as potentially destructive and may add unnecessary confirmation steps.

Default annotations:

Tool	ReadOnly	Destructive	Idempotent	OpenWorld
trino_query	false	false	false	false
trino_explain	true	—	true	false
trino_list_catalogs	true	—	true	false
trino_list_schemas	true	—	true	false
trino_list_tables	true	—	true	false
trino_describe_table	true	—	true	false
trino_list_connections	true	—	true	false

Annotations follow the same override pattern as tool descriptions — per-registration beats toolkit-level beats built-in defaults:

Toolkit-level override:

toolkit := tools.NewToolkit(client, cfg,
    tools.WithAnnotations(map[tools.ToolName]*mcp.ToolAnnotations{
        tools.ToolQuery: {ReadOnlyHint: true, IdempotentHint: true},
    }),
)

Per-registration override:

toolkit.RegisterWith(server, tools.ToolQuery,
    tools.WithAnnotation(&mcp.ToolAnnotations{ReadOnlyHint: true}),
)

Read defaults programmatically:

ann := tools.DefaultAnnotations(tools.ToolQuery)

Typed Structured Outputs

All tool handlers now return typed output structs as the second return value, alongside the unchanged human-readable TextContent response. This enables middleware, platform wrappers, and programmatic clients to access structured data directly.

Tool	Output Type	Key Fields
trino_query	QueryOutput	columns, rows, row_count, stats
trino_explain	ExplainOutput	plan, type
trino_list_catalogs	ListCatalogsOutput	catalogs, count
trino_list_schemas	ListSchemasOutput	catalog, schemas, count
trino_list_tables	ListTablesOutput	catalog, schema, tables, count, pattern
trino_describe_table	DescribeTableOutput	catalog, schema, table, columns, column_count
trino_list_connections	ListConnectionsOutput	connections, count

Documentation

• Extensibility Guide — New "Tool Annotations" and "Structured Outputs" sections with API examples and priority chain
• Tools API Reference — Annotations summary table and per-tool structured output JSON examples
• Server Configuration — New "Tool Annotations" section
• Configuration Reference — Annotations in toolkit config table and Go example

Other Changes

• handleListTables — Consolidated duplicate filtered/unfiltered code paths
• Test coverage — Added TestRegisteredToolInvocation exercising full MCP dispatch via InMemoryTransport for all 7 tools; package coverage 85.8% → 94.4%

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_0.5.0_darwin_arm64.mcpb
• macOS Intel: mcp-trino_0.5.0_darwin_amd64.mcpb
• Windows: mcp-trino_0.5.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:v0.5.0

Go Library

go get github.com/txn2/mcp-trino@v0.5.0

Verification

All release artifacts are signed with Cosign and include SLSA Level 3 provenance. Verify with:

cosign verify-blob --bundle mcp-trino_0.5.0_linux_amd64.tar.gz.sigstore.json \
  mcp-trino_0.5.0_linux_amd64.tar.gz

mcp-trino-v0.4.0

Summary

This release adds customizable tool descriptions — a new API that lets consumers override the descriptions AI agents see for each tool. It also ships enhanced default descriptions with AI agent decision context, so agents make better tool selection choices out of the box.

New Features

Tool Description Override API

Tool descriptions were previously hardcoded. Now they can be customized at three levels, with a clear priority chain (highest wins):

1. Per-registration WithDescription() via RegisterWith()
2. Toolkit-level WithDescriptions() via NewToolkit()
3. Default built-in description

Library usage — bulk override:

toolkit := tools.NewToolkit(client, cfg,
    tools.WithDescriptions(map[tools.ToolName]string{
        tools.ToolQuery:   "Query the retail analytics warehouse",
        tools.ToolExplain: "Check query performance before running",
    }),
)

Library usage — per-registration override:

toolkit.RegisterWith(server, tools.ToolQuery,
    tools.WithDescription("Query the retail analytics warehouse"),
)

Config file (YAML/JSON):

toolkit:
  descriptions:
    trino_query: "Query the retail analytics data warehouse."
    trino_explain: "Check query performance before running."

Standalone server:

opts := server.Options{
    Descriptions: map[tools.ToolName]string{
        tools.ToolQuery: "Custom description",
    },
}

Read defaults programmatically:

desc := tools.DefaultDescription(tools.ToolQuery)

Enhanced Default Tool Descriptions

Production feedback from AI agents revealed that tool descriptions described what each tool does but not when to use it. The trino_explain tool was never used because nothing in the description triggered agents to consider checking query plans.

Updated descriptions for three tools:

• trino_query — Now includes catalog.schema.table path format guidance, limit parameter awareness, WHERE clause advice for large tables, and a nudge toward trino_explain for expensive queries
• trino_explain — Now provides concrete triggers: large tables (millions of rows), filter verification, slow query debugging, and join strategy analysis
• trino_describe_table — Now highlights include_sample=true for understanding data formats, positions it as the richest single-call for table structure, and cross-references trino_list_tables for discovery

Documentation

New documentation across all relevant guides:

• README — New "Customizing Tool Descriptions" section with library, config file, and programmatic examples
• Library Quickstart — New step showing description customization early in the composition walkthrough
• Extensibility Guide — New "Tool Description Overrides" section covering all override patterns
• Tools API Reference — New "Description Overrides" section with priority chain documentation
• Server Configuration — Updated YAML example with descriptions field

Dependency Updates

• github.com/modelcontextprotocol/go-sdk — Updated to latest
• github/codeql-action — Bumped in CI
• GitHub Actions group — Bumped in CI

Other Changes

• .goreleaser.yml — Removed draft: true so releases publish directly
• pkg/multiserver/config.go — Fixed prealloc lint issue in ConnectionNames()

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_0.4.0_darwin_arm64.mcpb
• macOS Intel: mcp-trino_0.4.0_darwin_amd64.mcpb
• Windows: mcp-trino_0.4.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:v0.4.0

Go Library

go get github.com/txn2/mcp-trino@v0.4.0

Verification

All release artifacts are signed with Cosign and include SLSA Level 3 provenance. Verify with:

cosign verify-blob --bundle mcp-trino_0.4.0_linux_amd64.tar.gz.sigstore.json \
  mcp-trino_0.4.0_linux_amd64.tar.gz

mcp-trino-v0.3.0

Summary

This release improves query response metadata with accurate duration reporting and query ID tracking for debugging.

Breaking Changes

QueryStats.DurationMs field type change

The duration_ms JSON field now correctly contains milliseconds instead of nanoseconds.

Before (v0.2.x):

{"duration_ms": 540000000}  // Actually nanoseconds!

After (v0.3.0):

{"duration_ms": 540}  // Correctly milliseconds

Migration: If you were dividing by 1,000,000 to convert, remove that conversion.

New Features

Query ID in response stats

Query responses now include the Trino query ID for debugging and log correlation:

{
  "stats": {
    "row_count": 100,
    "duration_ms": 540,
    "truncated": false,
    "query_id": "20240115_123456_00001_abcde"
  }
}

Use this to:

• Correlate with Trino UI/logs
• Debug slow queries
• Build audit trails

Fixes

• #22: duration_ms JSON field now contains actual milliseconds (was nanoseconds)
• #23: Added query_id to QueryStats for debugging/tracking

Known Limitations

• #24 (Warnings): Trino REST API returns warnings, but trino-go-client v0.333.0 does not expose them. Tracking upstream support.

Upgrade Guide

1. Update your dependency:

   go get github.com/txn2/mcp-trino@v0.3.0

2. If you were compensating for nanosecond values in duration_ms, remove that logic.

3. (Optional) Start using query_id for debugging and correlation.

Changelog

Others

• a547dd9: Add changelogs for v0.2.0 and v0.2.1 releases (#18) (@cjimti)
• e4fafe9: Housekeeping/repo (#20) (@cjimti)
• 4958dea: Issues #22, #23, #24 - QueryStats Improvements (#26) (@cjimti)
• d2a6387: ci: bump the github-actions group with 2 updates (#19) (@dependabot[bot])
• fd00323: ci: bump the github-actions group with 3 updates (#21) (@dependabot[bot])
• eb2c662: ci: bump the github-actions group with 6 updates (#16) (@dependabot[bot])

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_0.3.0_darwin_arm64.mcpb
• macOS Intel: mcp-trino_0.3.0_darwin_amd64.mcpb
• Windows: mcp-trino_0.3.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:v0.3.0

Verification

All release artifacts are signed with Cosign. Verify with:

cosign verify-blob --bundle mcp-trino_0.3.0_linux_amd64.tar.gz.sigstore.json \
  mcp-trino_0.3.0_linux_amd64.tar.gz