awslabs.eks-mcp-server 0.1.1__py3-none-any.whl

awslabs/eks_mcp_server/logging_helper.py

@@ -0,0 +1,52 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except in compliance
+# with the License. A copy of the License is located at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# or in the 'license' file accompanying this file. This file is distributed on an 'AS IS' BASIS, WITHOUT WARRANTIES
+# OR CONDITIONS OF ANY KIND, express or implied. See the License for the specific language governing permissions
+# and limitations under the License.
+
+"""Logging helper for the EKS MCP Server."""
+
+from enum import Enum
+from loguru import logger
+from mcp.server.fastmcp import Context
+from typing import Any
+
+
+class LogLevel(Enum):
+    """Enum for log levels."""
+
+    DEBUG = 'debug'
+    INFO = 'info'
+    WARNING = 'warning'
+    ERROR = 'error'
+    CRITICAL = 'critical'
+
+
+def log_with_request_id(ctx: Context, level: LogLevel, message: str, **kwargs: Any) -> None:
+    """Log a message with the request ID from the context.
+
+    Args:
+        ctx: The MCP context containing the request ID
+        level: The log level (from LogLevel enum)
+        message: The message to log
+        **kwargs: Additional fields to include in the log message
+    """
+    # Format the log message with request_id
+    log_message = f'[request_id={ctx.request_id}] {message}'
+
+    # Log at the appropriate level
+    if level == LogLevel.DEBUG:
+        logger.debug(log_message, **kwargs)
+    elif level == LogLevel.INFO:
+        logger.info(log_message, **kwargs)
+    elif level == LogLevel.WARNING:
+        logger.warning(log_message, **kwargs)
+    elif level == LogLevel.ERROR:
+        logger.error(log_message, **kwargs)
+    elif level == LogLevel.CRITICAL:
+        logger.critical(log_message, **kwargs)

awslabs/eks_mcp_server/models.py

@@ -0,0 +1,271 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except in compliance
+# with the License. A copy of the License is located at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# or in the 'license' file accompanying this file. This file is distributed on an 'AS IS' BASIS, WITHOUT WARRANTIES
+# OR CONDITIONS OF ANY KIND, express or implied. See the License for the specific language governing permissions
+# and limitations under the License.
+
+"""Data models for the EKS MCP Server."""
+
+from enum import Enum
+from mcp.types import CallToolResult
+from pydantic import BaseModel, Field
+from typing import Any, Dict, List, Optional, Union
+
+
+class EventItem(BaseModel):
+    """Summary of a Kubernetes event.
+
+    This model represents a Kubernetes event with timestamps, message, and metadata.
+    Events provide information about state changes and important occurrences in the cluster.
+    """
+
+    first_timestamp: Optional[str] = Field(
+        None, description='First timestamp of the event in ISO format'
+    )
+    last_timestamp: Optional[str] = Field(
+        None, description='Last timestamp of the event in ISO format'
+    )
+    count: Optional[int] = Field(None, description='Count of occurrences', ge=0)
+    message: str = Field(..., description='Event message describing what happened')
+    reason: Optional[str] = Field(
+        None, description='Short, machine-understandable reason for the event'
+    )
+    reporting_component: Optional[str] = Field(
+        None, description='Component that reported the event (e.g., kubelet, controller-manager)'
+    )
+    type: Optional[str] = Field(None, description='Event type (Normal, Warning)')
+
+
+class Operation(str, Enum):
+    """Kubernetes resource operations for single resources."""
+
+    CREATE = 'create'
+    REPLACE = 'replace'
+    PATCH = 'patch'
+    DELETE = 'delete'
+    READ = 'read'
+
+
+class ApplyYamlResponse(CallToolResult):
+    """Response model for apply_yaml tool."""
+
+    force_applied: bool = Field(
+        False, description='Whether force option was used to update existing resources'
+    )
+    resources_created: int = Field(0, description='Number of resources created')
+    resources_updated: int = Field(0, description='Number of resources updated (when force=True)')
+
+
+class KubernetesResourceResponse(CallToolResult):
+    """Response model for single Kubernetes resource operations."""
+
+    kind: str = Field(..., description='Kind of the Kubernetes resource')
+    name: str = Field(..., description='Name of the Kubernetes resource')
+    namespace: Optional[str] = Field(None, description='Namespace of the Kubernetes resource')
+    api_version: str = Field(..., description='API version of the Kubernetes resource')
+    operation: str = Field(
+        ..., description='Operation performed (create, replace, patch, delete, read)'
+    )
+    resource: Optional[Dict[str, Any]] = Field(
+        None, description='Resource data (for read operation)'
+    )
+
+
+class ResourceSummary(BaseModel):
+    """Summary of a Kubernetes resource."""
+
+    name: str = Field(..., description='Name of the resource')
+    namespace: Optional[str] = Field(None, description='Namespace of the resource')
+    creation_timestamp: Optional[str] = Field(None, description='Creation timestamp')
+    labels: Optional[Dict[str, str]] = Field(None, description='Resource labels')
+    annotations: Optional[Dict[str, str]] = Field(None, description='Resource annotations')
+
+
+class KubernetesResourceListResponse(CallToolResult):
+    """Response model for list_resources tool."""
+
+    kind: str = Field(..., description='Kind of the Kubernetes resources')
+    api_version: str = Field(..., description='API version of the Kubernetes resources')
+    namespace: Optional[str] = Field(None, description='Namespace of the Kubernetes resources')
+    count: int = Field(..., description='Number of resources found')
+    items: List[ResourceSummary] = Field(..., description='List of resources')
+
+
+class ApiVersionsResponse(CallToolResult):
+    """Response model for list_api_versions tool."""
+
+    cluster_name: str = Field(..., description='Name of the EKS cluster')
+    api_versions: List[str] = Field(..., description='List of available API versions')
+    count: int = Field(..., description='Number of API versions')
+
+
+class GenerateAppManifestResponse(CallToolResult):
+    """Response model for generate_app_manifest tool."""
+
+    output_file_path: str = Field(..., description='Path to the output manifest file')
+
+
+class PodLogsResponse(CallToolResult):
+    """Response model for get_pod_logs tool."""
+
+    pod_name: str = Field(..., description='Name of the pod')
+    namespace: str = Field(..., description='Namespace of the pod')
+    container_name: Optional[str] = Field(None, description='Container name (if specified)')
+    log_lines: List[str] = Field(..., description='Pod log lines')
+
+
+class EventsResponse(CallToolResult):
+    """Response model for get_k8s_events tool."""
+
+    involved_object_kind: str = Field(..., description='Kind of the involved object')
+    involved_object_name: str = Field(..., description='Name of the involved object')
+    involved_object_namespace: Optional[str] = Field(
+        None, description='Namespace of the involved object'
+    )
+    count: int = Field(..., description='Number of events found')
+    events: List[EventItem] = Field(..., description='List of events')
+
+
+class CloudWatchLogEntry(BaseModel):
+    """Model for a CloudWatch log entry.
+
+    This model represents a single log entry from CloudWatch logs,
+    containing a timestamp and the log message.
+    """
+
+    timestamp: str = Field(..., description='Timestamp of the log entry in ISO format')
+    message: str = Field(..., description='Log message content')
+
+
+class CloudWatchLogsResponse(CallToolResult):
+    """Response model for get_cloudwatch_logs tool.
+
+    This model contains the response from a CloudWatch logs query,
+    including resource information, time range, and log entries.
+    """
+
+    resource_type: str = Field(..., description='Resource type (pod, node, container)')
+    resource_name: str = Field(..., description='Resource name')
+    cluster_name: str = Field(..., description='Name of the EKS cluster')
+    log_type: str = Field(
+        ..., description='Log type (application, host, performance, control-plane, or custom)'
+    )
+    log_group: str = Field(..., description='CloudWatch log group name')
+    start_time: str = Field(..., description='Start time in ISO format')
+    end_time: str = Field(..., description='End time in ISO format')
+    log_entries: List[Dict[str, Any]] = Field(
+        ..., description='Log entries with timestamps and messages'
+    )
+
+
+class CloudWatchDataPoint(BaseModel):
+    """Model for a CloudWatch metric data point.
+
+    This model represents a single data point from CloudWatch metrics,
+    containing a timestamp and the corresponding metric value.
+    """
+
+    timestamp: str = Field(..., description='Timestamp of the data point in ISO format')
+    value: float = Field(..., description='Metric value')
+
+
+class CloudWatchMetricsResponse(CallToolResult):
+    """Response model for get_cloudwatch_metrics tool.
+
+    This model contains the response from a CloudWatch metrics query,
+    including resource information, metric details, time range, and data points.
+    """
+
+    resource_type: str = Field(..., description='Resource type (pod, node, container, cluster)')
+    resource_name: str = Field(..., description='Resource name')
+    cluster_name: str = Field(..., description='Name of the EKS cluster')
+    metric_name: str = Field(..., description='Metric name (e.g., cpu_usage_total, memory_rss)')
+    namespace: str = Field(..., description='CloudWatch namespace (e.g., ContainerInsights)')
+    start_time: str = Field(..., description='Start time in ISO format')
+    end_time: str = Field(..., description='End time in ISO format')
+    data_points: List[Dict[str, Any]] = Field(
+        ..., description='Metric data points with timestamps and values'
+    )
+
+
+class StackSummary(BaseModel):
+    """Summary of a CloudFormation stack."""
+
+    stack_name: str = Field(..., description='Name of the CloudFormation stack')
+    stack_id: str = Field(..., description='ID of the CloudFormation stack')
+    cluster_name: str = Field(..., description='Name of the EKS cluster')
+    creation_time: str = Field(..., description='Creation time of the stack')
+    stack_status: str = Field(..., description='Current status of the stack')
+    description: Optional[str] = Field(None, description='Description of the stack')
+
+
+class GenerateTemplateResponse(CallToolResult):
+    """Response model for generate operation of manage_eks_stacks tool."""
+
+    template_path: str = Field(..., description='Path to the generated template')
+
+
+class DeployStackResponse(CallToolResult):
+    """Response model for deploy operation of manage_eks_stacks tool."""
+
+    stack_name: str = Field(..., description='Name of the CloudFormation stack')
+    stack_arn: str = Field(..., description='ARN of the CloudFormation stack')
+    cluster_name: str = Field(..., description='Name of the EKS cluster')
+
+
+class DescribeStackResponse(CallToolResult):
+    """Response model for describe operation of manage_eks_stacks tool."""
+
+    stack_name: str = Field(..., description='Name of the CloudFormation stack')
+    stack_id: str = Field(..., description='ID of the CloudFormation stack')
+    cluster_name: str = Field(..., description='Name of the EKS cluster')
+    creation_time: str = Field(..., description='Creation time of the stack')
+    stack_status: str = Field(..., description='Current status of the stack')
+    outputs: Dict[str, str] = Field(..., description='Stack outputs')
+
+
+class DeleteStackResponse(CallToolResult):
+    """Response model for delete operation of manage_eks_stacks tool."""
+
+    stack_name: str = Field(..., description='Name of the deleted CloudFormation stack')
+    stack_id: str = Field(..., description='ID of the deleted CloudFormation stack')
+    cluster_name: str = Field(..., description='Name of the EKS cluster')
+
+
+class PolicySummary(BaseModel):
+    """Summary of an IAM policy."""
+
+    policy_type: str = Field(..., description='Type of the policy (Managed or Inline)')
+    description: Optional[str] = Field(None, description='Description of the policy')
+    policy_document: Optional[Dict[str, Any]] = Field(None, description='Policy document')
+
+
+class RoleDescriptionResponse(CallToolResult):
+    """Response model for get_policies_for_role tool."""
+
+    role_arn: str = Field(..., description='ARN of the IAM role')
+    assume_role_policy_document: Dict[str, Any] = Field(
+        ..., description='Assume role policy document'
+    )
+    description: Optional[str] = Field(None, description='Description of the IAM role')
+    managed_policies: List[PolicySummary] = Field(
+        ..., description='Managed policies attached to the IAM role'
+    )
+    inline_policies: List[PolicySummary] = Field(
+        ..., description='Inline policies embedded in the IAM role'
+    )
+
+
+class AddInlinePolicyResponse(CallToolResult):
+    """Response model for add_inline_policy tool."""
+
+    policy_name: str = Field(..., description='Name of the inline policy to create')
+    role_name: str = Field(..., description='Name of the role to add the policy to')
+    permissions_added: Union[Dict[str, Any], List[Dict[str, Any]]] = Field(
+        ..., description='Permissions to include in the policy (in JSON format)'
+    )

awslabs/eks_mcp_server/server.py

@@ -0,0 +1,151 @@
+# Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except in compliance
+# with the License. A copy of the License is located at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+# or in the 'license' file accompanying this file. This file is distributed on an 'AS IS' BASIS, WITHOUT WARRANTIES
+# OR CONDITIONS OF ANY KIND, express or implied. See the License for the specific language governing permissions
+# and limitations under the License.
+
+"""awslabs EKS MCP Server implementation.
+
+This module implements the EKS MCP Server, which provides tools for managing Amazon EKS clusters
+and Kubernetes resources through the Model Context Protocol (MCP).
+
+Environment Variables:
+    AWS_REGION: AWS region to use for AWS API calls
+    AWS_PROFILE: AWS profile to use for credentials
+    FASTMCP_LOG_LEVEL: Log level (default: WARNING)
+"""
+
+import argparse
+from awslabs.eks_mcp_server.cloudwatch_handler import CloudWatchHandler
+from awslabs.eks_mcp_server.eks_kb_handler import EKSKnowledgeBaseHandler
+from awslabs.eks_mcp_server.eks_stack_handler import EksStackHandler
+from awslabs.eks_mcp_server.iam_handler import IAMHandler
+from awslabs.eks_mcp_server.k8s_handler import K8sHandler
+from loguru import logger
+from mcp.server.fastmcp import FastMCP
+
+
+# Define server instructions and dependencies
+SERVER_INSTRUCTIONS = """
+# Amazon EKS MCP Server
+
+This MCP server provides tools for managing Amazon EKS clusters and is the preferred mechanism for creating new EKS clusters.
+
+## Usage Notes
+
+- By default, the server runs in read-only mode. Use the `--allow-write` flag to enable write operations.
+- Access to sensitive data (logs, events, Kubernetes Secrets) requires the `--allow-sensitive-data-access` flag.
+- For safety reasons, CloudFormation stacks can only be modified by the tool that created them.
+- When creating or updating resources, always check for existing resources first to avoid conflicts.
+- Use the `list_api_versions` tool to find the correct apiVersion for Kubernetes resources.
+
+## Common Workflows
+
+### Creating and Deploying an Application
+1. Generate a CloudFormation template: `manage_eks_stacks(operation='generate', template_file='/path/to/template.yaml', cluster_name='my-cluster')`
+2. Deploy the CloudFormation stack: `manage_eks_stacks(operation='deploy', template_file='/path/to/template.yaml', cluster_name='my-cluster')`
+3. Generate an application manifest: `generate_app_manifest(app_name='my-app', image_uri='123456789012.dkr.ecr.us-east-1.amazonaws.com/my-repo:latest')`
+4. Apply the manifest: `apply_yaml(yaml_path='/path/to/manifest.yaml', cluster_name='my-cluster', namespace='default')`
+5. Monitor the application: `get_pod_logs(cluster_name='my-cluster', namespace='default', pod_name='my-app-pod')`
+
+### Troubleshooting Application Issues
+1. Check pod status: `list_k8s_resources(cluster_name='my-cluster', kind='Pod', api_version='v1', namespace='default', field_selector='metadata.name=my-pod')`
+2. Get pod events: `get_k8s_events(cluster_name='my-cluster', kind='Pod', name='my-pod', namespace='default')`
+3. Check pod logs: `get_pod_logs(cluster_name='my-cluster', namespace='default', pod_name='my-pod')`
+4. Monitor metrics: `get_cloudwatch_metrics(resource_type='pod', resource_name='my-pod', cluster_name='my-cluster', metric_name='cpu_usage_total', namespace='ContainerInsights')`
+5. Search troubleshooting guide: `search_eks_troubleshoot_guide(query='pod pending')`
+
+## Best Practices
+
+- Use descriptive names for resources to make them easier to identify and manage.
+- Apply proper labels and annotations to Kubernetes resources for better organization.
+- Use namespaces to isolate resources and avoid naming conflicts.
+- Monitor resource usage with CloudWatch metrics to identify performance issues.
+- Check logs and events when troubleshooting issues with Kubernetes resources.
+- Follow the principle of least privilege when creating IAM policies.
+- Use the search_eks_troubleshoot_guide tool when encountering common EKS issues.
+- Always verify API versions with list_api_versions before creating resources.
+"""
+
+SERVER_DEPENDENCIES = [
+    'pydantic',
+    'loguru',
+    'boto3',
+    'kubernetes',
+    'requests',
+    'pyyaml',
+    'cachetools',
+    'requests_auth_aws_sigv4',
+]
+
+# Global reference to the MCP server instance for testing purposes
+mcp = None
+
+
+def create_server():
+    """Create and configure the MCP server instance."""
+    return FastMCP(
+        'awslabs.eks-mcp-server',
+        instructions=SERVER_INSTRUCTIONS,
+        dependencies=SERVER_DEPENDENCIES,
+    )
+
+
+def main():
+    """Run the MCP server with CLI argument support."""
+    global mcp
+
+    parser = argparse.ArgumentParser(
+        description='An AWS Labs Model Context Protocol (MCP) server for EKS'
+    )
+    parser.add_argument(
+        '--allow-write',
+        action=argparse.BooleanOptionalAction,
+        default=False,
+        help='Enable write access mode (allow mutating operations)',
+    )
+    parser.add_argument(
+        '--allow-sensitive-data-access',
+        action=argparse.BooleanOptionalAction,
+        default=False,
+        help='Enable sensitive data access (required for reading logs, events, and Kubernetes Secrets)',
+    )
+
+    args = parser.parse_args()
+
+    allow_write = args.allow_write
+    allow_sensitive_data_access = args.allow_sensitive_data_access
+
+    # Log startup mode
+    mode_info = []
+    if not allow_write:
+        mode_info.append('read-only mode')
+    if not allow_sensitive_data_access:
+        mode_info.append('restricted sensitive data access mode')
+
+    mode_str = ' in ' + ', '.join(mode_info) if mode_info else ''
+    logger.info(f'Starting EKS MCP Server{mode_str}')
+
+    # Create the MCP server instance
+    mcp = create_server()
+
+    # Initialize handlers - all tools are always registered, access control is handled within tools
+    CloudWatchHandler(mcp, allow_sensitive_data_access)
+    EKSKnowledgeBaseHandler(mcp)
+    EksStackHandler(mcp, allow_write)
+    K8sHandler(mcp, allow_write, allow_sensitive_data_access)
+    IAMHandler(mcp, allow_write)
+
+    # Run server
+    mcp.run()
+
+    return mcp
+
+
+if __name__ == '__main__':
+    main()