Development Guide

This guide covers the development workflow of MCP Proxy for AWS.

Prerequisites
Development Environment Setup
Project Structure
Development Workflow
Running and Testing
Code Quality
Contributing Guidelines
Troubleshooting

Prerequisites

Before you begin development, ensure you have the following installed:

Python 3.10+: Download Python
uv package manager: Install uv
AWS CLI: Install and configure AWS CLI
Git: For version control
Pre-commit: Will be installed automatically with dev dependencies

Development Environment Setup

1. Clone and Setup the Project

# Clone the repository
git clone git@github.com:aws/mcp-proxy-for-aws.git
cd mcp-proxy-for-aws

# Install dependencies including dev dependencies
uv sync --group dev

# Install pre-commit hooks
uv run pre-commit install

2. Verify Installation

# Check that the server can start
uv run mcp_proxy_for_aws/server.py --help

# Run tests to ensure everything is working
uv run pytest

Project Structure

mcp_proxy_for_aws/
├── __init__.py              # Package initialization
├── server.py                # Main MCP server implementation
├── mcp_proxy_manager.py     # MCP proxy management logic
├── sigv4_helper.py          # AWS SigV4 authentication helper
├── logging_config.py        # Logging configuration
└── utils.py                 # Utility functions

tests/
├── test_init.py             # Package tests
├── test_server.py           # Server tests
├── test_mcp_proxy_manager.py # Proxy manager tests
├── test_sigv4_helper.py     # SigV4 helper tests
├── test_logging_config.py   # Logging tests
├── test_utils.py            # Utility tests
└── test_main.py             # Main integration tests

pyproject.toml               # Project configuration
.pre-commit-config.yaml      # Pre-commit hooks configuration
README.md                    # Project documentation
DEVELOPMENT.md               # This file

Development Workflow

1. Creating a Feature Branch

# Create and switch to a new feature branch
git checkout -b feature/your-feature-name

# Make your changes
# ...

# Commit your changes
git add .
git commit -m "feat: add new feature description"

2. Running the Server Locally

Basic Local Execution

# Run the server directly
uv run mcp_proxy_for_aws/server.py <your-endpoint>

With MCP Inspector (for debugging)

# Run with MCP inspector for interactive debugging
npx @modelcontextprotocol/inspector uv run \
  mcp_proxy_for_aws/server.py <your-endpoint>

A browser window will open automatically outside of your terminal window. Navigate to the browser window. Then click "Connect" in the opened browser window to interact with the server.

Advanced Options

# Run with specific AWS profile and write permissions
uv run mcp_proxy_for_aws/server.py <your-endpoint> \
  --service <aws-service> \
  --profile <aws-profile> \
  --allow-write

Running and Testing

Running Tests

# Run all tests
uv run pytest

# Run tests with coverage
uv run pytest --cov --cov-branch --cov-report=term-missing

# Run tests in verbose mode
uv run pytest -v

# Run specific test file
uv run pytest tests/test_server.py

# Run tests with specific marker (if any)
uv run pytest -m "not live"

Test Coverage Requirements

The project maintains high test coverage standards:

Minimum Coverage: 80% (target: 90%+)
Branch Coverage: Required
Coverage Report: Generated with --cov-report=term-missing

Code Quality

Linting and Formatting

The project uses several tools for code quality:

# Run ruff linting
uv run ruff check

# Fix auto-fixable ruff issues
uv run ruff check --fix

# Format code with ruff
uv run ruff format

# Run type checking with pyright
uv run pyright

# Run all pre-commit hooks manually
uv run pre-commit run --all-files

Code Style Guidelines

Line Length: 99 characters (configured in pyproject.toml)
Quote Style: Single quotes preferred
Import Organization: Handled by ruff (isort profile)
Docstrings: Google style convention
Type Hints: Required for all public functions

Pre-commit Hooks

The project uses pre-commit hooks that run automatically before each commit:

File Validation: JSON, YAML, TOML syntax checking
Security: Detect private keys and AWS credentials
Code Quality: Ruff linting and formatting
Conventional Commits: Enforces commit message format

Contributing Guidelines

Commit Message Format

Follow the Conventional Commits specification:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Types:

feat: New feature
fix: Bug fix
docs: Documentation changes
style: Code style changes (formatting, etc.)
refactor: Code refactoring
test: Adding or updating tests
chore: Maintenance tasks

Examples:

git commit -m "feat(auth): add SigV4 authentication support"
git commit -m "fix(server): handle connection timeouts gracefully"
git commit -m "docs: update development setup instructions"

Code Review Process

Using Commitizen

This project uses Commitizen to enforce conventional commit messages and automate version management. Commitizen is integrated into the pre-commit hooks and provides several useful features.

When to Use Commitizen

Use cz commit when:

You want guided commit message creation
You're unsure about conventional commit format
You want to ensure your commit follows the project standards
You're making your first commits to the project

Use regular git commit when:

You're comfortable with conventional commit format
You want faster commit workflow
You're making quick fixes or documentation updates

Interactive Commit Creation

# Use Commitizen interactive mode for guided commit creation
uv run cz commit

# Alternative shorter command
uv run cz c

This will guide you through:

Type selection: Choose from feat, fix, docs, style, refactor, test, chore, etc.
Scope (optional): Specify what part of the codebase is affected
Description: Write a concise description of the change
Body (optional): Add detailed explanation if needed
Breaking changes (optional): Describe any breaking changes
Footer (optional): Reference issues, etc.

Version Management and Releases

Commitizen automates version bumping and changelog generation:

# Bump version automatically based on conventional commits
uv run cz bump

# Preview what the next version would be (dry run)
uv run cz bump --dry-run

# Bump to a specific version type
uv run cz bump --increment PATCH   # 0.1.0 -> 0.1.1
uv run cz bump --increment MINOR   # 0.1.0 -> 0.2.0
uv run cz bump --increment MAJOR   # 0.1.0 -> 1.0.0

# Generate changelog without bumping version
uv run cz changelog

Pre-commit Integration

Commitizen runs automatically through pre-commit hooks:

commitizen hook: Validates commit message format
commitizen-branch hook: Runs on pre-push to ensure branch is ready

If your commit message doesn't follow conventional format, the pre-commit hook will fail with guidance.

Configuration

Commitizen is configured in pyproject.toml:

Version files: Automatically updates version in pyproject.toml and mcp_proxy_for_aws/__init__.py
Tag format: Creates git tags in v{version} format (e.g., v0.1.0)
Changelog: Automatically generates CHANGELOG.md when bumping versions

Common Commitizen Workflow

# Make your changes
git add .

# Create commit with Commitizen (interactive)
uv run cz commit

# OR use regular git commit if you know the format
git commit -m "feat(auth): add SigV4 request signing"

# Before release, bump version and generate changelog
uv run cz bump

# Push changes and tags
git push && git push --tags

Troubleshooting Commitizen

# Check current version
uv run cz version

# Validate commit message format
echo "your commit message" | uv run cz check

# Check what commits would be included in next bump
uv run cz bump --dry-run --changelog

# Fix version if it gets out of sync
uv run cz bump --increment PATCH --yes

Code Review Process

Create Feature Branch: Branch from main on your own fork
Implement Changes: Follow coding standards
Write Tests: Ensure adequate test coverage
Run Quality Checks: All linting and tests must pass
Create Pull Request: Include clear description and context
Address Feedback: Respond to review comments
Merge: Once approved and CI passes

Adding New Features

When adding new features:

Design First: Consider the MCP specification and AWS service integration
Add Tests: Write tests before or alongside implementation
Update Documentation: Update README.md and relevant docs
Error Handling: Implement proper error handling and logging
AWS Integration: Follow AWS SDK best practices for authentication and retries

Dependencies

Adding Dependencies: Add to dependencies in pyproject.toml
Dev Dependencies: Add to dev dependency group
Security: Regularly update dependencies for security patches

Troubleshooting

Common Issues

UV Package Manager Issues

# Clear uv cache
uv cache clean

# Reinstall dependencies
rm uv.lock
uv sync --group dev

Test Failures

# Run tests in verbose mode for more details
uv run pytest -v -s

# Run specific failing test
uv run pytest tests/test_specific.py::test_function_name -v

Debug Mode

Enable debug logging for troubleshooting:

# Set logging level to debug
export LOG_LEVEL=DEBUG
uv run mcp_proxy_for_aws/server.py <endpoint>

Additional Resources

For questions or issues not covered in this guide, please:

Check existing GitHub Issues
Review the MCP Specification
Create a new issue with detailed information about your problem

FilesExpand file tree

DEVELOPMENT.md

Latest commit

History

DEVELOPMENT.md

File metadata and controls

Development Guide

Table of Contents

Prerequisites

Development Environment Setup

1. Clone and Setup the Project

2. Verify Installation

Project Structure

Development Workflow

1. Creating a Feature Branch

2. Running the Server Locally

Basic Local Execution

With MCP Inspector (for debugging)

Advanced Options

Running and Testing

Running Tests

Test Coverage Requirements

Code Quality

Linting and Formatting

Code Style Guidelines

Pre-commit Hooks

Contributing Guidelines

Commit Message Format

Code Review Process

Using Commitizen

When to Use Commitizen

Interactive Commit Creation

Version Management and Releases

Pre-commit Integration

Configuration

Common Commitizen Workflow

Troubleshooting Commitizen

Code Review Process

Adding New Features

Dependencies

Troubleshooting

Common Issues

UV Package Manager Issues

Test Failures

Debug Mode

Additional Resources