teradata-mcp-server CLAUDE.md

CLAUDE.md

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

Project Overview

Teradata MCP Server — a Model Context Protocol server for interacting with Teradata databases. Built on FastMCP, distributed on PyPI as teradata-mcp-server. Python 3.11+.

Build & Development Commands

# Install dependencies
uv sync

# Install with optional modules
uv sync --extra fs       # Feature Store (teradataml)
uv sync --extra tdvs     # Vector Store (teradatagenai)
uv sync --extra bar      # Backup & Restore
uv sync --extra dev      # Dev tools (ruff, mypy)

# Run the server locally (stdio mode)
uv run teradata-mcp-server --database_uri "teradata://user:pass@host:1025/db"

# Run with specific profile and transport
uv run teradata-mcp-server --profile dba --mcp_transport streamable-http --mcp_port 8001

# Lint
uv run ruff check src/
uv run ruff format --check src/

# Type check
uv run mypy src/

# Run tests (requires a live Teradata connection)
export DATABASE_URI="teradata://user:pass@host:1025/database"
uv run python tests/integration/run_mcp_tests.py "uv run teradata-mcp-server"

# Docker
docker compose up teradata-mcp-server

Architecture

Request Flow

1. server.py — CLI argument parsing, calls create_mcp_app()
2. app.py — FastMCP app factory. Creates the MCP instance, registers tools/prompts/resources based on profile, configures middleware. A teradata_lifespan async context manager (passed to FastMCP(lifespan=...)) owns the TDConn pool lifecycle: creates the pool at server startup and calls engine.dispose() in its finally block on shutdown.
3. middleware.py — RequestContextMiddleware extracts per-request headers, auth, and session info. Sets Teradata QueryBand for tracing
4. Tool handlers — Plain sync functions (handle_*) in tools/ subdirectories. Wrapped to async via asyncio.to_thread

Profile-Based Module Loading

Tools are organized into domain modules under src/teradata_mcp_server/tools/:

• base/ — Core queries (readQuery, tableList, columnDescription, etc.)
• dba/ — Administration & monitoring
• sec/ — Security & permissions
• rag/ — Retrieval-augmented generation workflows
• fs/ — Feature Store (optional, requires teradataml)
• tdvs/ — Vector Store operations
• bar/ — Backup & restore (optional)
• chat/ — Chat completion
• qlty/ — Data quality / EDA
• plot/ — Visualization (charts)
• sql_opt/ — SQL optimization
• tmpl/ — Template tools