Docker Deployment

Relevant source files

• Dockerfile
• docker-compose.yml
• src/utils/logger.ts
• tests/integration-workflows.ts
• tests/test-all-tools-edge-cases.ts
• tests/test-docker.cjs

The Help Scout MCP Server is distributed as a containerized application to ensure consistent environments across development, testing, and production. The deployment strategy utilizes a multi-stage Dockerfile to minimize image size and maximize security, alongside docker-compose.yml for simplified local orchestration.

Multi-Stage Dockerfile Implementation

The server uses a two-stage build process. The first stage handles the TypeScript compilation and dependency resolution, while the second stage creates a hardened, minimal runtime environment.

1. Builder Stage

The builder stage uses node:20-alpine as its base Dockerfile2 It installs all dependencies, including devDependencies required for the TypeScript compiler (tsc), and generates the production JavaScript assets in the dist/ directory using npm run build Dockerfile12-19

2. Production Stage

The production stage also uses node:20-alpine Dockerfile22 but implements several security and optimization measures:

• Dependency Trimming: Only production dependencies are installed using npm ci --omit=dev Dockerfile35
• Non-Root User: A dedicated system user help-scout (UID 1001) and group nodejs (GID 1001) are created to run the application, adhering to the principle of least privilege Dockerfile25-26
• Artifact Transfer: Only the compiled dist/ folder and the mcp.json manifest are copied from the builder stage Dockerfile38-39
• Health Monitoring: A health check is defined to ensure the container is responsive, performing a basic Node.js execution check every 30 seconds Dockerfile49-50
• Entrypoint: The container defaults to executing the compiled CLI entry point at dist/cli.js Dockerfile53

Docker Build Flow

The following diagram illustrates the transition from source code to the final production image.

Diagram: Build Stage Transition

Sources: Dockerfile1-53

Docker Compose Configuration

For local development and testing, docker-compose.yml provides a standardized way to launch the server with the necessary environment variables and network configurations.

Feature	Configuration	Purpose
Context	.	Uses the local directory for building the image docker-compose.yml6-7
Env File	.env	Automatically loads Help Scout credentials and server settings docker-compose.yml10
Interactive	stdin_open: true, tty: true	Required for MCP servers communicating via Stdio docker-compose.yml12-13
Networking	helpscout-network	Bridges the container to other optional services like Redis docker-compose.yml14-15
Restart	unless-stopped	Ensures high availability unless manually terminated docker-compose.yml11

Sources: docker-compose.yml1-32

Container Runtime and Environment

The container is designed to be configured entirely via environment variables. These variables are mapped from the host or .env file into the container at runtime and consumed by the internal configuration logic.

Diagram: Environment to Code Mapping

Sources: src/utils/logger.ts13-14 docker-compose.yml10 tests/test-docker.cjs104-111

CI/CD and Automated Testing

The project's GitHub Actions pipeline automates the building of multi-platform images and verifies container integrity before publishing.

Docker Live Testing

The tests/test-docker.cjs script provides a comprehensive suite of live tests that build the image and verify MCP protocol compliance tests/test-docker.cjs7-31

Test Phase	Implementation	Requirement
Build	buildImage	Ensures docker build completes with exit code 0 tests/test-docker.cjs87-94
Startup	waitForStartup	Scans stderr for "Help Scout MCP Server started" message tests/test-docker.cjs120-147
Protocol	testMcpProtocol	Executes initialize and tools/list over stdin/stdout tests/test-docker.cjs201-233
Gateway	toolNames	Verifies search_help_scout, describe_help_scout, and read_help_scout are advertised tests/test-docker.cjs225-232

Multi-Platform Publishing

The pipeline utilizes docker buildx to build and push images for both linux/amd64 and linux/arm64 architectures. This ensures compatibility across standard cloud servers and Apple Silicon hardware.

Metadata Label	Source/Value
version	Matches package.json (e.g., "2.1.0") Dockerfile58
name	help-scout-mcp-server Dockerfile56
maintainer	Drew Burchfield Dockerfile59
io.modelcontextprotocol.server.name	io.github.drewburchfield/help-scout-mcp Dockerfile60

Sources: Dockerfile55-60 tests/test-docker.cjs1-233

Deployment Security

The Docker deployment adheres to several security best practices:

1. Non-root Execution: The USER help-scout instruction ensures the process does not have root privileges inside the container, mitigating potential breakout risks Dockerfile43
2. Minimal Surface Area: By using node:20-alpine and omitting devDependencies, the image size is reduced and the number of installed packages is minimized Dockerfile22-35
3. Secret Management: Credentials are never baked into the image. They are injected at runtime via environment variables docker-compose.yml10
4. Graceful Error Handling: The server is tested to ensure it fails with descriptive messages regarding missing HELPSCOUT_APP_ID or HELPSCOUT_APP_SECRET tests/test-docker.cjs100-102

Sources: Dockerfile22-43 tests/test-docker.cjs96-102