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