# InfraLens MCP

InfraLens MCP is a read-only Model Context Protocol server and CLI for investigating AWS ECS deployment and runtime issues. The MVP focuses on AWS ECS Fargate services behind an Application Load Balancer.

The tool is designed to answer questions such as:

```text
Why is the ECS service orders-api-service unhealthy?
```

InfraLens investigates the named service, collects evidence from AWS, correlates symptoms, and returns structured findings that explain what is failing, why it is likely failing, which evidence supports the finding, what to check next, and what remediation is recommended.

## Status

The MVP implements ECS, ELBv2, CloudWatch Logs, limited IAM failure parsing, deterministic analyzers, investigation orchestration, MCP tools, CLI output, tests, Docker, pre-commit, and CI. All AWS collection paths are read-only and use dependency-injected boto3 clients.

## Problem Statement

ECS incidents often involve overlapping signals from service events, stopped tasks, target-group health, health-check configuration, application logs, and downstream dependencies. A generic checklist is slow and can lead engineers to fix the wrong layer. InfraLens MCP produces evidence-backed findings for deployment failure, target-group configuration issues, network timeout, readiness endpoint failure, downstream dependency failure, container startup failure, and permission failure.

## Architecture

```mermaid
flowchart LR
    User["Engineer or MCP client"] --> CLI["CLI"]
    User --> MCP["MCP server"]
    CLI --> Tools["Tool adapters"]
    MCP --> Tools
    Tools --> Service["Investigation service"]
    Service --> ECSCollector["ECS collector"]
    Service --> ELBCollector["ELBv2 collector"]
    Service --> LogsCollector["CloudWatch Logs collector"]
    Service --> IAMParser["IAM failure parser"]
    ECSCollector --> ECS["Amazon ECS read APIs"]
    ELBCollector --> ELB["ELBv2 read APIs"]
    LogsCollector --> Logs["CloudWatch Logs read APIs"]
    Service --> Evidence["Evidence service"]
    Evidence --> Analyzers["Deterministic analyzers"]
    Analyzers --> Findings["Evidence-backed findings"]
    Findings --> Result["InvestigationResult"]
```

AWS SDK calls live in collectors, not MCP tool handlers. Collection, analysis, orchestration, redaction, and presentation are separate layers.

## Supported AWS Services

- Amazon ECS clusters, services, deployments, service events, running tasks, stopped tasks, and task definitions
- ELBv2 Application Load Balancers, listeners, listener rules, target groups, and target health
- CloudWatch Logs with bounded lookback windows, keyword filtering, deduplication, grouping, and redaction
- IAM-related access-denied metadata parsed from already-collected failure messages

## Installation

```bash
python -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"
```

On PowerShell:

```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"
```

## AWS Authentication

InfraLens MCP uses the standard boto3 credential chain:

- `AWS_PROFILE`
- Environment credentials
- ECS task role
- EC2 instance profile
- Web identity or OIDC credentials

Configuration variables:

```text
AWS_PROFILE
AWS_REGION
INFRALENS_LOG_LEVEL
INFRALENS_LOOKBACK_MINUTES
INFRALENS_MAX_LOG_EVENTS
INFRALENS_REDACT_ACCOUNT_IDS
INFRALENS_AWS_API_TIMEOUT_SECONDS
```

## CLI Usage

Primary investigation example:

```bash
infralens investigate \
  --cluster demo-platform-cluster \
  --service orders-api-service \
  --region us-east-1
```

JSON output:

```bash
infralens investigate \
  --cluster demo-platform-cluster \
  --service orders-api-service \
  --region us-east-1 \
  --output json
```

Service events:

```bash
infralens service-events \
  --cluster demo-platform-cluster \
  --service orders-api-service \
  --region us-east-1
```

Target health:

```bash
infralens target-health \
  --target-group-arn arn:aws:elasticloadbalancing:us-east-1:111122223333:targetgroup/orders-api-target-group/abcdef1234567890 \
  --region us-east-1
```

Search logs:

```bash
infralens search-logs \
  --log-group /ecs/orders-api-service \
  --region us-east-1 \
  --lookback-minutes 30
```

InfraLens accepts any valid cluster, service, region, target-group ARN, task-definition ARN, and log-group name through CLI arguments or MCP tool inputs. The fictional resources above are examples only.

## MCP Configuration Example

```json
{
  "mcpServers": {
    "infralens": {
      "command": "infralens-mcp",
      "args": [],
      "env": {
        "AWS_REGION": "us-east-1",
        "INFRALENS_LOOKBACK_MINUTES": "30",
        "INFRALENS_MAX_LOG_EVENTS": "200"
      }
    }
  }
}
```

Available MCP tools:

- `investigate_ecs_service`
- `inspect_ecs_service_events`
- `inspect_task_definition`
- `inspect_target_health`
- `search_service_logs`

## Example Investigation

Primary finding:

The ECS target is unhealthy because the application readiness endpoint is not returning a successful response.

Supporting evidence:

- The target group reports `Target.Timeout`.
- The ECS task is running.
- The container and target-group ports both use port `8080`.
- Application logs contain PostgreSQL authentication failures.
- The readiness endpoint checks PostgreSQL connectivity and returns HTTP `503`.

Probable root cause:

An application dependency failure rather than an ECS or target-group port configuration mismatch.

Recommended next steps:

- Verify database connectivity using the task's runtime configuration.
- Confirm that the task is receiving the expected database username.
- Validate network access between the ECS task and database.
- Separate liveness and readiness endpoints.

## Security Model

InfraLens MCP is read-only. It does not restart ECS services, force deployments, update task definitions, change security groups, modify target groups, update IAM policies, retrieve secret values, or make AWS infrastructure changes.

Runtime output redacts AWS account IDs, passwords, tokens, authorization headers, database connection strings, secret values, and personal data where detected. InfraLens does not call Secrets Manager or SSM Parameter Store to retrieve secret values.

## Required IAM Read-Only Permissions

A minimal starter IAM policy is available at `docs/iam/read-only-policy.json`. Production users should further restrict resources based on their environment.

## Optional Demo Stack

An optional Terraform example is available at `examples/demo-stack/`. It can create a disposable ECS Fargate service behind an ALB for manual collector testing. InfraLens MCP does not apply this stack and remains read-only.

## Development

```bash
python -m pip install -e ".[dev]"
python scripts/check_repository_hygiene.py
python -m ruff format --check .
python -m ruff check .
python -m mypy src
python -m pytest
```

Or run all checks:

```bash
make check
```

## Testing

The test suite uses mocked AWS responses and botocore Stubber. It covers healthy services, port mismatches, target timeouts, HTTP 503 readiness failures with PostgreSQL evidence, 404 health paths, image-pull failures, resource initialization failures, essential container exits, access-denied parsing, Redis or Valkey failures, repeated rollback, no registered targets, redaction, partial results, and read-only operation contracts.

## Roadmap

- Broader ECS deployment metadata and deployment history correlation
- Optional CloudWatch Metrics read-only summaries
- More language-specific log analyzers
- Richer MCP resources and prompts
- Packaged releases for common MCP hosts

## Contributing

Contributions should preserve the read-only safety model, include tests for new diagnosis rules, use fictional examples only, and avoid committing real infrastructure identifiers or secrets.