Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 0 additions & 1 deletion .github/workflows/docker.yml
Original file line number Diff line number Diff line change
Expand Up @@ -64,7 +64,6 @@ jobs:
docker run -i --rm \
-v /var/run/docker.sock:/var/run/docker.sock \
--add-host host.docker.internal:host-gateway \
--add-host s3.host.docker.internal:host-gateway \
--add-host snowflake.localhost.localstack.cloud:host-gateway \
-e LOCALSTACK_AUTH_TOKEN \
-e LOCALSTACK_HOSTNAME=host.docker.internal \
Expand Down
29 changes: 5 additions & 24 deletions Dockerfile
Original file line number Diff line number Diff line change
Expand Up @@ -31,35 +31,17 @@ RUN set -eux; \
RUN python3 -m venv /opt/venv \
&& pip install --no-cache-dir --upgrade pip \
&& pip install --no-cache-dir --no-compile \
terraform-local \
aws-sam-cli \
aws-sam-cli-local \
snowflake-cli \
&& find /opt/venv/lib \
\( -type d \( -name __pycache__ -o -name tests -o -name test \) -o -type f \( -name '*.pyc' -o -name '*.pyo' \) \) \
-prune -exec rm -rf '{}' +

RUN npm install -g aws-cdk@2.1133.0 aws-cdk-local \
# lstk wraps terraform, cdk, and sam for the deployer tool. aws-cdk >= 2.1138 honors the
# CDK_S3_FORCE_PATH_STYLE that lstk sets, so S3 assets reach host.docker.internal path-style.
RUN npm install -g aws-cdk@2.1145.0 @localstack/lstk@1.4.2 \
&& npm cache clean --force

RUN node <<'NODE'
const fs = require("fs");
const path = require("path");
const { execSync } = require("child_process");
const globalRoot = execSync("npm root -g").toString().trim();
const file = path.join(globalRoot, "aws-cdk/lib/index.js");
const source = fs.readFileSync(file, "utf8");
const target = ` s3() {\n const client = new import_client_s33.S3Client(this.config);`;
const replacement = ` s3() {\n if (/^(1|true|yes)$/i.test(process.env.AWS_S3_FORCE_PATH_STYLE || "")) {\n this.config.forcePathStyle = true;\n }\n const client = new import_client_s33.S3Client(this.config);`;

if (!source.includes(replacement)) {
if (!source.includes(target)) {
throw new Error("Could not patch aws-cdk S3 forcePathStyle hook");
}
fs.writeFileSync(file, source.replace(target, replacement));
}
NODE

WORKDIR /app
RUN mkdir -p /tmp/dockerode-deps \
&& npm install --prefix /tmp/dockerode-deps --omit=dev --ignore-scripts --no-audit --no-fund dockerode@5.0.1 \
Expand All @@ -71,11 +53,10 @@ COPY --from=builder /app/dist ./dist
COPY --from=builder /app/package.json ./package.json

RUN set -eux; \
lstk --version; \
terraform version; \
tflocal --version; \
sam --version; \
command -v samlocal; \
cdklocal --version; \
cdk --version; \
snow --version; \
node dist/cli.js version; \
node -e "require('dockerode'); console.log('dockerode ok')"
Expand Down
8 changes: 3 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,7 @@ This server provides your AI with dedicated tools for managing your LocalStack e
| Tool Name | Description | Key Features |
| :-------------------------------------------------------------------------------- | :------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| [`localstack-management`](./src/tools/localstack-management.ts) | Manages LocalStack runtime operations for AWS, Snowflake and Azure stacks | - Execute start, stop, restart, and status checks<br/>- Integrate LocalStack authentication tokens<br/>- Inject custom environment variables<br/>- Verify real-time status and perform health monitoring |
| [`localstack-deployer`](./src/tools/localstack-deployer.ts) | Handles infrastructure deployment to LocalStack for AWS environments | - Automatically run CDK, Terraform, and SAM tooling to deploy infrastructure locally<br/>- Enable parameterized deployments with variable support<br/>- Process and present deployment results<br/>- Requires you to have [`cdklocal`](https://github.com/localstack/aws-cdk-local), [`tflocal`](https://github.com/localstack/terraform-local), or [`samlocal`](https://github.com/localstack/aws-sam-cli-local) installed in your system path |
| [`localstack-deployer`](./src/tools/localstack-deployer.ts) | Handles infrastructure deployment to LocalStack for AWS environments | - Automatically run CDK, Terraform, and SAM tooling to deploy infrastructure locally<br/>- Enable parameterized deployments with variable support<br/>- Process and present deployment results<br/>- Runs `lstk terraform`, `lstk cdk`, or `lstk sam`, so it requires [`lstk`](https://docs.localstack.cloud/aws/developer-tools/running-localstack/lstk/) plus `terraform`, `cdk`, or `sam` in your system path |
| [`localstack-logs-analysis`](./src/tools/localstack-logs-analysis.ts) | Analyzes LocalStack for AWS logs for troubleshooting and insights | - Offer multiple analysis options including summaries, errors, requests, and raw data<br/>- Filter by specific services and operations<br/>- Generate API call metrics and failure breakdowns<br/>- Group errors intelligently and identify patterns |
| [`localstack-iam-policy-analyzer`](./src/tools/localstack-iam-policy-analyzer.ts) | Handles IAM policy management and violation remediation | - Set IAM enforcement levels including `enforced`, `soft`, and `disabled` modes<br/>- Search logs for permission-related violations<br/>- Generate IAM policies automatically from detected access failures<br/>- Requires a valid LocalStack Auth Token |
| [`localstack-chaos-injector`](./src/tools/localstack-chaos-injector.ts) | Injects and manages chaos experiment faults for system resilience testing | - Inject, add, remove, and clear service fault rules<br/>- Configure network latency effects<br/>- Comprehensive fault targeting by service, region, and operation<br/>- Built-in workflow guidance for chaos experiments<br/>- Requires a valid LocalStack Auth Token |
Expand Down Expand Up @@ -124,7 +124,7 @@ Run `npx -y @localstack/localstack-mcp-server init --help` for all options.
### Prerequisites

- Docker installed and running. The MCP server manages the LocalStack container directly through the Docker API.
- [`cdklocal`](https://github.com/localstack/aws-cdk-local), [`tflocal`](https://github.com/localstack/terraform-local), or [`samlocal`](https://github.com/localstack/aws-sam-cli-local) installed in your system path if you want to deploy CDK, Terraform, or SAM projects
- [`lstk`](https://docs.localstack.cloud/aws/developer-tools/running-localstack/lstk/) (`npm install -g @localstack/lstk`) plus the Terraform, AWS CDK (2.177.0 or newer), or AWS SAM (1.95.0 or newer) CLI in your system path if you want to deploy Terraform, CDK, or SAM projects
- Snowflake CLI (`snow`) installed in your system path if you want to use the Snowflake tool
- Azure CLI (`az`) installed in your system path if you want to use the Azure tool (see [docs/AZURE.md](./docs/AZURE.md))
- A [valid LocalStack Auth Token](https://docs.localstack.cloud/aws/getting-started/auth-token/) configured as `LOCALSTACK_AUTH_TOKEN` (**required for all MCP tools**)
Expand Down Expand Up @@ -170,7 +170,7 @@ If you installed from source, change `command` and `args` to point to your local

### Run with Docker

The `localstack/localstack-mcp-server` Docker image bundles Terraform/`tflocal`, CDK/`cdklocal`, SAM/`samlocal`, and the Snowflake CLI. The only required host dependency is Docker. The container uses the mounted Docker socket to run LocalStack as a sibling container on the host; state lives in a named Docker volume (`localstack-mcp`) unless `LOCALSTACK_VOLUME_DIR` points at a host directory.
The `localstack/localstack-mcp-server` Docker image bundles `lstk` with Terraform, CDK, and SAM, and the Snowflake CLI. The only required host dependency is Docker. The container uses the mounted Docker socket to run LocalStack as a sibling container on the host; state lives in a named Docker volume (`localstack-mcp`) unless `LOCALSTACK_VOLUME_DIR` points at a host directory.

If you use the deployer tool with local Terraform, CDK, or SAM projects, bind-mount those project paths into the MCP container and pass the in-container path to the tool. The simplest convention is to mount projects at the same absolute path they use on the host.

Expand All @@ -188,8 +188,6 @@ If you use the deployer tool with local Terraform, CDK, or SAM projects, bind-mo
"--add-host",
"host.docker.internal:host-gateway",
"--add-host",
"s3.host.docker.internal:host-gateway",
"--add-host",
"snowflake.localhost.localstack.cloud:host-gateway",
"-e",
"LOCALSTACK_AUTH_TOKEN",
Expand Down
32 changes: 14 additions & 18 deletions docs/DOCKER.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Running the LocalStack MCP Server in Docker

The published image bundles everything the server shells out to — Terraform +
`tflocal`, AWS CDK + `cdklocal`, AWS SAM + `samlocal`, and the Snowflake `snow`
The published image bundles everything the server shells out to — `lstk` with
Terraform, AWS CDK, and AWS SAM, and the Snowflake `snow`
CLI — so the **only dependency on your machine is Docker itself**. LocalStack
lifecycle, logs, and `awslocal` run through the Docker Engine API and LocalStack's
REST APIs.
Expand Down Expand Up @@ -47,21 +47,19 @@ interpreted by the **host** daemon).
docker run -i --rm \
-v /var/run/docker.sock:/var/run/docker.sock \
--add-host host.docker.internal:host-gateway \
--add-host s3.host.docker.internal:host-gateway \
--add-host snowflake.localhost.localstack.cloud:host-gateway \
-e LOCALSTACK_AUTH_TOKEN="<YOUR_TOKEN>" \
-e LOCALSTACK_HOSTNAME=host.docker.internal \
localstack/localstack-mcp-server:latest
```

| Flag | Why it's needed |
| -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `-v /var/run/docker.sock:/var/run/docker.sock` | Lets the server create/stop/restart the sibling LocalStack container, read its logs, and run `awslocal` inside it. |
| `--add-host host.docker.internal:host-gateway` | Resolves `host.docker.internal` on Linux. Harmless on Docker Desktop (Mac/Windows), where it already resolves. |
| `--add-host s3.host.docker.internal:host-gateway` | Lets CDK's virtual-hosted S3 endpoint resolve when `cdklocal` uses `AWS_ENDPOINT_URL_S3=http://s3.host.docker.internal:4566`. |
| `--add-host snowflake.localhost.localstack.cloud:host-gateway` | Lets the Snowflake CLI reach the sibling Snowflake emulator through the hostname the emulator expects for routing. |
| `-e LOCALSTACK_AUTH_TOKEN` | Required by **every** tool in this server. |
| `-e LOCALSTACK_HOSTNAME=host.docker.internal` | Tells the server + IaC CLIs where the sibling LocalStack lives. |
| Flag | Why it's needed |
| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| `-v /var/run/docker.sock:/var/run/docker.sock` | Lets the server create/stop/restart the sibling LocalStack container, read its logs, and run `awslocal` inside it. |
| `--add-host host.docker.internal:host-gateway` | Resolves `host.docker.internal` on Linux. Harmless on Docker Desktop (Mac/Windows), where it already resolves. |
| `--add-host snowflake.localhost.localstack.cloud:host-gateway` | Lets the Snowflake CLI reach the sibling Snowflake emulator through the hostname the emulator expects for routing. |
| `-e LOCALSTACK_AUTH_TOKEN` | Required by **every** tool in this server. |
| `-e LOCALSTACK_HOSTNAME=host.docker.internal` | Tells the server + IaC CLIs where the sibling LocalStack lives. |

## MCP client configuration

Expand All @@ -82,8 +80,6 @@ expand `$HOME`/`$PWD` — use absolute paths.
"--add-host",
"host.docker.internal:host-gateway",
"--add-host",
"s3.host.docker.internal:host-gateway",
"--add-host",
"snowflake.localhost.localstack.cloud:host-gateway",
"-e",
"LOCALSTACK_AUTH_TOKEN",
Expand Down Expand Up @@ -111,10 +107,11 @@ The simplest convention is to mount it at the same absolute path:

Then tell the tool `directory: /Users/you/projects/my-infra`.

Terraform, SAM, and CDK receive the LocalStack endpoint automatically when
`LOCALSTACK_HOSTNAME=host.docker.internal` is set. CDK asset publishing is forced
to path-style S3 inside the Docker image, so the single `s3.host.docker.internal`
alias covers bootstrap asset uploads.
The deployer runs Terraform, SAM, and CDK through `lstk terraform|sam|cdk`, which
receives the LocalStack endpoint automatically when
`LOCALSTACK_HOSTNAME=host.docker.internal` is set. `lstk` forces CDK asset
publishing to path-style S3, so no extra S3 host alias is needed. Existing configs
that still pass `--add-host s3.host.docker.internal:host-gateway` keep working.

## Known limitations

Expand Down Expand Up @@ -153,7 +150,6 @@ node tests/docker/validate-image.mjs -- \
docker run -i --rm \
-v /var/run/docker.sock:/var/run/docker.sock \
--add-host host.docker.internal:host-gateway \
--add-host s3.host.docker.internal:host-gateway \
--add-host snowflake.localhost.localstack.cloud:host-gateway \
-e LOCALSTACK_AUTH_TOKEN \
-e LOCALSTACK_HOSTNAME=host.docker.internal \
Expand Down
26 changes: 19 additions & 7 deletions src/core/localstack-env.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -20,22 +20,34 @@ describe("buildIacCliEnv", () => {
expect(env.AWS_REGION).toBe("us-east-1");
expect(env.CDK_DEFAULT_ACCOUNT).toBe("000000000000");
expect(env.CDK_DEFAULT_REGION).toBe("us-east-1");
expect(env.AWS_ENVAR_ALLOWLIST).toContain("AWS_ACCESS_KEY_ID");
expect(env.AWS_ENDPOINT_URL).toBeUndefined();
expect(env.CI).toBe("true");
});

it("adds Docker endpoint overrides when LocalStack runs through the host gateway", () => {
it("points lstk at localhost.localstack.cloud for a local LocalStack", () => {
const env = buildIacCliEnv();

expect(env.AWS_ENDPOINT_URL).toBe("http://localhost.localstack.cloud:4566");
expect(env.AWS_ENDPOINT_URL_S3).toBeUndefined();
});

it("points lstk at the host gateway when LocalStack runs outside the container", () => {
process.env.LOCALSTACK_HOSTNAME = "host.docker.internal";

const env = buildIacCliEnv();

expect(env.AWS_ACCESS_KEY_ID).toBe("test");
expect(env.AWS_SECRET_ACCESS_KEY).toBe("test");
expect(env.AWS_ENDPOINT_URL).toBe("http://host.docker.internal:4566");
expect(env.AWS_ENDPOINT_URL_S3).toBe("http://s3.host.docker.internal:4566");
expect(env.S3_ENDPOINT).toBe("http://host.docker.internal:4566");
expect(env.AWS_S3_FORCE_PATH_STYLE).toBe("1");
expect(env.LOCALSTACK_HOSTNAME).toBe("host.docker.internal");
// lstk derives the S3 endpoint and path-style addressing itself.
expect(env.AWS_ENDPOINT_URL_S3).toBeUndefined();
});

it("preserves an explicit endpoint", () => {
process.env.LOCALSTACK_HOSTNAME = "host.docker.internal";

const env = buildIacCliEnv({ AWS_ENDPOINT_URL: "https://example.localstack.cloud" });

expect(env.AWS_ENDPOINT_URL).toBe("https://example.localstack.cloud");
});

it("preserves explicit credentials and regions", () => {
Expand Down
Loading
Loading