Thanks to visit codestin.com
Credit goes to github.com

Skip to content

CLAUDE.md

Latest commit

 

History

History
183 lines (142 loc) · 7.57 KB

CLAUDE.md

File metadata and controls

183 lines (142 loc) · 7.57 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

mcp-trino is a dual-purpose tool that works as both:

  1. MCP Server - Enables AI assistants to interact with Trino's distributed SQL query engine through standardized MCP tools
  2. Interactive CLI - psql-like REPL for direct human access to Trino databases

The tool automatically detects which mode to use based on arguments and environment.

Tech Stack

  • Language: Go 1.24.11+
  • Key Dependencies:
    • github.com/mark3labs/mcp-go v0.41.1 (MCP protocol)
    • github.com/trinodb/trino-go-client v0.328.0 (Trino client)
    • github.com/tuannvm/oauth-mcp-proxy v0.0.2 (OAuth 2.1 authentication)
  • Build Tools: GoReleaser, Docker, GitHub Actions, golangci-lint

Development Commands

# Core development
make build           # Build binary to ./bin/mcp-trino
make test            # Run unit tests with race detection
make run-dev         # Run from source code (go run ./cmd)
make run             # Run built binary
make clean           # Clean build artifacts
make lint            # Run linting (same as CI: golangci-lint + go mod tidy)

# Docker development
make docker-compose-up   # Start with Docker Compose
make docker-compose-down # Stop Docker Compose
make run-docker          # Build and run Docker image locally

# Release and packaging
make release-snapshot    # Create snapshot release with GoReleaser
make build-dxt          # Build platform-specific binaries for DXT
make pack-dxt           # Package DXT extension

# Testing individual components
go test ./internal/config    # Test configuration package
go test ./internal/trino     # Test Trino client package
go test ./internal/mcp       # Test MCP handlers package
go test ./internal/cli       # Test CLI commands and REPL
go test ./cmd                # Test mode detection and integration

Architecture

Core Components

  1. Main Entry Point (cmd/main.go):

    • Dual-mode detection (MCP vs CLI based on args/environment)
    • MCP server initialization and Trino connection testing
    • Transport selection (STDIO vs HTTP with SSE)
    • Graceful shutdown with signal handling
    • CORS support for web clients
    • Version management and build metadata

  2. CLI Layer (internal/cli/):

    • commands.go - CLI subcommands with io.Writer injection for testability
    • repl.go - Interactive REPL with injectable stdin/stdout for testing
    • config.go - Dual-format config (YAML via gopkg.in/yaml.v3 + JSON via encoding/json)
    • Output formatting via text/tabwriter (table), encoding/csv (CSV), encoding/json (JSON)
    • Structured LLM-friendly --help with NAME/SYNOPSIS/DESCRIPTION/COMMANDS/FLAGS/EXAMPLES/ENVIRONMENT
    • Unix exit codes (0=success, 1=error, 2=usage) and signal handling (SIGINT/SIGTERM)

  3. Configuration Layer (internal/config/config.go):

    • Environment-based configuration with validation
    • Security defaults (HTTPS, read-only queries)
    • Timeout configuration with validation
    • Connection parameter management

  4. Client Layer (internal/trino/client.go):

    • Database connection management with connection pooling
    • SQL injection protection via read-only query enforcement
    • Context-based timeout handling for queries
    • Query result processing and formatting

  5. Handler Layer (internal/mcp/handlers.go):

    • MCP tool implementations with JSON response formatting
    • Parameter validation and error handling
    • Consistent logging for debugging
    • Tool result standardization

OAuth Authentication Architecture

OAuth 2.1 authentication is provided by the external oauth-mcp-proxy library:

  • Integration Point: internal/mcp/server.go - OAuth middleware registration
  • Configuration: internal/config/config.go - OAuth config gathering (validation delegated to library)
  • Modes: Native (client-driven) and Proxy (server-driven) OAuth flows
  • Providers: HMAC, Okta, Google, Azure AD
  • Documentation: See docs/oauth.md and oauth-mcp-proxy docs

Transport Support

  • STDIO Transport: Direct MCP client integration (default)
  • HTTP Transport: StreamableHTTP support on /mcp endpoint with SSE backward compatibility on /sse endpoint
  • Status Endpoint: GET / returns server status and version

SQL Security Architecture

The security model centers around the isReadOnlyQuery() function in internal/trino/client.go:

  • Allows: SELECT, SHOW, DESCRIBE, EXPLAIN, WITH (CTEs)
  • Blocks: INSERT, UPDATE, DELETE, CREATE, DROP, ALTER by default
  • Override: Set TRINO_ALLOW_WRITE_QUERIES=true to bypass (logs warning)

Available MCP Tools

All tools return JSON-formatted responses and handle parameter validation:

  • execute_query: Execute SQL queries with security restrictions
  • list_catalogs: Discover available data catalogs
  • list_schemas: List schemas within catalogs (optional catalog param)
  • list_tables: List tables within schemas (optional catalog/schema params)
  • get_table_schema: Retrieve table structure (required table param)
  • explain_query: Analyze query execution plans with optional format parameter

Configuration

Trino Connection:

  • TRINO_HOST, TRINO_PORT, TRINO_USER, TRINO_PASSWORD
  • TRINO_SCHEME (http/https), TRINO_SSL, TRINO_SSL_INSECURE
  • TRINO_ALLOW_WRITE_QUERIES (default: false for security)
  • TRINO_QUERY_TIMEOUT (default: 30 seconds, validated > 0)

MCP Server:

  • MCP_TRANSPORT (stdio/http), MCP_PORT (default: 8080), MCP_HOST

OAuth (optional, via oauth-mcp-proxy):

  • OAUTH_ENABLED (default: false) - Single source of truth for OAuth activation
  • OAUTH_MODE (native/proxy, default: native)
  • OAUTH_PROVIDER (hmac/okta/google/azure, default: hmac)
  • JWT_SECRET - Required for HMAC provider
  • OIDC_ISSUER, OIDC_AUDIENCE, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET - For OIDC providers
  • OAUTH_ALLOWED_REDIRECT_URIS - Comma-separated redirect URIs

Key defaults and behaviors:

  • HTTPS scheme forces SSL=true regardless of TRINO_SSL setting
  • Invalid timeout values fall back to 30 seconds with warning
  • Connection pool: 10 max open, 5 max idle, 5min max lifetime

CI/CD Pipeline

The GitHub Actions workflow (.github/workflows/build.yml) includes:

Code Quality (verify job):

  • Go mod tidy verification
  • golangci-lint with 5m timeout
  • Dependency verification

Security (security job):

  • govulncheck for Go vulnerability scanning
  • Trivy SARIF scanning (CRITICAL/HIGH/MEDIUM severity)
  • SBOM generation with SPDX format
  • Security results uploaded to GitHub Security tab

Testing (test job):

  • Race detection enabled (go test -race)
  • Code coverage with atomic mode
  • Coverage uploaded to Codecov

Build/Release:

  • Multi-platform builds via GoReleaser
  • Docker images published to GHCR
  • Automated releases on main branch pushes
  • SLSA provenance generation for supply chain security

Manual Testing

  • Docker Compose setup includes real Trino server
  • Set MCP_TRANSPORT=http and test StreamableHTTP endpoint at http://localhost:8080/mcp
  • Test legacy SSE endpoint at http://localhost:8080/sse for backward compatibility
  • Test status endpoint at GET /

Build and Release

  • Multi-platform Support: Uses GoReleaser for linux/darwin/windows on amd64/arm64/arm
  • Version Injection: -ldflags "-X main.Version=$(VERSION)" sets version from git tags
  • Docker: Multi-stage build with scratch base image for minimal size
  • Distribution: GitHub Releases, GHCR, Homebrew tap (tuannvm/mcp)