refactor: restructure as proper Python package with type-safe configuration

- Moved server.py to src/server.py and created proper package structure
- Added src/__init__.py and src/__main__.py for module execution
- Implemented type-safe configuration management with pydantic-settings
- Added comprehensive logging with uvicorn logger integration
- Updated Dockerfile to use new package structure and non-root user
- Enhanced HTTP client configuration with timeout and HTTP/2 support
- Fixed httpx.Timeout configuration to include all required parameters
- Added /ping health check endpoint
- Updated documentation and development setup instructions
- Improved .gitignore with comprehensive Python exclusions

Author: kmlx

.gitignore

@@ -1,15 +1,23 @@
-.env
-
-tests/
-
-examples/
-
-.venv/
-
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+.pytest_cache
+.mypy_cache/
 .ruff_cache/
 
-.pytest_cache/
+# Virtual environments
+.venv
 
-__pycache__/
+# macos
+.DS_Store
+
+# Environment
+.env*
+!.env.example
 
-.gitignore
+# LLM
+.claude

CLAUDE.md

@@ -10,10 +10,11 @@ This is a FastMCP (Model Context Protocol) server for Metabase integration. It p
 
 ### Core Components
 
-- **`server.py`**: Main FastMCP server with all tool implementations
+- **`src/server.py`**: Main FastMCP server with all tool implementations using `mcp.server.fastmcp`
+- **`src/config.py`**: Type-safe configuration management using pydantic-settings
 - **`MetabaseClient`**: HTTP client class handling Metabase API authentication and requests
-- **Authentication**: Supports both API Key (preferred) and email/password session authentication
-- **Transport Methods**: STDIO (default for IDE integration), SSE, HTTP
+- **Authentication**: API Key authentication with `X-API-KEY` header
+- **Transport Methods**: HTTP (default), STDIO (for IDE integration)
 
 ### Key Tool Categories
 
@@ -22,9 +23,13 @@ This is a FastMCP (Model Context Protocol) server for Metabase integration. It p
 3. **Collection Management**: `list_collections`, `create_collection`, `list_cards_by_collection`
 4. **Smart Search**: `search_metabase`, `find_candidate_collections`, `search_cards_in_collections`
 
-### Authentication
+### Configuration Management
 
-The server uses API Key authentication with the `X-API-KEY` header.
+The server uses `config.py` with pydantic-settings for type-safe configuration:
+- Automatic `.env` file loading
+- Environment variable validation
+- Type-safe access to all settings
+- Centralized configuration management
 
 ## Development Commands
 
@@ -39,17 +44,14 @@ uv sync --group dev
 
 ### Running the Server
 ```bash
-# STDIO transport (default for IDE integration)
-uv run python server.py
+# Default transport (streamable-http)
+uv run python -m src
 
-# SSE transport for web applications
-uv run python server.py --sse
-
-# HTTP transport
-uv run python server.py --http
+# STDIO transport (for IDE integration)
+MCP_TRANSPORT=stdio uv run python -m src
 
 # Custom host/port via environment variables
-HOST=localhost PORT=9000 uv run python server.py --sse
+HOST=localhost PORT=9000 uv run python -m src
 ```
 
 ### Code Quality & Testing
@@ -65,22 +67,32 @@ uv run black .
 uv run isort .
 
 # Type checking
-uv run mypy server.py
+uv run mypy src/
 
 # Run tests
 uv run pytest
 ```
 
 ## Configuration
 
+Configuration is managed through `config.py` using pydantic-settings. All settings can be configured via environment variables or a `.env` file.
+
 ### Environment Variables
-Required in `.env` file:
+**Required:**
 - `METABASE_URL`: Metabase instance URL
 - `METABASE_API_KEY`: Metabase API key
 
-Optional:
-- `HOST`: Server host (default: 0.0.0.0 for SSE/HTTP)
-- `PORT`: Server port (default: 8000 for SSE/HTTP)
+**Optional (with defaults):**
+- `HOST`: Server host (default: "0.0.0.0")
+- `PORT`: Server port (default: 8080)
+- `MCP_TRANSPORT`: Transport method - "streamable-http" or "stdio" (default: "streamable-http")
+- `LOG_LEVEL`: Logging level (default: "INFO")
+- `MCP_SERVER_NAME`: Server name (default: "metabase-mcp")
+
+**HTTP Client Configuration:**
+- `HTTP_CONNECT_TIMEOUT`: Connection timeout in seconds (default: 10.0, range: 1.0-60.0)
+- `HTTP_READ_TIMEOUT`: Read timeout in seconds (default: 30.0, range: 5.0-300.0)
+- `HTTP_ENABLE_HTTP2`: Enable HTTP/2 support for better performance (default: False)
 
 ### Tool Configuration
 - Line length: 100 characters (Black, Ruff, isort)
@@ -91,11 +103,12 @@ Optional:
 ## Common Development Patterns
 
 ### Adding New Tools
-1. Use `@mcp.tool` decorator
-2. Include proper type hints and docstrings
-3. Handle errors with try/except and logger.error
-4. Use `metabase_client.request()` for API calls
-5. Return structured dict responses
+1. Use `@mcp.tool()` decorator
+2. Add `ctx: Context` as first parameter to access lifespan context
+3. Include proper type hints and docstrings
+4. Access MetabaseClient via `ctx.request_context.lifespan_context.metabase_client`
+5. Handle errors with try/except and logger.error
+6. Return structured responses
 
 ### Error Handling
 - Log errors with `logger.error()`
@@ -111,5 +124,8 @@ Optional:
 
 - The `list_cards()` tool returns 1700+ cards and may timeout - use `list_cards_paginated()` instead
 - Search tools are optimized: use `find_candidate_collections()` first, then `search_cards_in_collections()`
-- SSE/HTTP transports require starting the server before IDE integration
-- Uses per-request HTTP clients for automatic connection management
+- Server uses `mcp.server.fastmcp` with type-safe context management
+- Configuration uses pydantic-settings for validation and type safety
+- Default transport is `streamable-http` - set `MCP_TRANSPORT=stdio` for IDE integration
+- Uses per-request HTTP clients for automatic connection management
+- Custom `/ping` endpoint available for health checks

Dockerfile

@@ -1,35 +1,33 @@
-FROM python:3.12-slim
+FROM ghcr.io/astral-sh/uv:0.8-python3.12-bookworm-slim
 
-# Set working directory
-WORKDIR /app
+# Set environment variables
+ENV PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1
 
-# Install system dependencies and uv
-RUN apt-get update && apt-get install -y \
-    gcc \
-    curl \
-    && curl -LsSf https://astral.sh/uv/install.sh | sh \
-    && rm -rf /var/lib/apt/lists/*
+# Create non-root user
+RUN groupadd -r appuser && useradd -r -g appuser appuser
 
-# Add uv to PATH
-ENV PATH="/root/.local/bin:$PATH"
+# Set working directory
+WORKDIR /app
 
-# Copy project files
-COPY pyproject.toml .
-COPY requirements.txt .
+# Copy workspace files for dependency resolution
+COPY pyproject.toml uv.lock ./
 
-# Install Python dependencies with uv
-RUN uv sync --frozen
+# Install dependencies
+RUN uv sync --locked
 
 # Copy application code
-COPY server.py .
-COPY .env* ./
+COPY src/ src/
 
-# Create non-root user
-RUN useradd --create-home --shell /bin/bash app
-USER app
+# Create cache directory and change ownership
+RUN mkdir -p /home/appuser/.cache/uv && \
+    chown -R appuser:appuser /app /home/appuser/.cache
+
+# Switch to non-root user
+USER appuser
 
-# Expose port (for HTTP/SSE transport)
-EXPOSE 8000
+# Expose port (updated to match our config default)
+EXPOSE 8080
 
-# Default command
-CMD ["uv", "run", "python", "server.py"] 
+# Run the application using our new package structure
+CMD ["uv", "run", "python", "-m", "src"]

README.md

@@ -1,118 +1,76 @@
-# Metabase FastMCP Server
+# Metabase MCP Server
 
-A FastMCP (Model Context Protocol) server for Metabase, built with Python. This server provides tools to interact with Metabase databases, execute queries, manage cards, and work with collections.
-
-## Features
-
-- List and manage Metabase databases
-- Execute SQL queries and saved questions/cards
-- Create and manage cards (questions)
-- Work with collections
-- List tables and fields
-- API Key authentication
+A FastMCP server for Metabase integration that provides tools to interact with Metabase databases, execute queries, manage cards (questions), and work with collections.
 
 ## Installation
 
-### Quick Start with uv (Recommended)
-
-1. **Install uv** if not already installed:
-```bash
-curl -LsSf https://astral.sh/uv/install.sh | sh
-```
-
-2. **Clone and setup**:
 ```bash
+# Clone the repository
 git clone <repository-url>
 cd metabase-mcp
-uv sync  # Install dependencies and create virtual environment
-```
 
-3. **Configure environment**:
-```bash
-# Create .env file with your Metabase configuration
-echo "METABASE_URL=http://localhost:3000" > .env
-echo "METABASE_API_KEY=your-api-key-here" >> .env
+# Install dependencies
+uv sync
 ```
 
 ## Configuration
 
-Set the following environment variables in your `.env` file:
-
-- `METABASE_URL`: Your Metabase instance URL
-- `METABASE_API_KEY`: Your Metabase API key
-
-## Usage
-
-### Run the Server
+Set required environment variables in a `.env` file:
 
 ```bash
-# STDIO transport (default for MCP integration)
-uv run server.py
-
-# SSE transport (for web applications)
-uv run server.py --sse
-
-# HTTP transport
-uv run server.py --http
+METABASE_URL=https://your-metabase-instance.com
+METABASE_API_KEY=your-api-key-here
+
+# Optional settings (defaults shown)
+MCP_TRANSPORT=streamable-http  # or "stdio" for IDE integration
+HOST=0.0.0.0
+PORT=8080
+LOG_LEVEL=INFO
+
+# HTTP Client Configuration (optional)
+HTTP_CONNECT_TIMEOUT=10.0      # Connection timeout in seconds (1.0-60.0)
+HTTP_READ_TIMEOUT=30.0         # Read timeout in seconds (5.0-300.0)
+HTTP_ENABLE_HTTP2=false        # Enable HTTP/2 support
 ```
 
-### Claude Desktop Integration
+## Running
 
-To integrate with Claude Desktop, add the configuration to `~/Library/Application\ Support/Claude/claude_desktop_config.json`:
+```bash
+# Default (HTTP transport)
+uv run python -m src
 
-```json
-{
-    "mcpServers": {
-        "metabase-mcp": {
-            "command": "uv",
-            "args": ["run", "python", "/path/to/metabase-mcp-kmlx/server.py"],
-            "cwd": "/path/to/metabase-mcp-kmlx"
-        }
-    }
-}
+# STDIO transport (for IDE integration)
+MCP_TRANSPORT=stdio uv run python -m src
 ```
 
 ## Available Tools
 
 ### Database & Schema Tools
-- `list_databases`: List all databases in Metabase
-- `list_tables`: List all tables in a database with formatted output
-- `get_table_fields`: Get all fields/columns in a table
+- **`list_databases`** - List all databases in Metabase
+- **`list_tables(database_id)`** - List tables in a database with formatted markdown output
+- **`get_table_fields(table_id, limit=20)`** - Get fields/columns in a table
 
 ### Card & Query Tools
-- `list_cards`: List all questions/cards in Metabase (WARNING: Large dataset)
-- `list_cards_paginated`: List cards with pagination to avoid timeout issues
-- `execute_card`: Execute a Metabase question/card and get results
-- `execute_query`: Execute a SQL query against a Metabase database
-- `create_card`: Create a new question/card in Metabase
+- **`list_cards`** - List all questions/cards (WARNING: Large dataset, may timeout)
+- **`list_cards_paginated(limit=50, offset=0, filter_type="all")`** - List cards with pagination
+- **`list_cards_by_collection(collection_id)`** - List cards in a specific collection
+- **`execute_card(card_id, parameters=None)`** - Execute a Metabase question/card
+- **`execute_query(database_id, query, native_parameters=None)`** - Execute SQL query
+- **`create_card(name, database_id, query, description=None, collection_id=None, visualization_settings=None)`** - Create new card
 
-### Collection Management Tools
-- `list_collections`: List all collections in Metabase
-- `list_cards_by_collection`: List cards in a specific collection (focused dataset)
-- `create_collection`: Create a new collection in Metabase
+### Collection Management
+- **`list_collections`** - List all collections
+- **`create_collection(name, description=None, color=None, parent_id=None)`** - Create new collection
 
 ### Smart Search Tools
-- `search_metabase`: Universal search using Metabase search API (cards, dashboards, collections)
-- `find_candidate_collections`: Find collections by name/description matching (fast)
-- `search_cards_in_collections`: Search for cards within specific collections (targeted)
+- **`search_metabase(query, limit=20, models=None, archived=False, search_native_query=None)`** - Search using Metabase API
+- **`find_candidate_collections(query, limit_collections=10)`** - Find collections matching query
+- **`search_cards_in_collections(query, collection_ids, limit=25, offset=0)`** - Search cards within specific collections
 
-## Development
+## Health Check
 
-### Development Setup
+The server provides a `/ping` endpoint for health checks when running with HTTP transport.
 
-```bash
-# Install development dependencies (Python 3.12+)
-uv sync --group dev
-
-# Run tests
-uv run pytest
+## Integration
 
-# Format and lint code
-uv run ruff check .          # Lint
-uv run ruff format .         # Format
-uv run black .               # Alternative formatter
-uv run isort .               # Import sorting
-
-# Type checking
-uv run mypy server.py
-```
+For Claude Desktop or Cursor IDE integration, set `MCP_TRANSPORT=stdio` in your environment.