cloud-mcp-server

# 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

### Resources (`resources.py`)
- `aws://profiles` — parses `~/.aws/credentials` and `~/.aws/config`
- `aws://regions` — hardcoded list + optional live fetch from EC2 API
- `aws://config` — summary of current AWS config state

### Prompts (`prompts.py`)
- 10+ prompt templates for common AWS tasks (Well-Architected, cost optimization, security)
- Consistent pattern: Pydantic `Field(description=...)` for all parameters

## Testing Patterns

- **Mocking AWS CLI:** `unittest.mock.patch` on `asyncio.create_subprocess_exec`
- **Sandbox tests:** separate unit (mocked) and integration (requires Linux + Landlock kernel)
- **Fixtures:** shared fixtures in `conftest.py` for mock subprocess results
- **Integration tests:** need actual AWS CLI + credentials — skip in CI with `-m "not integration"`
- **Coverage target:** >80% on `src/aws_mcp_server` — run with `--cov=aws_mcp_server`
- **Timeout:** always run with `--timeout=60` to avoid CI hangs on sandbox tests

## MCP Development Guidelines

- **Tool annotations:** always set `ToolAnnotations` on new tools (`readOnlyHint`, `destructiveHint`, `openWorldHint`)
- **Error handling:** raise `ToolError` for all tool failures — never return error status text from tool functions (SEP-1303)
- **FastMCP patterns:** `@mcp.tool()`, `@mcp.resource()`, `@mcp.prompt()` decorators
- **Context:** accept `ctx: Context | None = None` in tool functions for progress reporting via `ctx.info()`/`ctx.warning()`
- **Field descriptions:** use `pydantic.Field(description=...)` for all tool parameters — these become tool schema
- **Icons:** server-level icon set via `icons=[Icon(src=..., mimeType=...)]` in `FastMCP()`
- **Description:** server description via `SERVER_DESCRIPTION` prepended to `instructions`

## Security Notes

- **NEVER** log or store AWS credentials (access keys, session tokens, profile names with secrets)
- **NEVER** disable sandbox in production
- AWS env vars (`AWS_ACCESS_KEY_ID`, etc.) are in `SANDBOX_AWS_ENV_VARS` — update if new ones added
- Command validation must reject commands that don't start with `aws` or pipe to non-allowlisted executables
- `AWS_MCP_SANDBOX=disabled` is for development only — never in Dockerfile or production config