diff --git a/src/ecs-mcp-server/README.md b/src/ecs-mcp-server/README.md index c0911a2b73..9f10e0cdd8 100644 --- a/src/ecs-mcp-server/README.md +++ b/src/ecs-mcp-server/README.md @@ -24,6 +24,19 @@ Customers can list and view their ECS resources (clusters, services, tasks, task ## Installation +### Prerequisites + +Before installing the ECS MCP Server, ensure you have the following prerequisites installed: + +1. **Docker or Finch**: Required for containerization and local testing + - [Docker](https://docs.docker.com/get-docker/) for container management + - [Finch](https://github.com/runfinch/finch) as a Docker alternative + +2. **UV**: Required for package management and running MCP servers + - Install `uv` from [Astral](https://docs.astral.sh/uv/getting-started/installation/) + +### Installation Steps + ```bash # Install using uv uv pip install awslabs.ecs-mcp-server @@ -42,6 +55,8 @@ git clone https://github.com/awslabs/mcp.git uv --directory /path/to/ecs-mcp-server/src/ecs-mcp-server/awslabs/ecs_mcp_server run main.py ``` +To setup your preferred MCP client (ie. Amazon Q Developer CLI, Cline, Cursor, VS Code, etc.) with the ECS MCP Server, proceed to the [Configuration](#configuration) section. + ## Usage Environments The ECS MCP Server is currently in development and is designed for the following environments: diff --git a/src/ecs-mcp-server/awslabs/ecs_mcp_server/main.py b/src/ecs-mcp-server/awslabs/ecs_mcp_server/main.py index 3c587d0116..6c4e96b033 100755 --- a/src/ecs-mcp-server/awslabs/ecs_mcp_server/main.py +++ b/src/ecs-mcp-server/awslabs/ecs_mcp_server/main.py @@ -71,10 +71,6 @@ # Create the MCP server mcp = FastMCP( name="AWS ECS MCP Server", - description=( - "A server for automating containerization and deployment of web applications to AWS ECS" - ), - version="0.1.0", instructions="""Use this server to containerize and deploy web applications to AWS ECS. WORKFLOW: diff --git a/src/ecs-mcp-server/awslabs/ecs_mcp_server/modules/troubleshooting.py b/src/ecs-mcp-server/awslabs/ecs_mcp_server/modules/troubleshooting.py index cc4071e116..cc563d474f 100644 --- a/src/ecs-mcp-server/awslabs/ecs_mcp_server/modules/troubleshooting.py +++ b/src/ecs-mcp-server/awslabs/ecs_mcp_server/modules/troubleshooting.py @@ -22,7 +22,6 @@ from mcp.server.fastmcp import FastMCP from awslabs.ecs_mcp_server.api.ecs_troubleshooting import ( - TROUBLESHOOTING_DOCS, TroubleshootingAction, ecs_troubleshooting_tool, ) @@ -64,13 +63,128 @@ def register_module(mcp: FastMCP) -> None: @mcp.tool( name="ecs_troubleshooting_tool", annotations=None, - description=TROUBLESHOOTING_DOCS, # Dynamically generated documentation string ) async def mcp_ecs_troubleshooting_tool( app_name: Optional[str] = None, action: TroubleshootingAction = "get_ecs_troubleshooting_guidance", parameters: Optional[Dict[str, Any]] = None, ) -> Dict[str, Any]: + """ + ECS troubleshooting tool with multiple diagnostic actions. + + This tool provides access to all ECS troubleshooting operations through a single interface. + Use the 'action' parameter to specify which troubleshooting operation to perform. + + ## Available Actions and Parameters: + + ### 1. get_ecs_troubleshooting_guidance + Initial assessment and data collection + - Required: app_name + - Optional: symptoms_description (Description of symptoms experienced by the user) + - Example: action="get_ecs_troubleshooting_guidance", + parameters={"symptoms_description": "ALB returning 503 errors"} + + ### 2. fetch_cloudformation_status + Infrastructure-level diagnostics for CloudFormation stacks + - Required: stack_id + - Example: action="fetch_cloudformation_status", parameters={"stack_id": "my-app-stack"} + + ### 3. fetch_service_events + Service-level diagnostics for ECS services + - Required: app_name, cluster_name, service_name + - Optional: time_window (Time window in seconds to look back for events (default: 3600)), + start_time (Explicit start time for the analysis window (UTC, takes + precedence over time_window if provided)), + end_time (Explicit end time for the analysis window (UTC, defaults to + current time if not provided)) + - Example: action="fetch_service_events", + parameters={"cluster_name": "my-cluster", + "service_name": "my-service", + "time_window": 7200} + + ### 4. fetch_task_failures + Task-level diagnostics for ECS task failures + - Required: app_name, cluster_name + - Optional: time_window (Time window in seconds to look back for failures (default: 3600)), + start_time (Explicit start time for the analysis window (UTC, takes + precedence over time_window if provided)), + end_time (Explicit end time for the analysis window (UTC, defaults to + current time if not provided)) + - Example: action="fetch_task_failures", + parameters={"cluster_name": "my-cluster", + "time_window": 3600} + + ### 5. fetch_task_logs + Application-level diagnostics through CloudWatch logs + - Required: app_name, cluster_name + - Optional: task_id (Specific task ID to retrieve logs for), + time_window (Time window in seconds to look back for logs (default: 3600)), + filter_pattern (CloudWatch logs filter pattern), + start_time (Explicit start time for the analysis window (UTC, takes + precedence over time_window if provided)), + end_time (Explicit end time for the analysis window (UTC, defaults to + current time if not provided)) + - Example: action="fetch_task_logs", + parameters={"cluster_name": "my-cluster", + "filter_pattern": "ERROR", + "time_window": 1800} + + ### 6. detect_image_pull_failures + Specialized tool for detecting container image pull failures + - Required: app_name + - Example: action="detect_image_pull_failures", parameters={} + + ### 7. fetch_network_configuration + Network-level diagnostics for ECS deployments + - Required: app_name + - Optional: vpc_id (Specific VPC ID to analyze), cluster_name (Specific ECS cluster name) + - Example: action="fetch_network_configuration", + parameters={"vpc_id": "vpc-12345678", "cluster_name": "my-cluster"} + + ## Quick Usage Examples: + ``` + # Initial assessment and data collection + action: "get_ecs_troubleshooting_guidance" + parameters: {"symptoms_description": "ALB returning 503 errors"} + + # Infrastructure-level diagnostics for CloudFormation stacks + action: "fetch_cloudformation_status" + parameters: {"stack_id": "my-app-stack"} + + # Service-level diagnostics for ECS services + action: "fetch_service_events" + parameters: {"cluster_name": "my-cluster", + "service_name": "my-service", + "time_window": 7200} + + # Task-level diagnostics for ECS task failures + action: "fetch_task_failures" + parameters: {"cluster_name": "my-cluster", + "time_window": 3600} + + # Application-level diagnostics through CloudWatch logs + action: "fetch_task_logs" + parameters: {"cluster_name": "my-cluster", + "filter_pattern": "ERROR", + "time_window": 1800} + + # Specialized tool for detecting container image pull failures + action: "detect_image_pull_failures" + parameters: {} + + # Network-level diagnostics for ECS deployments + action: "fetch_network_configuration" + parameters: {"vpc_id": "vpc-12345678", "cluster_name": "my-cluster"} + ``` + + Parameters: + app_name: Application/stack name (required for most actions) + action: The troubleshooting action to perform (see available actions above) + parameters: Action-specific parameters (see parameter specifications above) + + Returns: + Results from the selected troubleshooting action + """ # Initialize default parameters if None if parameters is None: parameters = {} diff --git a/src/ecs-mcp-server/tests/unit/test_main.py b/src/ecs-mcp-server/tests/unit/test_main.py index 0ffaa82209..8f6594a715 100644 --- a/src/ecs-mcp-server/tests/unit/test_main.py +++ b/src/ecs-mcp-server/tests/unit/test_main.py @@ -2,7 +2,7 @@ Unit tests for main server module. This file contains tests for the ECS MCP Server main module, including: -- Basic properties (name, version, description, instructions) +- Basic properties (name, instructions) - Tools registration - Prompt patterns registration - Server startup and shutdown @@ -19,22 +19,19 @@ class MockFastMCP: """Mock implementation of FastMCP for testing.""" - def __init__(self, name, description=None, version=None, instructions=None): + def __init__(self, name, instructions=None): self.name = name - self.description = description or "" - self.version = version self.instructions = instructions self.tools = [] self.prompt_patterns = [] - def tool(self, name=None, description=None, annotations=None): + def tool(self, name=None, annotations=None): def decorator(func): self.tools.append( { "name": name or func.__name__, "function": func, "annotations": annotations, - "description": description, } ) return func @@ -76,20 +73,12 @@ def test_server_basic_properties(self): This test focuses only on the basic properties of the server: - Name - - Version - - Description - Instructions If this test fails, it indicates an issue with the basic server configuration. """ # Verify the server has the correct name and version self.assertEqual(mcp.name, "AWS ECS MCP Server") - self.assertEqual(mcp.version, "0.1.0") - - # Verify the description contains expected keywords - self.assertIn("containerization", mcp.description.lower()) - self.assertIn("deployment", mcp.description.lower()) - self.assertIn("aws ecs", mcp.description.lower()) # Verify instructions are provided self.assertIsNotNone(mcp.instructions) diff --git a/src/ecs-mcp-server/tests/unit/test_resource_management_tool.py b/src/ecs-mcp-server/tests/unit/test_resource_management_tool.py index 87ddad7e2c..b2250d508e 100644 --- a/src/ecs-mcp-server/tests/unit/test_resource_management_tool.py +++ b/src/ecs-mcp-server/tests/unit/test_resource_management_tool.py @@ -12,10 +12,8 @@ class MockFastMCP: """Mock implementation of FastMCP for testing.""" - def __init__(self, name, description=None, version=None, instructions=None): + def __init__(self, name, instructions=None): self.name = name - self.description = description or "" - self.version = version self.instructions = instructions self.tools = [] self.prompt_patterns = []