diff --git a/README.md b/README.md index 0f4787a..e0e397a 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,46 @@ +
+ +LocalStack MCP Server + # LocalStack MCP Server +**Let an AI agent manage and interact with LocalStack on your machine.** + +[![npm version](https://img.shields.io/npm/v/@localstack/localstack-mcp-server)](https://www.npmjs.com/package/@localstack/localstack-mcp-server) +[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](./LICENSE) +[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-localstack-blue)](https://registry.modelcontextprotocol.io/) + +
+ > [!IMPORTANT] > The LocalStack MCP server is currently available as an experimental public preview. For questions, issues or feedback, please utilize the [LocalStack Community slack](https://slack.localstack.cloud) or submit a [GitHub Issue](https://github.com/localstack/localstack-mcp-server/issues) -A [Model Context Protocol](https://modelcontextprotocol.io/docs/getting-started/intro) (MCP) server that provides tools to manage and interact with your [LocalStack for AWS](https://www.localstack.cloud/localstack-for-aws) container for simplified local cloud development and testing. The LocalStack MCP Server provides simplified integration between MCP-compatible apps and your local LocalStack for AWS development environment, enabling secure and direct communication with LocalStack's emulated services and additional developer experience features. +LocalStack emulates the cloud on your local machine so software teams and AI agents can validate security, quality, and reliability faster and more safely than the cloud allows. This [Model Context Protocol](https://modelcontextprotocol.io/docs/getting-started/intro) (MCP) server lets any MCP client (Cursor, Claude, VS Code, and more) start LocalStack, deploy infrastructure, and debug your local cloud in natural language. -This server eliminates custom scripts and manual LocalStack management with direct access to: +## Quick start + +Set up the server in your MCP client with the interactive wizard: + +```bash +npx -y @localstack/localstack-mcp-server init +``` + +The wizard detects your installed clients, asks how you want to run the server, and writes the configuration for you. You need a LocalStack Auth Token; the wizard reads `LOCALSTACK_AUTH_TOKEN` from your environment or asks for it. For the full options, prerequisites, and manual setup, see [Installation](#installation). + +## What you can ask your agent + +Once the server is configured, talk to LocalStack through your agent in natural language: + +- "Start LocalStack and deploy the Terraform project in `./infra`, then tell me which resources came up." +- "My Lambda calls are failing. Read the LocalStack logs, find the permission errors, and generate an IAM policy that fixes them." +- "Inject 500ms of latency into DynamoDB and confirm my retry logic still works." +- "Search the LocalStack docs for how to enable S3 event notifications and summarize the steps." + +## How it works + +The server connects MCP-compatible apps directly to your local LocalStack environment and its emulated AWS services, so your assistant can operate the stack securely without custom scripts or manual setup. + +This server eliminates custom scripts and manual LocalStack management. Your agent can: - Start, stop, restart, and monitor LocalStack for AWS container status with built-in auth. - Deploy CDK, Terraform, and SAM projects with automatic configuration detection. @@ -19,9 +54,8 @@ This server eliminates custom scripts and manual LocalStack management with dire - Replicate external AWS resources into LocalStack with [AWS Replicator](https://docs.localstack.cloud/aws/tooling/aws-replicator/) so IaC stacks can resolve shared dependencies locally. - Inspect LocalStack application flows with [App Inspector](https://docs.localstack.cloud/aws/capabilities/web-app/app-inspector/) traces, spans, events, payload metadata, and IAM policy evaluations. - Start repeatable LocalStack workflows from ready-made MCP prompts, including infrastructure validation and integration test generation. -- Connect AI assistants and dev tools for automated cloud testing workflows. -## Tools Reference +## Tools This server provides your AI with dedicated tools for managing your LocalStack environment: @@ -43,18 +77,19 @@ This server provides your AI with dedicated tools for managing your LocalStack e | [`localstack-aws-replicator`](./src/tools/localstack-aws-replicator.ts) | Replicates external AWS resources into a running LocalStack instance | - Start single-resource replication jobs with a resource type and identifier or ARN
- Start batch replication jobs, such as SSM parameters under a path prefix
- Poll job status by job ID and list existing jobs
- List resource types supported by the running Replicator extension
- Reads source AWS credentials from the MCP server environment and supports optional target account or region overrides | | [`localstack-app-inspector`](./src/tools/localstack-app-inspector.ts) | Inspects LocalStack application traces, spans, events, and IAM evaluations | - Enable or disable App Inspector for the running LocalStack instance
- List and inspect traces to understand AWS service-to-service flows
- Drill into spans, events, payload metadata, and IAM policy evaluation events
- Filter by service, region, operation, resource, ARN, status, and time range
- Requires a valid LocalStack Auth Token and the App Inspector feature in the connected LocalStack license | | [`localstack-docs`](./src/tools/localstack-docs.ts) | Searches LocalStack documentation through CrawlChat | - Queries LocalStack docs through a public CrawlChat collection
- Returns focused snippets with source links only
- Helps answer coverage, configuration, and setup questions without requiring LocalStack runtime | +| [`localstack-snowflake-client`](./src/tools/localstack-snowflake-client.ts) | Runs SQL against the LocalStack Snowflake emulator through the `snow` CLI | - Execute SELECT, DDL (CREATE/DROP), DML (INSERT/UPDATE/DELETE), and SHOW/DESCRIBE statements from a query string or a `.sql` file
- Check the Snowflake connection before running queries
- Set optional database, schema, warehouse, and role context per query
- Requires the Snowflake CLI (`snow`) and a valid LocalStack Auth Token | ## Prompts Prompts are user-selected workflow templates exposed by MCP clients as slash commands or quick actions. They frame multi-step LocalStack tasks so the assistant follows the same phases, evidence requirements, and reporting format every time. -| Prompt Name | Description | Arguments | -| :---------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :--------------------------------------------------------------------------------------------- | -| `infrastructure-tester` | Deploys an IaC project to LocalStack, validates declared resources with live AWS probes and App Inspector evidence, then writes and runs deterministic integration tests. | `iac_path` (required), `iac_type`, `test_language`, `test_framework`, `mode`, `services_focus` | +| Prompt Name | Description | Arguments | +| :---------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------------ | +| `infrastructure-tester` | Deploys an IaC project to LocalStack, validates declared resources with live AWS probes and App Inspector evidence, then writes and runs deterministic integration tests. | `iac_path` (required), `iac_type`, `test_language`, `test_framework`, `mode`, `services_focus`, `user_focus` | ## Installation -### Quick Setup (Wizard) +### Set up with the wizard (recommended) The fastest way to install the MCP server is the interactive setup wizard: @@ -84,9 +119,7 @@ npx -y @localstack/localstack-mcp-server remove Run `npx -y @localstack/localstack-mcp-server init --help` for all options. -### Setup using npx - -#### Prerequisites +### Prerequisites - [LocalStack CLI](https://docs.localstack.cloud/getting-started/installation/#localstack-cli) and Docker installed in your system path - [`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 @@ -94,7 +127,7 @@ Run `npx -y @localstack/localstack-mcp-server init --help` for all options. - A [valid LocalStack Auth Token](https://docs.localstack.cloud/aws/getting-started/auth-token/) configured as `LOCALSTACK_AUTH_TOKEN` (**required for all MCP tools**) - [Node.js v20](https://nodejs.org/en/download/) or higher installed in your system path -#### Configuration +### Run with npx Add the following to your MCP client's configuration file (e.g., `~/.cursor/mcp.json`). This configuration uses `npx` to run the server, which will automatically download and install the package if needed. LocalStack and any deployment CLIs used by tools run from your host PATH. @@ -114,6 +147,8 @@ Add the following to your MCP client's configuration file (e.g., `~/.cursor/mcp. All LocalStack MCP tools require `LOCALSTACK_AUTH_TOKEN` to be set. You can get your LocalStack Auth Token by following the official [documentation](https://docs.localstack.cloud/aws/getting-started/auth-token/). +### Run from source + If you installed from source, change `command` and `args` to point to your local build: ```json @@ -130,7 +165,7 @@ If you installed from source, change `command` and `args` to point to your local } ``` -### Setup using Docker +### Run with Docker The `localstack/localstack-mcp-server` Docker image bundles the LocalStack CLI, `awslocal`, Terraform/`tflocal`, CDK/`cdklocal`, SAM/`samlocal`, Snowflake CLI, and Docker 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. @@ -162,10 +197,10 @@ If you use the deployer tool with local Terraform, CDK, or SAM projects, bind-mo See **[docs/DOCKER.md](./docs/DOCKER.md)** for the run command, MCP client config, IaC project mounts, CDK notes, and troubleshooting. -## LocalStack Configuration +## LocalStack configuration | Variable Name | Description | Default Value | -| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------- | +| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------- | | `LOCALSTACK_AUTH_TOKEN` (**required**) | The LocalStack Auth Token to use for the MCP server | None | | `MAIN_CONTAINER_NAME` | The name of the LocalStack container to use for the MCP server | `localstack-main` | | `MCP_ANALYTICS_DISABLED` | Disable MCP analytics when set to `1` | `0` | diff --git a/icon.png b/icon.png index 06ec5c3..dcccc52 100644 Binary files a/icon.png and b/icon.png differ diff --git a/package.json b/package.json index 8eb647d..f528e87 100644 --- a/package.json +++ b/package.json @@ -8,7 +8,7 @@ }, "scripts": { "build": "xmcp build && yarn build:cli", - "build:cli": "esbuild src/cli/index.ts --bundle --platform=node --format=cjs --target=node20 --tsconfig=tsconfig.cli.json --alias:jsonc-parser=jsonc-parser/lib/esm/main.js --outfile=dist/cli.js --external:./stdio.js \"--banner:js=#!/usr/bin/env node\" --log-level=warning", + "build:cli": "esbuild src/cli/index.ts --bundle --platform=node --format=cjs --target=node22 --tsconfig=tsconfig.cli.json --alias:jsonc-parser=jsonc-parser/lib/esm/main.js --outfile=dist/cli.js --external:./stdio.js \"--banner:js=#!/usr/bin/env node\" --log-level=warning", "dev": "xmcp dev", "start": "node dist/stdio.js", "prepack": "yarn build", @@ -21,7 +21,7 @@ "dependencies": { "dockerode": "^4.0.7", "posthog-node": "5.0.0", - "xmcp": "0.6.4", + "xmcp": "^0.6.11", "zod": "4.3.6" }, "devDependencies": { diff --git a/server.json b/server.json index c824217..09f96c5 100644 --- a/server.json +++ b/server.json @@ -1,5 +1,5 @@ { - "$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json", + "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json", "name": "io.github.localstack/localstack-mcp-server", "description": "A LocalStack MCP Server providing essential tools for local cloud development & testing", "status": "active", @@ -8,6 +8,13 @@ "source": "github" }, "version": "0.4.0", + "icons": [ + { + "src": "https://raw.githubusercontent.com/localstack/localstack-mcp-server/main/icon.png", + "mimeType": "image/png", + "sizes": ["256x256"] + } + ], "packages": [ { "registry_type": "npm", diff --git a/xmcp.config.ts b/xmcp.config.ts index d0a6556..a5a7766 100644 --- a/xmcp.config.ts +++ b/xmcp.config.ts @@ -1,5 +1,8 @@ import { type XmcpConfig } from "xmcp"; +const ICON_URL = + "https://raw.githubusercontent.com/localstack/localstack-mcp-server/main/icon.png"; + const config: XmcpConfig = { stdio: true, paths: { @@ -8,6 +11,19 @@ const config: XmcpConfig = { typescript: { skipTypeCheck: true, }, + template: { + name: "LocalStack", + description: + "Manage and interact with LocalStack for local cloud development and testing", + homePage: "https://www.localstack.cloud", + icons: [ + { + src: ICON_URL, + mimeType: "image/png", + sizes: ["256x256"], + }, + ], + }, }; export default config; diff --git a/yarn.lock b/yarn.lock index 3903cd5..0873b83 100644 --- a/yarn.lock +++ b/yarn.lock @@ -1252,7 +1252,30 @@ "@jsonjoy.com/buffers" "^1.0.0" "@jsonjoy.com/codegen" "^1.0.0" -"@modelcontextprotocol/sdk@^1.25.3", "@modelcontextprotocol/sdk@^1.27.1": +"@modelcontextprotocol/sdk@^1.26.0": + version "1.29.0" + resolved "https://registry.yarnpkg.com/@modelcontextprotocol/sdk/-/sdk-1.29.0.tgz#79786d8b525e269de850ac82b1f1f757f3915f44" + integrity sha512-zo37mZA9hJWpULgkRpowewez1y6ML5GsXJPY8FI0tBBCd77HEvza4jDqRKOXgHNn867PVGCyTdzqpz0izu5ZjQ== + dependencies: + "@hono/node-server" "^1.19.9" + ajv "^8.17.1" + ajv-formats "^3.0.1" + content-type "^1.0.5" + cors "^2.8.5" + cross-spawn "^7.0.5" + eventsource "^3.0.2" + eventsource-parser "^3.0.0" + express "^5.2.1" + express-rate-limit "^8.2.1" + hono "^4.11.4" + jose "^6.1.3" + json-schema-typed "^8.0.2" + pkce-challenge "^5.0.0" + raw-body "^3.0.0" + zod "^3.25 || ^4.0" + zod-to-json-schema "^3.25.1" + +"@modelcontextprotocol/sdk@^1.27.1": version "1.27.1" resolved "https://registry.yarnpkg.com/@modelcontextprotocol/sdk/-/sdk-1.27.1.tgz#a602cf823bf8a68e13e7112f50aeb02b09fb83b9" integrity sha512-sr6GbP+4edBwFndLbM60gf07z0FQ79gaExpnsjMGePXqFcSSb7t6iscpjk9DhFhwd+mTEQrzNafGP8/iGGFYaA== @@ -4958,12 +4981,12 @@ wsl-utils@^0.1.0: dependencies: is-wsl "^3.1.0" -xmcp@0.6.4: - version "0.6.4" - resolved "https://registry.yarnpkg.com/xmcp/-/xmcp-0.6.4.tgz#b0ed5e955e88d0f061ffd9df9534d9c7340fdf50" - integrity sha512-aigY10YfKfG7BZ2MCq+Lbudgp25F28at8IzXt/rDYAD+iBfUeMsTkzCAO4s81L0miVCtJUB3arY8s4/hY3FsSA== +xmcp@^0.6.11: + version "0.6.11" + resolved "https://registry.yarnpkg.com/xmcp/-/xmcp-0.6.11.tgz#b36857b5fdb250ae3763d0f30ad51f4ff88656a7" + integrity sha512-quQg1sgZlWlB9w6wPpTGhe2ZzNXyXJdc6wi7UoTa29xM/p6Ir272+noqcrawGPHOKm2L98NIUI36r/ee4fG0Hw== dependencies: - "@modelcontextprotocol/sdk" "^1.25.3" + "@modelcontextprotocol/sdk" "^1.26.0" "@rspack/core" "^1.6.7" jose "^6.1.3" postcss-loader "^8.2.0"