Skip to content
Open
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
2 changes: 1 addition & 1 deletion .github/workflows/docker.yml
Original file line number Diff line number Diff line change
Expand Up @@ -46,7 +46,7 @@ jobs:

- name: Smoke test MCP startup
env:
HARNESS_SKIP: prompt,docs,status,start,aws,logs,state,cloudpods,appinspector,chaos,iam,replicator,ephemeral,deploy,deploy-cdk,extensions,restart,stop,snowflake
HARNESS_SKIP: prompt,docs,status,start,aws,logs,state,cloudpods,appinspector,chaos,iam,replicator,ephemeral,deploy,deploy-cdk,extensions,restart,stop,snowflake,azure
run: |
node tests/docker/validate-image.mjs -- \
docker run -i --rm \
Expand Down
8 changes: 7 additions & 1 deletion Dockerfile
Original file line number Diff line number Diff line change
Expand Up @@ -23,8 +23,13 @@ RUN set -eux; \
chmod a+r /usr/share/keyrings/hashicorp-archive-keyring.gpg; \
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] https://apt.releases.hashicorp.com bookworm main" \
> /etc/apt/sources.list.d/hashicorp.list; \
curl -fsSL https://packages.microsoft.com/keys/microsoft.asc \
| gpg --dearmor -o /usr/share/keyrings/microsoft.gpg; \
chmod a+r /usr/share/keyrings/microsoft.gpg; \
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/microsoft.gpg] https://packages.microsoft.com/repos/azure-cli/ bookworm main" \
> /etc/apt/sources.list.d/azure-cli.list; \
apt-get update; \
apt-get install -y --no-install-recommends terraform; \
apt-get install -y --no-install-recommends terraform azure-cli; \
apt-get clean; \
rm -rf /var/lib/apt/lists/*

Expand Down Expand Up @@ -57,6 +62,7 @@ RUN set -eux; \
terraform version; \
sam --version; \
cdk --version; \
az version; \
snow --version; \
node dist/cli.js version; \
node -e "require('dockerode'); console.log('dockerode ok')"
Expand Down
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
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 `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.
The `localstack/localstack-mcp-server` Docker image bundles `lstk` with Terraform, CDK, and SAM, the Azure CLI, 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 Down Expand Up @@ -210,7 +210,7 @@ See **[docs/DOCKER.md](./docs/DOCKER.md)** for the run command, MCP client confi
| Variable Name | Description | Default Value |
| -------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
| `LOCALSTACK_AUTH_TOKEN` (**required**) | The LocalStack Auth Token to use for the MCP server | None |
| `LOCALSTACK_HOSTNAME` | Host name of the LocalStack gateway the tools call; in Docker, `host.docker.internal`. The Azure tool always calls `azure.localhost.localstack.cloud` (127.0.0.1), so it needs a local gateway. | `localhost` |
| `LOCALSTACK_HOSTNAME` | Host name of the LocalStack gateway the tools call; in Docker, `host.docker.internal`. The Azure tool always calls `azure.localhost.localstack.cloud` (127.0.0.1); in Docker the server forwards that port to this host. | `localhost` |
| `LOCALSTACK_PORT` | Port of the LocalStack gateway the tools call. | `4566` |
| `MAIN_CONTAINER_NAME` | The explicit LocalStack container name to use for Docker-based tools. When unset, the server auto-detects standard LocalStack containers such as `localstack-main` and `localstack-aws`, then LocalStack Docker images. | Auto-detect |
| `LOCALSTACK_IMAGE_NAME` / `IMAGE_NAME` | Docker image the `start` action launches for the AWS stack. `LOCALSTACK_IMAGE_NAME` wins when both are set (beware: bare `IMAGE_NAME` is a common CI variable). | `localstack/localstack-pro:latest` |
Expand Down
2 changes: 1 addition & 1 deletion docs/AZURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,4 +8,4 @@
- Relative file paths in commands resolve against `LOCALSTACK_AZ_WORKDIR`, by default the directory the MCP client starts the server in.
- `rest` calls the emulator: give it a relative URL. An absolute URL must name a local host; a `management.azure.com` URL is turned into a relative one.
- Only `rest` URLs are checked: an endpoint given in a command, such as `--blob-endpoint` or a connection string, is used as it is.
- The Docker image does not include the Azure CLI yet: run the server with npx or from source to use the Azure tool.
- The Docker image includes the Azure CLI. Mount the files your commands use and set `LOCALSTACK_AZ_WORKDIR` to the mount (see [DOCKER.md](./DOCKER.md#azure-cli)). The image has no Azure CLI extensions or `bicep`, and its Azure CLI profile lasts only as long as the container.
25 changes: 19 additions & 6 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 — `lstk` with
Terraform, AWS CDK, and AWS SAM, and the Snowflake `snow`
Terraform, AWS CDK, and AWS SAM, the Azure CLI, 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 @@ -29,7 +29,9 @@ Because LocalStack is a sibling container, one thing must be configured at run t

- **Reachability** — set `LOCALSTACK_HOSTNAME=host.docker.internal` so the server
and the IaC CLIs target the sibling's published port instead of the container's
own `localhost`.
own `localhost`. The server also forwards the container's `127.0.0.1:4566`
(`LOCALSTACK_PORT`) to that host, because `*.localhost.localstack.cloud` names,
such as the Azure emulator's per-account storage hosts, resolve to `127.0.0.1`.

LocalStack state lives in a **named Docker volume** (`localstack-mcp`) by default,
so no host directory needs to be mounted or path-mirrored. To keep state in a host
Expand Down Expand Up @@ -113,6 +115,21 @@ receives the LocalStack endpoint automatically when
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.

## Azure CLI

The `localstack-azure-client` tool runs the bundled Azure CLI. As with IaC
projects, mount the files your commands use (templates, uploads) and point
`LOCALSTACK_AZ_WORKDIR` at the mount so relative paths resolve there:

```
-v "/Users/you/projects/my-app:/Users/you/projects/my-app"
-e LOCALSTACK_AZ_WORKDIR=/Users/you/projects/my-app
```

The tool's Azure CLI profile lives inside the container, so it is set up again
each time the container starts. The image has no Azure CLI extensions and no
`bicep`.

## Known limitations

- **Extra host aliases.** Include the aliases shown in the quick-start command.
Expand All @@ -122,10 +139,6 @@ that still pass `--add-host s3.host.docker.internal:host-gateway` keep working.
on the host even if your editor restarts the MCP container — reconnecting finds
your stack still up. State persists in the `localstack-mcp` named volume (or
`LOCALSTACK_VOLUME_DIR` if you set one).
- **No Azure CLI.** The image lists all 15 tools, but it does not include the Azure
CLI, so `localstack-azure-client` answers that `az` is not available. To use the
Azure tool, run the server with npx or from source. `localstack-management` can
still start and stop the Azure emulator (`service: azure`) from the image.

## Troubleshooting

Expand Down
2 changes: 2 additions & 0 deletions src/cli/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ import * as fs from "fs";
import * as path from "path";

import { exitWhenClientDisconnects } from "./lifecycle";
import { forwardLoopbackGateway } from "./loopback-forward";

function getVersion(): string {
try {
Expand Down Expand Up @@ -58,6 +59,7 @@ async function main(): Promise<void> {
);
}
exitWhenClientDisconnects();
forwardLoopbackGateway();
require("./stdio.js");
}
}
Expand Down
86 changes: 86 additions & 0 deletions src/cli/loopback-forward.test.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,86 @@
import * as net from "net";

import { loopbackForwardTarget, startLoopbackForwarder } from "./loopback-forward";

describe("loopbackForwardTarget", () => {
it("forwards to the host gateway inside a container", () => {
expect(loopbackForwardTarget({ LOCALSTACK_HOSTNAME: "host.docker.internal" }, true)).toEqual({
host: "host.docker.internal",
port: 4566,
});
});

it("uses LOCALSTACK_PORT", () => {
expect(
loopbackForwardTarget(
{ LOCALSTACK_HOSTNAME: "host.docker.internal", LOCALSTACK_PORT: "4567" },
true
)
).toEqual({ host: "host.docker.internal", port: 4567 });
});

it("does nothing outside a container", () => {
expect(loopbackForwardTarget({ LOCALSTACK_HOSTNAME: "host.docker.internal" }, false)).toBe(
undefined
);
});

it.each([undefined, "localhost", "127.0.0.1"])(
"does nothing when LocalStack is local (%s)",
(host) => {
expect(loopbackForwardTarget({ LOCALSTACK_HOSTNAME: host }, true)).toBe(undefined);
}
);

it("does nothing for an invalid port", () => {
expect(
loopbackForwardTarget(
{ LOCALSTACK_HOSTNAME: "host.docker.internal", LOCALSTACK_PORT: "nope" },
true
)
).toBe(undefined);
});
});

describe("startLoopbackForwarder", () => {
const listening = (server: net.Server) =>
new Promise<number>((resolve) =>
server.listening
? resolve((server.address() as net.AddressInfo).port)
: server.once("listening", () => resolve((server.address() as net.AddressInfo).port))
);

it("pipes loopback connections to the target and back", async () => {
const upstream = net.createServer((socket) => socket.pipe(socket));
upstream.listen(0, "127.0.0.1");
const upstreamPort = await listening(upstream);

const forwarder = startLoopbackForwarder({ host: "127.0.0.1", port: upstreamPort }, 0);
const forwarderPort = await listening(forwarder);

const reply = await new Promise<string>((resolve, reject) => {
const client = net.connect(forwarderPort, "127.0.0.1", () => client.write("ping"));
client.once("data", (data) => {
resolve(data.toString());
client.destroy();
});
client.once("error", reject);
});

expect(reply).toBe("ping");
forwarder.close();
upstream.close();
});

it("gives up quietly when the port is taken", async () => {
const taken = net.createServer();
taken.listen(0, "127.0.0.1");
const port = await listening(taken);

const forwarder = startLoopbackForwarder({ host: "127.0.0.1", port: 1 }, port);
await new Promise<void>((resolve) => forwarder.once("close", () => resolve()));

expect(forwarder.listening).toBe(false);
taken.close();
});
});
55 changes: 55 additions & 0 deletions src/cli/loopback-forward.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
/**
* In the Docker image LocalStack runs in a sibling container, but its
* *.localhost.localstack.cloud names resolve to 127.0.0.1 — this container.
* Names that `--add-host` cannot cover, such as the per-account Azure storage
* hosts (<account>.blob.core.azure.localhost.localstack.cloud), would reach
* nothing. Forwarding the container's loopback gateway port to
* LOCALSTACK_HOSTNAME sends every such name to LocalStack; TLS passes through
* untouched, so certificates still match the requested host.
*/
import * as fs from "fs";
import * as net from "net";

export interface ForwardTarget {
host: string;
port: number;
}

/** Where to forward, or undefined outside a container or when LocalStack is already local. */
export function loopbackForwardTarget(
env: NodeJS.ProcessEnv = process.env,
inContainer: boolean = fs.existsSync("/.dockerenv")
): ForwardTarget | undefined {
const host = env.LOCALSTACK_HOSTNAME?.trim();
if (!inContainer || !host || host === "localhost" || host === "127.0.0.1") return undefined;
const port = Number(env.LOCALSTACK_PORT?.trim() || 4566);
if (!Number.isInteger(port) || port < 1 || port > 65535) return undefined;
return { host, port };
}

export function startLoopbackForwarder(
target: ForwardTarget,
listenPort: number = target.port
): net.Server {
const server = net.createServer((client) => {
const upstream = net.connect(target.port, target.host);
const close = () => {
client.destroy();
upstream.destroy();
};
client.on("error", close).on("close", close);
upstream.on("error", close).on("close", close);
client.pipe(upstream).pipe(client);
});
// Best effort: a taken port (e.g. `--network host`) only means no forwarding.
server.on("error", () => server.close());
server.listen(listenPort, "127.0.0.1");
// The client's stdio decides when the process exits, not this listener.
server.unref();
return server;
}

export function forwardLoopbackGateway(): void {
const target = loopbackForwardTarget();
if (target) startLoopbackForwarder(target);
}
53 changes: 53 additions & 0 deletions tests/docker/validate-image.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@
* Env knobs:
* HARNESS_DEPLOY_DIR In-container path to the terraform sample (default /work/data/sample-terraform)
* HARNESS_CDK_DIR In-container path to the CDK sample (default /work/data/sample-cdk)
* HARNESS_AZURE_FILE In-container path to the file the Azure scenario uploads (default /work/data/sample-azure/hello.txt)
* HARNESS_TOKEN_REAL "1" if LOCALSTACK_AUTH_TOKEN is a real/valid token (affects Pro-tool expectations)
* HARNESS_SKIP Comma-separated scenario keys to skip (e.g. "deploy,extensions")
* HARNESS_NO_CLEANUP "1" to leave LocalStack running afterwards
Expand All @@ -47,6 +48,7 @@ const serverArgs = argv.slice(sep + 2);
const DEPLOY_DIR = process.env.HARNESS_DEPLOY_DIR || "/work/data/sample-terraform";
const CDK_DIR = process.env.HARNESS_CDK_DIR || "/work/data/sample-cdk";
const SQL_FILE = process.env.HARNESS_SQL_FILE || "/work/data/sample-sql/snowflake_test.sql";
const AZURE_FILE = process.env.HARNESS_AZURE_FILE || "/work/data/sample-azure/hello.txt";
const TOKEN_REAL = process.env.HARNESS_TOKEN_REAL === "1";
const SKIP = new Set(
(process.env.HARNESS_SKIP || "")
Expand Down Expand Up @@ -980,6 +982,57 @@ async function main() {
}
}
}

// 11. Azure stack — the bundled az CLI. The blob upload goes to a per-account
// *.localhost.localstack.cloud host, so it also validates the loopback forwarder.
if (!SKIP.has("azure")) {
const id = RUN_ID.replace(/[^a-z0-9]/g, "").slice(-12);
const group = `mcp-harness-${id}`;
const account = `mcpharness${id}`;
const storage = `--account-name ${account} --auth-mode key`;
const az = (command) => callTool("localstack-azure-client", { command }, 300000);
try {
const start = await callTool(
"localstack-management",
{ action: "start", service: "azure" },
300000
);
const answers = [`start: ${start.text}`];
let ok = !start.isError;
let blobs = "";
for (const command of [
`group create --name ${group} --location westeurope`,
`storage account create --name ${account} --resource-group ${group} --location westeurope --sku Standard_LRS`,
`storage container create --name data ${storage}`,
`storage blob upload --container-name data --name hello.txt --file ${AZURE_FILE} ${storage}`,
`storage blob list --container-name data ${storage} --query "[].name"`,
]) {
if (!ok) break;
const r = await az(command);
answers.push(`${command.split(" --")[0]}: ${r.text}`);
ok = !r.isError;
blobs = r.text;
}
ok = ok && /hello\.txt/.test(blobs);
recordToolResult(
"azure",
"localstack-azure-client group/storage account/blob upload",
{ text: answers.join("\n"), isError: !ok },
() => ok
);
} catch (e) {
record("azure", "azure-client", false, String(e.message));
} finally {
if (!NO_CLEANUP) {
try {
await az(`group delete --name ${group} --yes`);
} catch {}
try {
await callTool("localstack-management", { action: "stop" }, 60000);
} catch {}
}
}
}
}

main()
Expand Down