DEVELOPMENT.md

Development Guide for ECS MCP Server

This guide provides instructions for setting up your development environment, running tests, and contributing to the ECS MCP Server project. All development should comply with the guidelines in the parent repository's DEVELOPER_GUIDE.md.

Setting Up Development Environment

Prerequisites

• Python 3.10+ (recommended installation using uv python install 3.10)
• uv
• Git
• AWS CLI with appropriate credentials configured

Installation

Clone from GitHub

# Clone the repository
git clone https://github.com/awslabs/mcp.git
cd mcp

Using Virtual Environment

# Create and activate a virtual environment using uv
cd src/ecs-mcp-server
uv venv
source .venv/bin/activate  # On Unix/macOS
.venv\Scripts\activate     # On Windows

# Install development dependencies
uv pip install -e ".[dev]"

Configure AWS Credentials

Ensure you have AWS credentials configured with appropriate permissions:

aws configure
AWS Access Key ID [None]: your-access-key
AWS Secret Access Key [None]: your-secret-key
Default region name [None]: us-east-1
Default output format [None]: json

Alternative Installation Method

You can also run the MCP server directly from a local clone of the GitHub repository:

# Clone the repository
git clone https://github.com/awslabs/mcp.git

# Run the server directly using uv
uv --directory /path/to/ecs-mcp-server/src/ecs-mcp-server/awslabs/ecs_mcp_server run main.py

Running the Server Locally

To run the server during development:

cd src/ecs-mcp-server
python -m awslabs.ecs_mcp_server.main

Alternatively, you can use uv to run the server:

uv --directory /path/to/ecs-mcp-server/src/ecs-mcp-server/awslabs/ecs_mcp_server run main.py

Configuration

Add the ECS MCP Server to your MCP client configuration:

{
  "mcpServers": {
    "awslabs.ecs-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/ecs-mcp-server/src/ecs-mcp-server/awslabs/ecs_mcp_server",
        "run",
        "main.py"
      ],
      "env": {
        "AWS_PROFILE": "your-aws-profile",
        "AWS_REGION": "your-aws-region",
        "FASTMCP_LOG_LEVEL": "DEBUG",
        "FASTMCP_LOG_FILE": "/path/to/logs/ecs-mcp-server.log"
      }
    }
  }
}

Accessing Server Logs

The ECS MCP Server supports both console logging and file logging. During development, you can:

1. View console logs: By default, logs are printed to the console with level determined by FASTMCP_LOG_LEVEL
2. Enable file logging: Add the FASTMCP_LOG_FILE environment variable to write logs to a file
3. View log files: Access the log file at the specified path for debugging server issues
4. Analyze crash logs: In case of server crashes, the log file will contain details to help diagnose the problem

To adjust log verbosity, set FASTMCP_LOG_LEVEL to one of: DEBUG, INFO, WARNING, ERROR, or CRITICAL.

Testing

Unit Tests

To run all unit tests:

cd src/ecs-mcp-server
python -m pytest tests/unit

To run a specific test file:

python -m pytest tests/unit/test_main.py

To run a specific test case with verbose output:

python -m pytest tests/unit/test_main.py::TestMain::test_server_tools -v

Integration/LLM Tests

Integration tests are available in the tests/llm_testing directory and are run using the run_tests.sh script:

cd src/ecs-mcp-server/tests/llm_testing
./run_tests.sh

The script will:

1. Give you many test scenarios to choose from
2. Set up necessary resources for the particular test
3. Provide you with prompts to run in an LLM and the expected outputs
4. Clean up resources (with your confirmation)

Test Coverage

To generate a test coverage report:

# Generate coverage report
python -m pytest --cov=awslabs.ecs_mcp_server tests/

For a detailed HTML coverage report:

python -m pytest --cov=awslabs.ecs_mcp_server --cov-report=html tests/

This will create an htmlcov directory with an interactive HTML report that you can open in your browser.

Code Style and Linting

Use pre-commit in DEVELOPER_GUIDE.md

Development Workflow

1. Create a branch: Create a new branch for your feature or fix
2. Make changes: Implement your changes following the code style guidelines
3. Run tests: Ensure all tests pass and add new tests as needed
4. Update documentation: Update README.md and other documentation as needed
5. Commit changes: Use clear commit messages (conventional commits recommended)
6. Submit a pull request: Open a pull request against the main branch

All changes should comply with the guidelines in the parent repository's DEVELOPER_GUIDE.md. This includes following the appropriate branching strategy, commit message format, and code review process.

Building and Publishing

To build the package:

cd src/ecs-mcp-server
python -m build