mcp-trino CLI Release Notes v1.0

Release Date: 2025-03-25 Status: Production-Ready ✅

Overview

This release transforms mcp-trino from MCP-only to a dual-purpose tool that works both as an MCP server for AI assistants AND as an interactive CLI for human users.

What's New

CLI Mode

• Interactive REPL with SQL query execution
• Subcommands: query, catalogs, schemas, tables, describe, explain
• Output formats: table, json, csv
• Config file support: ~/.config/trino/config.yaml
• Auto-completion: Meta-commands (\help, \quit, \history, \format, etc.)

Dual-Mode Operation

The binary automatically detects which mode to use:

• MCP mode: Default when no args or MCP_PROTOCOL_VERSION is set
• CLI mode: Activated by CLI commands or --cli flag
• Explicit control: Use --mcp or --cli flags to force mode

Important Behavioral Changes

⚠️ Column Order Now Deterministic

Before: Table and CSV output had non-deterministic column order (due to Go map iteration)

After: Columns are sorted alphabetically for consistent output

Impact:

• ✅ Improved: Automated scripts get predictable output
• ⚠️ Breaking: Scripts parsing by column position may break
• Recommendation: Parse by column name instead of position

Example:

SELECT zebra, apple, banana FROM table;

Before: zebra | apple | banana (random order) After: apple | banana | zebra (alphabetically sorted)

Configuration Precedence

Values are applied in this order (later overrides earlier):

1. CLI flags (--host, --port, etc.) - highest priority
2. --profile flag (select named profile)
3. TRINO_PROFILE environment variable
4. current field in config file
5. default profile fallback
6. Environment variables (TRINO_HOST, etc.) - lowest priority

Example:

# ~/.config/trino/config.yaml
current: prod
profiles:
  prod:
    host: prod.example.com
    port: 443
    user: prod_user
  dev:
    host: localhost
    port: 8080
    user: trino

# CLI flag overrides everything
mcp-trino --host custom --profile prod query "SELECT 1"
# Uses: host=custom (flag), other values from prod profile

# Profile selection via flag
mcp-trino --profile dev catalogs
# Uses: dev profile values

# Profile selection via env var
export TRINO_PROFILE=prod
mcp-trino catalogs
# Uses: prod profile values

# Default profile (no explicit selection)
mcp-trino catalogs
# Uses: 'prod' profile (from 'current' field)

Mode Selection Logic

┌─────────────────────────────────────────────────────────────┐
│ Start                                                      │
└─────────────┬───────────────────────────────────────────────┘
              │
              ▼
┌─────────────────────────────────────────────────────────────┐
│ Is --mcp flag present?                                     │
│ Yes → MCP mode                                            │
└─────────────┬───────────────────────────────────────────────┘
              │ No
              ▼
┌─────────────────────────────────────────────────────────────┐
│ Is MCP_PROTOCOL_VERSION set?                               │
│ Yes → MCP mode                                            │
└─────────────┬───────────────────────────────────────────────┘
              │ No
              ▼
┌─────────────────────────────────────────────────────────────┐
│ Is --cli flag present or known CLI command?                │
│ Yes → CLI mode                                            │
└─────────────┬───────────────────────────────────────────────┘
              │ No
              ▼
┌─────────────────────────────────────────────────────────────┐
│ Unknown positional argument?                               │
│ Yes → MCP mode (backward compatibility)                   │
└─────────────┬───────────────────────────────────────────────┘
              │ No
              ▼
┌─────────────────────────────────────────────────────────────┐
│ No arguments, TTY?                                        │
│ Yes → CLI help                                           │
│ No → MCP mode                                            │
└─────────────────────────────────────────────────────────────┘

Usage Examples

Basic CLI Usage

# List catalogs
mcp-trino catalogs

# List tables in a catalog/schema
mcp-trino tables memory default

# Execute a query
mcp-trino query "SELECT * FROM my_table LIMIT 10"

# Describe a table
mcp-trino describe memory.default.users

# Explain a query
mcp-trino explain "SELECT COUNT(*) FROM users"

Interactive REPL

# Start REPL
mcp-trino --interactive

# Or just
mcp-trino

# In REPL:
trino> SELECT 1 AS test;
 test
-----
    1

trino> \format json
trino> SELECT 1;
{"_col0": 1}

trino> \quit

Config File

# ~/.config/trino/config.yaml
current: prod

profiles:
  prod:
    host: trino.example.com
    port: 443
    user: prod_user
    password: prod_password
    catalog: hive
    schema: analytics
    ssl:
      enabled: true
      insecure: false

  dev:
    host: localhost
    port: 8080
    user: trino
    catalog: memory
    schema: default

  staging:
    host: staging-trino.example.com
    port: 443
    user: staging_user
    catalog: hive
    schema: analytics_staging

output:
  format: table

Output Formats

# Table format (default)
mcp-trino --format table query "SELECT 1"

# JSON format
mcp-trino --format json query "SELECT 1"

# CSV format
mcp-trino --format csv query "SELECT 1"

Mode Selection

# Force MCP mode
mcp-trino --mcp

# Force CLI mode
mcp-trino --cli

# MCP mode (default for no args)
mcp-trino

# CLI mode (when command recognized)
mcp-trino query "SELECT 1"

REPL Meta-Commands

Command	Description
\help	Show help
\quit, \exit, \q	Exit REPL
\history	Show command history
\catalogs	List all catalogs
\schemas [catalog]	List schemas (optional catalog)
\tables [catalog schema]	List tables (optional catalog.schema)
\describe <table>	Describe table structure
\format <fmt>	Set output format (table, json, csv)

Testing Summary

Test Coverage

• Unit Tests: 100+ tests across 6 test files
• Integration Tests: End-to-end binary execution tests
• All Tests: Passing ✅
• Linting: 0 issues ✅

Test Files

• cmd/main_test.go - Mode detection, argument parsing
• cmd/integration_test.go - Binary execution, precedence
• internal/cli/config_test.go - Config loading, SSL handling
• internal/cli/commands_test.go - CLI commands
• internal/cli/repl_test.go - REPL behavior
• internal/cli/output_test.go - Output determinism

Known Limitations

1. Shell completions not yet implemented (bash/zsh)
2. REPL multiline queries require TTY for full testing
3. Tests conducted without live Trino server (structural testing)

Backward Compatibility

✅ Fully backward compatible with existing MCP integrations:

• No-arg startup defaults to MCP mode
• Unknown positional arguments preserve MCP behavior
• MCP_PROTOCOL_VERSION environment variable respected
• STDIO transport mode unchanged

Deployment Recommendations

Before Release

1. ✅ All tests passing
2. ✅ Linting clean
3. ✅ Documentation complete
4. ⚠️ Test with real Trino server if possible

Post-Release Monitoring

• User feedback on column order change
• Reports of MCP compatibility issues
• Performance with large result sets

Rollback Plan

If critical issues arise:

1. Previous version available via git tags
2. Config file allows disabling CLI features
3. MCP mode fully backward compatible

Support

• Documentation: See README.md and docs/ directory
• Issues: Report via GitHub issues
• Contributing: Pull requests welcome

Acknowledgments

Built with:

• Go 1.24.11+
• Trino Go Client v0.328.0
• MCP Go SDK v0.41.1