# API Reference

This document provides the API reference for the AWS Logs MCP server.

## Endpoints

The MCP server exposes the following endpoints:

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/sse` | GET | Server-Sent Events endpoint for MCP communication |
| `/mcp` | POST | Direct endpoint for MCP tool invocations |
| `/health` | GET | Health check endpoint |

## MCP Protocol

AWS Logs MCP implements the [Model Context Protocol](https://github.com/anthropics/anthropic-model-context-protocol) for AI assistant integration.

### Tool Registration

When a client connects, the server registers available tools:

```json
{
  "type": "tool_registration",
  "tools": [
    {
      "name": "cloudWatchLogGroups",
      "description": "List available CloudWatch Log Groups with optional filtering",
      "schema": {
        "type": "object",
        "properties": {
          "prefix": {
            "type": "string",
            "description": "Filter log groups by prefix"
          },
          "limit": {
            "type": "number",
            "description": "Maximum number of log groups to return"
          }
        }
      }
    },
    // Other tools...
  ]
}
```

### Tool Invocation

Clients invoke tools using:

```json
{
  "type": "tool_invocation",
  "id": "invocation-123",
  "name": "cloudWatchLogs",
  "params": {
    "logGroupName": "/aws/lambda/my-function",
    "startTime": "-1h",
    "limit": 50
  }
}
```

### Tool Response

The server responds with:

```json
{
  "type": "tool_response",
  "id": "invocation-123",
  "status": "success",
  "content": [
    {
      "type": "text",
      "text": "[2023-01-15T12:34:56.789Z] Log message content..."
    }
  ]
}
```

### Error Response

For errors, the server responds with:

```json
{
  "type": "tool_response",
  "id": "invocation-123",
  "status": "error",
  "error": {
    "type": "AWS_SERVICE_ERROR",
    "message": "Failed to retrieve logs: Access denied",
    "service": "CloudWatchLogs",
    "operation": "filterLogEvents"
  }
}
```

## Health Check

The `/health` endpoint returns information about server health:

```json
{
  "status": "healthy",
  "version": "1.0.0",
  "uptime": 3600,
  "timestamp": "2023-01-15T12:34:56.789Z",
  "aws": {
    "connectivity": true,
    "region": "us-east-1"
  },
  "memory": {
    "rss": 75000000,
    "heapTotal": 50000000,
    "heapUsed": 40000000
  }
}
```

## Direct MCP Endpoint

The `/mcp` endpoint accepts direct POST requests:

**Request:**

```json
{
  "tool": "cloudTrailEvents",
  "params": {
    "eventName": "CreateFunction",
    "startTime": "-1d",
    "limit": 25
  }
}
```

**Response:**

```json
{
  "status": "success",
  "content": [
    {
      "type": "text",
      "text": "[JSON string with CloudTrail events]"
    }
  ]
}
```

## Error Codes

| Error Code | HTTP Status | Description |
|------------|-------------|-------------|
| `VALIDATION_ERROR` | 400 | Invalid parameters |
| `AUTHENTICATION_ERROR` | 401 | AWS authentication failed |
| `PERMISSION_ERROR` | 403 | Insufficient AWS permissions |
| `RESOURCE_NOT_FOUND` | 404 | Requested resource not found |
| `AWS_SERVICE_ERROR` | 502 | AWS service error |
| `INTERNAL_ERROR` | 500 | Server internal error |