# AWS Athena MCP Server

A Model Context Protocol (MCP) server for AWS Athena that enables SQL queries and database exploration through a standardized interface.

## 🏗️ Project Structure

The project follows best practices for Python project organization:

```
aws-athena-mcp/
├── src/
│   └── athena_mcp/
│       ├── core/                 # Core system modules
│       │   ├── config.py        # Centralized configurations
│       │   ├── exceptions.py    # Custom exceptions
│       │   └── __init__.py
│       ├── services/            # Business services
│       │   ├── athena_client.py # Athena client factory and management
│       │   ├── athena_service.py # Main Athena operations
│       │   └── __init__.py
│       ├── utils/               # Utilities and helpers
│       │   ├── formatters.py    # Output formatters
│       │   ├── helpers.py       # Helper functions
│       │   ├── validators.py    # Validators
│       │   └── __init__.py
│       ├── handlers/            # MCP handlers
│       │   ├── tool_handlers.py # MCP tool handlers
│       │   └── __init__.py
│       ├── server.py            # Main MCP server
│       └── __init__.py
├── tests/
│   ├── unit/                    # Unit tests
│   ├── integration/             # Integration tests
│   └── __init__.py
├── main.py                      # Main entry point
├── setup.py                     # Installation configuration
├── pyproject.toml              # Development tools configuration
├── requirements.txt            # Dependencies
└── README.md
```

## 🚀 Features

- **Modular Architecture**: Code organized in well-defined modules following single responsibility principle
- **Complete Type Hints**: Static typing for better maintainability
- **Robust Error Handling**: Custom exceptions and proper error handling
- **Centralized Configuration**: All configurations in a single location
- **Tests Included**: Unit and integration test structure
- **Structured Logging**: Configurable logging system
- **Input Validation**: Validators for different data types

## 🔌 MCP Configuration

To use this server in MCP clients like Cursor, add the following configuration to your `mcp.json` file:

```json
{
  "mcpServers": {
    "athena-connector": {
      "command": "python3",
      "args": ["/path/to/aws-athena-mcp/main.py"],
      "env": {
        "AWS_ACCESS_KEY_ID": "your-access-key",
        "AWS_SECRET_ACCESS_KEY": "your-secret-key",
        "AWS_REGION": "us-east-1",
        "AWS_S3_OUTPUT_LOCATION": "s3://your-bucket/athena-results/"
      }
    }
  }
}
```

### Configuration Options

#### Using Direct Credentials:
```json
{
  "command": "python3",
  "args": ["/path/to/aws-athena-mcp/main.py"],
  "env": {
    "AWS_ACCESS_KEY_ID": "AKIA...",
    "AWS_SECRET_ACCESS_KEY": "your-secret-key",
    "AWS_REGION": "us-east-1",
    "AWS_S3_OUTPUT_LOCATION": "s3://your-bucket/results/"
  }
}
```

#### Using AWS Profile:
```json
{
  "command": "python3",
  "args": ["/path/to/aws-athena-mcp/main.py"],
  "env": {
    "AWS_PROFILE": "your-aws-profile",
    "AWS_REGION": "us-east-1",
    "AWS_S3_OUTPUT_LOCATION": "s3://your-bucket/results/"
  }
}
```

#### Using System Default Credentials:
```json
{
  "command": "python3",
  "args": ["/path/to/aws-athena-mcp/main.py"],
  "env": {
    "AWS_S3_OUTPUT_LOCATION": "s3://your-bucket/results/"
  }
}
```

### Required Environment Variables

- **AWS_S3_OUTPUT_LOCATION**: S3 location where query results will be stored

### Optional Environment Variables

- **AWS_ACCESS_KEY_ID**: AWS access key (if not using profile)
- **AWS_SECRET_ACCESS_KEY**: AWS secret key (if not using profile)
- **AWS_PROFILE**: Locally configured AWS profile
- **AWS_REGION** or **AWS_DEFAULT_REGION**: AWS region (default: us-east-1)
- **LOG_LEVEL**: Logging level (DEBUG, INFO, WARNING, ERROR)

> **⚠️ Security**: For production environments, we recommend using IAM roles or AWS profiles instead of direct credentials in the configuration file.

## 📦 Installation

### Development Installation

```bash
# Clone the repository
git clone <repository-url>
cd aws-athena-mcp

# Install in development mode
pip install -e .[dev]
```

### Production Installation

```bash
pip install .
```

## ⚙️ Configuration

Configure the following environment variables:

```bash
# AWS credentials (optional if using profile)
export AWS_ACCESS_KEY_ID="your-access-key"
export AWS_SECRET_ACCESS_KEY="your-secret-key"

# AWS region
export AWS_DEFAULT_REGION="us-east-1"

# Or use an AWS profile
export AWS_PROFILE="your-profile"

# S3 output location (required)
export AWS_S3_OUTPUT_LOCATION="s3://your-bucket/athena-results/"
```

## 🎯 Usage

### Run the Server

```bash
# Using the main entry point
python main.py

# Or using the installed command
athena-mcp
```

### Available Tools

1. **list_databases**: Lists all available databases in Athena
2. **query_athena**: Executes SQL queries in Athena
3. **describe_data_structure**: Describes the structure of a database

## 🧪 Testing

```bash
# Run all tests
pytest

# Run only unit tests
pytest tests/unit/

# Run with coverage
pytest --cov=src/athena_mcp

# Run specific tests
pytest tests/unit/test_validators.py -v
```

## 🛠️ Development

### Code Quality Tools

```bash
# Code formatting
black src/ tests/

# Import sorting
isort src/ tests/

# Type checking
mypy src/

# Linting
flake8 src/ tests/
```

### Development Environment Setup

```bash
# Install development dependencies
pip install -e .[dev]

# Or install manually
pip install pytest pytest-asyncio black isort flake8 mypy
```

## 📋 Implemented Best Practices

### Architecture

- **Separation of Concerns**: Each module has a specific responsibility
- **Dependency Inversion**: Use of interfaces and dependency injection
- **Single Responsibility Principle**: Classes and functions with single purpose
- **Factory Pattern**: For AWS client creation
- **Strategy Pattern**: For different types of formatting and validation

### Code Quality

- **Type Hints**: Static typing in all functions and methods
- **Docstrings**: Complete documentation in Google Style format
- **Error Handling**: Custom exceptions and proper handling
- **Logging**: Structured and configurable logging system
- **Validation**: Rigorous input validation

### Project Structure

- **src/ Layout**: Clear separation between source code and other files
- **Namespace Packages**: Hierarchical organization of modules
- **Test Structure**: Tests organized mirroring code structure
- **Configuration Files**: Centralized and externalized configuration

## 🔧 Troubleshooting

Consult the [TROUBLESHOOTING.md](TROUBLESHOOTING.md) file for common issues and solutions.

## 📝 Module Structure

### Core (`src/athena_mcp/core/`)
- **config.py**: Centralized system configurations
- **exceptions.py**: Custom domain exceptions

### Services (`src/athena_mcp/services/`)
- **athena_client.py**: AWS Athena client factory and management
- **athena_service.py**: High-level services for Athena operations

### Utils (`src/athena_mcp/utils/`)
- **formatters.py**: Formatters for different output types
- **helpers.py**: General helper functions and utilities
- **validators.py**: Validators for different input types

### Handlers (`src/athena_mcp/handlers/`)
- **tool_handlers.py**: Handlers for MCP tools

## 🤝 Contributing

1. Fork the project
2. Create a feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.