AWS Model Context Protocol Server

# AWS MCP Server Development Guide ## Build & Test Commands ### Using uv (recommended) - Install dependencies: `uv pip install --system -e .` - Install dev dependencies: `uv pip install --system -e ".[dev]"` - Update lock file: `uv pip compile --system pyproject.toml -o uv.lock` - Install from lock file: `uv pip sync --system uv.lock` ### Using pip (alternative) - Install dependencies: `pip install -e .` - Install dev dependencies: `pip install -e ".[dev]"` ### Running the server - Run server: `python -m aws_mcp_server` - Run server with SSE transport: `AWS_MCP_TRANSPORT=sse python -m aws_mcp_server` - Run with MCP CLI: `mcp run src/aws_mcp_server/server.py` ### Testing and linting - Run tests: `pytest` - Run single test: `pytest tests/path/to/test_file.py::test_function_name -v` - Run tests with coverage: `python -m pytest --cov=src/aws_mcp_server tests/` - Run linter: `ruff check src/ tests/` - Format code: `ruff format src/ tests/` ## Technical Stack - **Python version**: Python 3.13+ - **Project config**: `pyproject.toml` for configuration and dependency management - **Environment**: Use virtual environment in `.venv` for dependency isolation - **Package management**: Use `uv` for faster, more reliable dependency management with lock file - **Dependencies**: Separate production and dev dependencies in `pyproject.toml` - **Version management**: Use `setuptools_scm` for automatic versioning from Git tags - **Linting**: `ruff` for style and error checking - **Type checking**: Use VS Code with Pylance for static type checking - **Project layout**: Organize code with `src/` layout ## Code Style Guidelines - **Formatting**: Black-compatible formatting via `ruff format` - **Imports**: Sort imports with `ruff` (stdlib, third-party, local) - **Type hints**: Use native Python type hints (e.g., `list[str]` not `List[str]`) - **Documentation**: Google-style docstrings for all modules, classes, functions - **Naming**: snake_case for variables/functions, PascalCase for classes - **Function length**: Keep functions short (< 30 lines) and single-purpose - **PEP 8**: Follow PEP 8 style guide (enforced via `ruff`) ## Python Best Practices - **File handling**: Prefer `pathlib.Path` over `os.path` - **Debugging**: Use `logging` module instead of `print` - **Error handling**: Use specific exceptions with context messages and proper logging - **Data structures**: Use list/dict comprehensions for concise, readable code - **Function arguments**: Avoid mutable default arguments - **Data containers**: Leverage `dataclasses` to reduce boilerplate - **Configuration**: Use environment variables (via `python-dotenv`) for configuration - **AWS CLI**: Validate all commands before execution (must start with "aws") - **Security**: Never store/log AWS credentials, set command timeouts ## Development Patterns & Best Practices - **Favor simplicity**: Choose the simplest solution that meets requirements - **DRY principle**: Avoid code duplication; reuse existing functionality - **Configuration management**: Use environment variables for different environments - **Focused changes**: Only implement explicitly requested or fully understood changes - **Preserve patterns**: Follow existing code patterns when fixing bugs - **File size**: Keep files under 300 lines; refactor when exceeding this limit - **Test coverage**: Write comprehensive unit and integration tests with `pytest`; include fixtures - **Test structure**: Use table-driven tests with parameterization for similar test cases - **Mocking**: Use unittest.mock for external dependencies; don't test implementation details - **Modular design**: Create reusable, modular components - **Logging**: Implement appropriate logging levels (debug, info, error) - **Error handling**: Implement robust error handling for production reliability - **Security best practices**: Follow input validation and data protection practices - **Performance**: Optimize critical code sections when necessary - **Dependency management**: Add libraries only when essential - When adding/updating dependencies, update `pyproject.toml` first - Regenerate the lock file with `uv pip compile --system pyproject.toml -o uv.lock` - Install the new dependencies with `uv pip sync --system uv.lock` ## Development Workflow - **Version control**: Commit frequently with clear messages - **Versioning**: Use Git tags for versioning (e.g., `git tag -a 1.2.3 -m "Release 1.2.3"`) - For releases, create and push a tag - For development, let `setuptools_scm` automatically determine versions - **Impact assessment**: Evaluate how changes affect other codebase areas - **Documentation**: Keep documentation up-to-date for complex logic and features - **Dependencies**: When adding dependencies, always update the `uv.lock` file - **CI/CD**: All changes should pass CI checks (tests, linting, etc.) before merging