# Data Flow

This document explains how data flows through the AWS Logs MCP system, from client requests to AWS service interactions and back.

## MCP Connection Flow

1. **Client Connection**:
   - Client connects to the SSE endpoint (`/sse`)
   - Server creates a transport for the session
   - Client receives a unique session ID

2. **Tool Registration**:
   - Server registers available tools with their schemas and handlers
   - Client receives tool registration information

3. **Tool Invocation**:
   - Client sends a tool invocation request
   - Server validates the request against the tool's schema
   - Tool handler processes the request

4. **Response Handling**:
   - Tool handler formats the response according to MCP
   - Response is streamed back to the client through SSE
   - Client processes the response data

## AWS Service Interaction Flow

### CloudWatch Logs Flow

For CloudWatch Logs tools, the data flow is:

```mermaid
graph LR
    Client[Client] --> MCP[MCP Server]
    MCP --> ToolHandler[Tool Handler]
    ToolHandler --> Validator[Parameter Validator]
    Validator --> Service[CloudWatch Logs Service]
    Service --> AWS[AWS CloudWatch Logs API]
    AWS --> Service
    Service --> ToolHandler
    ToolHandler --> Formatter[Response Formatter]
    Formatter --> MCP
    MCP --> Client
```

1. **Request Validation**:
   - Tool handler validates parameters (log group, time range, etc.)
   - Parameters are converted to appropriate AWS SDK format

2. **Service Layer**:
   - CloudWatch Logs service constructs appropriate AWS SDK command
   - Service handles pagination for large result sets
   - Service catches and wraps AWS-specific errors

3. **Response Formatting**:
   - Log events/groups are formatted according to MCP
   - Timestamps are normalized to ISO format
   - Response is structured for client consumption

### CloudTrail Flow

For CloudTrail events, the data flow is similar:

```mermaid
graph LR
    Client[Client] --> MCP[MCP Server]
    MCP --> ToolHandler[Tool Handler]
    ToolHandler --> Validator[Parameter Validator]
    Validator --> Service[CloudTrail Service]
    Service --> AWS[AWS CloudTrail API]
    AWS --> Service
    Service --> ToolHandler
    ToolHandler --> Formatter[Response Formatter]
    Formatter --> MCP
    MCP --> Client
```

1. **Request Validation**:
   - Tool handler validates parameters (event name, time range, etc.)
   - Parameters are converted to appropriate AWS SDK format

2. **Service Layer**:
   - CloudTrail service constructs `LookupEvents` command
   - Service handles token-based pagination
   - Service catches and wraps AWS-specific errors

3. **Response Formatting**:
   - CloudTrail events are formatted according to MCP
   - Event details are structured for client consumption

## Error Flow

When errors occur, they follow a structured path:

```mermaid
graph LR
    Error[AWS Error] --> ServiceLayer[Service Layer]
    ServiceLayer --> ErrorWrapper[Error Wrapper]
    ErrorWrapper --> ToolHandler[Tool Handler]
    ToolHandler --> MCP[MCP Server]
    MCP --> Client[Client]
```

1. **Error Origin**:
   - AWS SDK throws an error
   - Service layer catches the error

2. **Error Enhancement**:
   - Error is wrapped with additional context (service, operation)
   - Error is classified (operational vs. programming)
   - Error is logged with appropriate level

3. **Error Response**:
   - Tool handler formats the error for MCP
   - MCP server sends error response to client
   - Client receives structured error information

## Metrics Flow

For observability, metrics flow as follows:

```mermaid
graph LR
    ToolHandler[Tool Handler] --> MetricsTracker[Metrics Tracker]
    MetricsTracker --> Logger[Logger]
    MetricsTracker --> CloudWatch[CloudWatch Metrics]
```

1. **Metric Collection**:
   - Tool handlers track metrics (latency, success/failure)
   - Service layer may track AWS-specific metrics

2. **Metric Publication**:
   - Metrics are logged for local monitoring
   - Metrics can be sent to CloudWatch if enabled
   - Metrics include dimensions like tool name, service, etc.