Development Guide

This guide covers setting up the development environment, running tests, and contributing to AWS MCP Server.

Requirements

• Python 3.13+
• AWS CLI installed and configured
• Docker (optional, for containerized testing)

Development Setup

Using pip

# Clone repository
git clone https://github.com/alexei-led/aws-mcp-server.git
cd aws-mcp-server

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install runtime dependencies
pip install -e .

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

Using uv (Recommended)

uv provides faster dependency management:

# Install uv
pip install uv

# Install runtime dependencies
make uv-install

# Install development dependencies
make uv-dev-install

Running the Server

# Standard mode (stdio transport)
python -m aws_mcp_server

# Streamable HTTP transport mode (recommended over SSE)
AWS_MCP_TRANSPORT=streamable-http python -m aws_mcp_server

# SSE transport mode (deprecated, use streamable-http instead)
AWS_MCP_TRANSPORT=sse python -m aws_mcp_server

# With sandbox disabled (for development)
AWS_MCP_SANDBOX=disabled python -m aws_mcp_server

# Using MCP CLI
mcp run src/aws_mcp_server/server.py

Makefile Commands

The project includes a Makefile with targets for common tasks:

Test Commands

make test             # Run unit tests (excludes integration)
make test-unit        # Run unit tests only
make test-integration # Run integration tests (requires AWS credentials)
make test-all         # Run all tests including integration

Coverage

make test-coverage     # Coverage report (excludes integration)
make test-coverage-all # Coverage report (includes integration)

Linting and Formatting

make lint      # Run linters (ruff check, format --check)
make lint-fix  # Run linters and auto-fix issues
make format    # Format code with ruff

Full List

Run make help to see all available commands.

Testing

Unit Tests

# Run all unit tests
pytest

# Run specific test file
pytest tests/path/to/test_file.py

# Run specific test function
pytest tests/path/to/test_file.py::test_function_name -v

# Run with coverage
python -m pytest --cov=src/aws_mcp_server tests/

Integration Tests

Integration tests verify functionality with actual AWS resources:

1. Set up AWS resources:

   # Create an S3 bucket for testing
   aws s3 mb s3://your-test-bucket-name
   
   # Set environment variable
   export AWS_TEST_BUCKET=your-test-bucket-name
   

2. Run integration tests:

   # All tests including integration
   make test-all
   
   # Only integration tests
   make test-integration
   
   # Or using pytest directly
   pytest --run-integration -m integration
   

Code Style

Formatting

• Use ruff format (Black-compatible)
• Run make format before committing

Linting

• Use ruff check for linting
• Run make lint to check, make lint-fix to auto-fix

Type Hints

Use native Python type hints:

# Good
def process_items(items: list[str]) -> dict[str, int]:
    ...

# Avoid (old style)
from typing import List, Dict
def process_items(items: List[str]) -> Dict[str, int]:
    ...

Docstrings

Use Google-style docstrings:

def execute_command(command: str, timeout: int = 300) -> str:
    """Execute an AWS CLI command.

    Args:
        command: The AWS CLI command to execute.
        timeout: Maximum execution time in seconds.

    Returns:
        The command output as a string.

    Raises:
        CommandExecutionError: If the command fails to execute.
        TimeoutError: If the command exceeds the timeout.
    """

Project Structure

aws-mcp-server/
├── src/aws_mcp_server/    # Main source code
│   ├── __init__.py
│   ├── __main__.py        # Entry point
│   ├── server.py          # MCP server implementation
│   ├── cli_executor.py    # AWS CLI execution with error handling
│   ├── sandbox.py         # OS-level sandbox execution
│   ├── tools.py           # Pipe command utilities
│   ├── config.py          # Configuration settings
│   ├── resources.py       # MCP resources (profiles, regions)
│   └── prompts.py         # Prompt templates
├── tests/                 # Test files
│   ├── unit/              # Unit tests
│   └── integration/       # Integration tests
├── deploy/docker/         # Docker deployment files
└── docs/                  # Documentation

Versioning

The project uses setuptools_scm for automatic version management based on Git tags.

Version Format

• Release versions: Git tag (e.g., 1.2.3)
• Development versions: <tag>.post<commits>+g<hash>.d<date> (e.g., 1.2.3.post10+gb697684.d20250406)

Creating a Release

# Create and push a tag
git tag -a 1.2.3 -m "Release version 1.2.3"
git push origin 1.2.3

The CI/CD pipeline automatically builds and publishes Docker images with version tags.

For more details, see VERSION.md.

Dependency Management

Adding Dependencies

1. Add to pyproject.toml under dependencies or [project.optional-dependencies]
2. Regenerate lock file: uv pip compile --system pyproject.toml -o uv.lock
3. Install: uv pip sync --system uv.lock

Lock File

The uv.lock file ensures reproducible builds. Always update it when changing dependencies.

Docker Development

The Docker image uses a pre-built Python wheel for faster builds and consistent versioning.

Building the Image

# Step 1: Build the Python wheel (required)
uv build

# Step 2: Build Docker image
docker build -f deploy/docker/Dockerfile -t aws-mcp-server .

The wheel in dist/ contains the correct version from setuptools_scm. This approach:

• Reuses the same versioned package across CI, PyPI, and Docker
• Speeds up Docker builds (no Python build inside container)
• Ensures version consistency between pip install aws-mcp and Docker image

Running in Docker

# Using docker-compose
docker compose -f deploy/docker/docker-compose.yml up -d

# Using docker run
docker run -i --rm \
  -v ~/.aws:/home/appuser/.aws:ro \
  aws-mcp-server

Troubleshooting

Common Issues

Import errors: Ensure you installed in development mode (pip install -e .)

AWS credential errors: Verify ~/.aws/credentials or environment variables are set

Test failures: Check AWS_TEST_BUCKET is set for integration tests

Sandbox errors: Verify kernel support (Linux 5.13+ for Landlock) or install Bubblewrap

Debug Mode

Enable debug logging:

export LOG_LEVEL=DEBUG
python -m aws_mcp_server