cloud-mcp-server: Instructions file for Claude Code

AWS MCP Server Development Guide

Build & Test Commands

• Install all deps: uv pip install --system -e ".[dev]"
• Run tests: make test or python -m pytest -v -m "not integration" --timeout=60
• Run single test: pytest tests/path/to/test_file.py::test_function_name -v
• Run linter: ruff check src/ tests/
• Format code: ruff format src/ tests/
• Run server: python -m aws_mcp_server
• Run with streamable-http: AWS_MCP_TRANSPORT=streamable-http python -m aws_mcp_server
• Run with sandbox disabled: AWS_MCP_SANDBOX=disabled python -m aws_mcp_server
• Update lockfile: uv pip compile --system pyproject.toml -o uv.lock
• Versioning: setuptools_scm from Git tags — tag as v1.x.y to release

Architecture

Server (server.py)

• Two tools: aws_cli_help (readOnly) and aws_cli_pipeline (destructive, openWorld)
• FastMCP instance with instructions, icons, SERVER_DESCRIPTION
• Tools use ToolAnnotations from mcp.types for tool metadata
• Tool functions return typed dataclasses (CommandResult, CommandHelpResult)
• All tool failures raise ToolError — FastMCP sets isError: true in protocol response (SEP-1303)

Sandbox (sandbox.py)

• Landlock LSM for filesystem isolation (Linux only)
• Seccomp-bpf for syscall filtering
• AWS env vars from SANDBOX_AWS_ENV_VARS are passed through to sandboxed processes
• AWS_MCP_SANDBOX=disabled to bypass for development; required to fail hard if unavailable

CLI Executor (cli_executor.py)

• All commands validated before execution (must start with aws)
• Pipe support: commands can include | jq, | grep, etc.
• Timeout handling with configurable default (300s)
• Returns {"status": "success"|"error", "output": "..."} dict

Transport & Lifecycle (__main__.py)

• Transports: stdio (default), streamable-http (recommended for web), sse (deprecated)
• On stdio: background thread monitors for client disconnect via select.poll or parent PID
• On sse/streamable-http: binds to 0.0.0.0 in Docker, 127.0.0.1 otherwise