# 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:**

```sql
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:**

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

```bash
# 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

```bash
# 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

```bash
# 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

```yaml
# ~/.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

```bash
# 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

```bash
# 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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.tuannvm.com/mcp-trino/release_notes.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.