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 goal is to answer questions such as:

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

InfraLens MCP is designed to investigate the named service, collect evidence, correlate symptoms, and explain what is failing, why it is likely failing, which evidence supports the finding, what to check next, and what remediation is recommended.

Current Status

This repository currently contains the Phase 1 foundation plus Phase 2 ECS and ELBv2 collectors. The collectors use injected boto3 clients, bounded read-only operations, pagination, redaction, and Stubber-backed tests. CloudWatch Logs collection, IAM parsing, analyzers, the MCP server, and full CLI execution are intentionally deferred and do not return fake success.

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 error-prone. InfraLens MCP will provide evidence-backed diagnosis for scenarios such as deployment failure, target-group configuration issues, network timeout, readiness endpoint failure, downstream dependency failure, container startup failure, and permission failure.

Architecture

flowchart LR
    User["Engineer or MCP client"] --> CLI["CLI"]
    User --> MCP["MCP server"]
    CLI --> Service["Investigation service"]
    MCP --> Service
    Service --> Collectors["Read-only AWS collectors"]
    Collectors --> ECS["Amazon ECS"]
    Collectors --> ELB["ELBv2 and target groups"]
    Collectors --> Logs["CloudWatch Logs"]
    Collectors --> IAM["IAM failure metadata"]
    Service --> Redaction["Redaction service"]
    Service --> Analyzers["Deterministic analyzers"]
    Analyzers --> Result["Evidence-backed findings"]

AWS SDK calls live in collectors, not MCP tool handlers. Analysis, presentation, and collection remain separate.

Supported AWS Services

Planned MVP read-only coverage:

• Amazon ECS services, deployments, tasks, task definitions, and service events
• ELBv2 load balancers, listeners, rules, target groups, and target health
• CloudWatch Logs with bounded lookback windows
• IAM-related failure metadata parsed from service and task failures

Installation

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:

AWS_PROFILE
AWS_REGION
INFRALENS_LOG_LEVEL
INFRALENS_LOOKBACK_MINUTES
INFRALENS_MAX_LOG_EVENTS
INFRALENS_REDACT_ACCOUNT_IDS

CLI Usage

Primary investigation example:

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

Service events example:

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

Target health example:

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

The application accepts any valid cluster, service, region, target-group ARN, task-definition ARN, or log-group name through CLI arguments or MCP tool inputs.

MCP Configuration Example

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

The MCP server command will be finalized in Phase 6.

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 must not restart 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.

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

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

Roadmap

• Phase 2: ECS and ELBv2 collectors with mocked AWS tests - complete
• Phase 3: Evidence service and deterministic analyzers
• Phase 4: CloudWatch Logs collection and log analyzer
• Phase 5: Investigation orchestration and partial-failure handling
• Phase 6: MCP tools and full CLI output
• Phase 7: Container, release, and documentation hardening

Contributing

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