Skip to content

Architecture Overview

AWS Logs MCP follows a clean, modular architecture designed for maintainability, testability, and extensibility.

Overall Architecture

The project is structured around several core layers, each with a specific responsibility:

  • Configuration Layer: Manages environment variables, AWS credentials, and server settings
  • Services Layer: Implements AWS service interactions
  • Tools Layer: Implements MCP tools using the service layer
  • Server Layer: Provides HTTP and SSE transport for the MCP protocol
  • Utilities Layer: Provides shared functionality across the application

This separation ensures that each component has a single responsibility and can be tested and maintained independently.

Key Architectural Principles

  1. Separation of Concerns: Each module has a specific responsibility
  2. Type Safety: Strong typing throughout the application using TypeScript and direct AWS SDK types
  3. Consistent Error Handling: Standardized error handling with detailed context
  4. Security First: Secure credential handling and proper permission management
  5. Testability: Components designed for easy testing
  6. Extensibility: Easy to add new tools and services
  7. Flexible Transport: Supports both STDIO and HTTP transport modes for different use cases

Directory Structure

src/
├── config/             # Configuration handling
│   ├── aws-config.ts   # AWS client configuration
│   ├── aws-credentials.ts # AWS credential providers
│   ├── env.ts          # Environment variable handling
│   └── server-config.ts # Server configuration
├── services/           # Core AWS service implementations
│   ├── aws/            
│   │   ├── cloudwatch-logs.ts # CloudWatch service layer
│   │   └── cloudtrail.ts      # CloudTrail service layer
├── tools/              # MCP tool implementations
│   ├── aws/            
│   │   ├── connection.ts      # AWS connectivity testing
│   │   ├── cloudwatch-logs.ts # CloudWatch tools
│   │   └── cloudtrail.ts      # CloudTrail tools
├── server/             # Server implementation
│   ├── mcp-server.ts   # MCP server setup
│   ├── middleware.ts   # Express middleware
│   └── transport.ts    # SSE transport management
├── utils/              # Shared utilities
│   ├── error-handling.ts  # Error handling utilities
│   ├── logging.ts      # Logging utilities
│   ├── metrics.ts      # Metrics collection
│   ├── secure-config.ts # Secure configuration utilities
│   └── time-utils.ts   # Time manipulation utilities
└── types/              # Type definitions
    ├── aws.ts          # AWS-related types (imports from AWS SDK)
    ├── tools.ts        # Tool-related types
    ├── validation-schemas.ts # Input validation schemas
    └── config.ts       # Configuration types