Skip to content

Architecture Components

AWS Logs MCP is built with a modular architecture. Each component has a specific responsibility, working together to provide the complete functionality.

Configuration Layer

The configuration layer is responsible for loading and managing all application settings, including environment variables and AWS credentials.

Key Components

  • env.ts: Loads and validates environment variables
  • aws-credentials.ts: Manages different AWS credential providers
  • aws-config.ts: Configures AWS SDK clients
  • server-config.ts: Configuration for the MCP server

Services Layer

The services layer abstracts interactions with AWS services, providing a clean API for the tools layer.

Key Components

  • cloudwatch-logs.ts: Service for interacting with CloudWatch Logs
  • cloudtrail.ts: Service for interacting with CloudTrail

These services handle:

  • AWS SDK client initialization
  • Service-specific error handling
  • Response normalization
  • Retry and pagination logic

Tools Layer

The tools layer implements the Model Context Protocol (MCP) tools, building on the services layer.

Key Components

  • cloudwatch-logs.ts: Implements CloudWatch log-related tools
  • cloudtrail.ts: Implements CloudTrail event-related tools
  • connection.ts: Implements AWS connection testing

Each tool:

  • Validates input parameters using Zod schemas
  • Calls appropriate service methods
  • Formats responses according to MCP specifications
  • Handles errors with appropriate context

Server Layer

The server layer provides transport options for the MCP protocol, supporting both HTTP and STDIO modes.

Key Components

  • mcp-server.ts: Initializes and configures the MCP server with AWS tools
  • transport.ts: Manages HTTP transport with session handling
  • middleware.ts: Express middleware for request handling and error processing

Transport Options

AWS Logs MCP supports two transport modes:

  1. STDIO Transport: Direct communication through standard input/output streams
  2. Implemented in transports/index.ts using StdioServerTransport

  3. Suitable for CLI applications and direct integration

  4. Streamable HTTP Transport: Network-based HTTP server

  5. Implemented in server/transport.ts using StreamableHTTPServerTransport
  6. Supports multiple concurrent sessions with session tracking
  7. Provides additional endpoints for health monitoring and metrics

For more details, see Transport Modes.

Utilities Layer

The utilities layer provides shared functionality used across the application.

Key Components

  • error-handling.ts: Error handling utilities and custom error classes
  • logging.ts: Structured logging utilities
  • metrics.ts: Metrics collection for monitoring
  • time-utils.ts: Time-related utilities for log querying
  • secure-config.ts: Utilities for secure configuration handling

Types Layer

The types layer provides TypeScript definitions used throughout the application.

Key Components

  • aws.ts: AWS-related types, re-exported from AWS SDK
  • tools.ts: Types for MCP tools and parameters
  • validation-schemas.ts: Zod validation schemas for tool inputs
  • config.ts: Configuration-related type definitions

Type Safety and AWS SDK Integration

AWS Logs MCP directly leverages AWS SDK types to ensure type safety and compatibility with AWS services. The aws.ts types file imports and re-exports AWS SDK types, providing:

import { LogGroup, OutputLogEvent } from "@aws-sdk/client-cloudwatch-logs";
import { Event, Resource } from "@aws-sdk/client-cloudtrail";

// Re-export AWS SDK types with aliases for backward compatibility
export type LogGroupInfo = LogGroup;
export type LogEvent = OutputLogEvent;
export type CloudTrailEventResource = Resource;
export type CloudTrailEventInfo = Event;

This approach ensures that our application keeps in sync with AWS SDK updates and provides strong typing throughout the codebase.