@supernova123/docker-mcp-server 0.2.3 → 0.2.5

package/README.md

@@ -141,11 +141,21 @@ claude mcp add docker -- npx -y @supernova123/docker-mcp-server
 
 ## Security
 
+This server has **full Docker daemon access** via the Docker socket. It is designed for local development and trusted environments.
+
 - **Read-only by default**: all container and image tools read state; write operations (start/stop/remove) require explicit tool calls
-- **No API keys needed**: connects to local Docker daemon via socket
+- **No API keys needed**: connects to local Docker socket (`/var/run/docker.sock`), not remote API tokens
 - **No network access**: all operations are local Docker API calls
+- **Input validation**: Zod schemas on every tool parameter — command injection, path traversal, and env injection are rejected at the schema level
+- **Output sanitization**: ANSI escape codes, invisible Unicode, and Docker stream headers are stripped from all tool output
+- **Output size caps**: log output capped at 100KB, general output at 1MB, to prevent LLM context overflow
+- **Parameter bounds**: command arrays limited to 50 args, env to 50 vars, log tail to 10K lines, timeouts enforced (600s health, 300s events)
 - **MIT License**: fully auditable
 
+**Threat model**: any tool that calls Docker through this server can start any container with any flags, including privileged. The threat model is the same as giving a user shell access to the Docker socket. Do not expose this server to untrusted users.
+
+For vulnerability reports, see [SECURITY.md](SECURITY.md).
+
 ## License
 
 MIT

package/SECURITY.md

@@ -0,0 +1,52 @@
+# Security
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability in this project, please report it responsibly.
+
+**Email:** security@friendlygeorge.org
+
+Please do not file public GitHub issues for security bugs.
+
+## Supported Versions
+
+The latest release on npm (`@supernova123/docker-mcp-server`) is the only supported version. Security fixes are applied to the latest release only.
+
+## Threat Model
+
+This server has **full Docker daemon access** via the Docker socket (`/var/run/docker.sock`). It is designed for **local development and trusted environments**.
+
+**In scope:**
+- Input validation on all tool parameters (command injection, path traversal, env injection)
+- Output sanitization (ANSI escape stripping, invisible Unicode removal, output size caps)
+- Schema-level bounds on all numeric and array parameters
+
+**Out of scope:**
+- Exposing this server to untrusted users or the public internet
+- Running in multi-tenant environments without additional isolation
+- Docker socket access control (by design, the server needs full daemon access)
+
+**Key security properties:**
+- No embedded credentials — the server uses the Docker socket, not API tokens
+- No network egress — all communication is local Docker API calls
+- Zod input validation on every tool parameter
+- Output sanitization prevents prompt injection via command output
+- Read-only tools marked with `readOnlyHint: true` in MCP metadata
+
+## Security Hardening (v0.2.5+)
+
+Starting with v0.2.5, the server includes:
+- **Command validation:** `exec_in_container` rejects shell metacharacters and enforces POSIX path rules
+- **Path validation:** `build_image` restricts build context to local absolute paths (no URLs)
+- **Output sanitization:** ANSI escapes, invisible Unicode, and Docker stream headers are stripped
+- **Output size caps:** Log output capped at 100KB, general output at 1MB
+- **Parameter bounds:** Command arrays limited to 50 args, env to 50 vars, log tail to 10K lines
+- **Timeout enforcement:** Health watch (600s max), event listening (300s max)
+
+## Dependencies
+
+Run `npm audit` regularly. The CI pipeline includes `npm audit --audit-level=high` on every push.
+
+## License
+
+MIT — see [LICENSE](LICENSE) for details.

package/dist/docker.d.ts

@@ -8,5 +8,10 @@ export declare function createDockerClient(options?: DockerClientOptions): Docke
 export declare function formatError(error: unknown): string;
 export declare function formatContainer(container: Dockerode.ContainerInfo): Record<string, unknown>;
 export declare function formatImage(image: Dockerode.ImageInfo): Record<string, unknown>;
+/**
+ * Sanitize tool output: strip ANSI escapes, invisible Unicode, and truncate.
+ * Prevents prompt injection via output and caps LLM context cost.
+ */
+export declare function sanitizeOutput(text: string, maxLength?: number): string;
 export declare function formatBytes(bytes: number): string;
 //# sourceMappingURL=docker.d.ts.map

package/dist/docker.js

@@ -47,6 +47,25 @@ export function formatImage(image) {
         created: new Date(image.Created).toISOString(),
     };
 }
+/**
+ * Sanitize tool output: strip ANSI escapes, invisible Unicode, and truncate.
+ * Prevents prompt injection via output and caps LLM context cost.
+ */
+export function sanitizeOutput(text, maxLength = 1_000_000) {
+    // Strip ANSI escape codes (CSI, OSC, simple sequences)
+    text = text.replace(/\x1b\[[0-9;?]*[a-zA-Z]/g, "");
+    text = text.replace(/\x1b\][^\x07]*\x07/g, ""); // OSC terminated by BEL
+    text = text.replace(/\x1b[@-Z\\-_]/g, ""); // Single-char escapes
+    // Strip invisible Unicode (Tag chars, bidi overrides, zero-width)
+    text = text.replace(/[\uE0001-\uE007F\u200B-\u200F\u202A-\u202E\u2060-\u206F\uFEFF]/g, "");
+    // Strip Docker stream-frame headers (8-byte prefix per frame)
+    text = text.replace(/^[\x00-\x0f]{8}/gm, "");
+    // Truncate to cap memory and LLM context cost
+    if (text.length > maxLength) {
+        return text.slice(0, maxLength) + `\n... [output truncated at ${maxLength} chars]`;
+    }
+    return text;
+}
 export function formatBytes(bytes) {
     if (bytes === 0)
         return "0 B";

package/dist/tools/compose.js

@@ -3,7 +3,7 @@ import { existsSync, statSync } from "fs";
 import { join } from "path";
 import { promisify } from "util";
 import { ComposeUpSchema, ComposeDownSchema, ComposePsSchema, ComposeLogsSchema, ComposeRestartSchema, } from "../types.js";
-import { formatError } from "../docker.js";
+import { formatError, sanitizeOutput } from "../docker.js";
 const execAsync = promisify(execCb);
 const COMPOSE_FILE_NAMES = ["docker-compose.yml", "docker-compose.yaml", "compose.yml", "compose.yaml"];
 function resolveComposePath(inputPath) {
@@ -38,7 +38,7 @@ function runCompose(path, args) {
     }
 }
 export function registerComposeTools(server) {
-    server.tool("compose_up", "Bring up Docker Compose services from a docker-compose.yml file. Optionally build images first.", ComposeUpSchema.shape, async (params) => {
+    server.tool("compose_up", "Bring up Docker Compose services from a docker-compose.yml file. Optionally build images first.", ComposeUpSchema.shape, { idempotentHint: true, openWorldHint: false }, async (params) => {
         try {
             const args = ["up", "-d"];
             if (params.build)
@@ -52,7 +52,7 @@ export function registerComposeTools(server) {
             return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
         }
     });
-    server.tool("compose_down", "Tear down Docker Compose services. Optionally remove named volumes.", ComposeDownSchema.shape, async (params) => {
+    server.tool("compose_down", "Tear down Docker Compose services. Optionally remove named volumes.", ComposeDownSchema.shape, { destructiveHint: true, openWorldHint: false }, async (params) => {
         try {
             const args = ["down"];
             if (params.volumes)
@@ -66,7 +66,7 @@ export function registerComposeTools(server) {
             return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
         }
     });
-    server.tool("compose_ps", "List service states across a Docker Compose stack.", ComposePsSchema.shape, async (params) => {
+    server.tool("compose_ps", "List service states across a Docker Compose stack.", ComposePsSchema.shape, { readOnlyHint: true, idempotentHint: true, openWorldHint: false }, async (params) => {
         try {
             const output = runCompose(params.path, ["ps", "--format", "json"]);
             const lines = output.split("\n").filter(Boolean);
@@ -92,13 +92,14 @@ export function registerComposeTools(server) {
             if (params.services?.length)
                 args.push(...params.services);
             const output = runCompose(params.path, args);
-            return { content: [{ type: "text", text: output || "No logs found." }] };
+            // Use 100KB cap for log output to keep LLM context small
+            return { content: [{ type: "text", text: sanitizeOutput(output, 100_000) || "No logs found." }] };
         }
         catch (error) {
             return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
         }
     });
-    server.tool("compose_restart", "Restart Docker Compose services. Restart specific services or the entire stack.", ComposeRestartSchema.shape, async (params) => {
+    server.tool("compose_restart", "Restart Docker Compose services. Restart specific services or the entire stack.", ComposeRestartSchema.shape, { destructiveHint: true, idempotentHint: true, openWorldHint: false }, async (params) => {
         try {
             const args = ["restart"];
             if (params.timeout)

package/dist/tools/container.js

@@ -1,7 +1,7 @@
 import { ListContainersSchema, InspectContainerSchema, StartContainerSchema, StopContainerSchema, RestartContainerSchema, RemoveContainerSchema, RecreateContainerSchema, RunContainerSchema, } from "../types.js";
 import { formatContainer, formatError } from "../docker.js";
 export function registerContainerTools(server, docker) {
-    server.tool("list_containers", "List Docker containers with optional filters (state, label, name). Returns container IDs, names, images, states, ports, and labels.", ListContainersSchema.shape, async (params) => {
+    server.tool("list_containers", "List Docker containers with optional filters (state, label, name). Returns container IDs, names, images, states, ports, and labels.", ListContainersSchema.shape, { readOnlyHint: true, idempotentHint: true, openWorldHint: false }, async (params) => {
         try {
             const containers = await docker.listContainers({
                 all: params.all ?? false,
@@ -18,7 +18,7 @@ export function registerContainerTools(server, docker) {
             return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
         }
     });
-    server.tool("inspect_container", "Get detailed configuration and state of a Docker container by ID or name.", InspectContainerSchema.shape, async (params) => {
+    server.tool("inspect_container", "Get detailed configuration and state of a Docker container by ID or name.", InspectContainerSchema.shape, { readOnlyHint: true, idempotentHint: true, openWorldHint: false }, async (params) => {
         try {
             const container = docker.getContainer(params.container_id);
             const info = await container.inspect();
@@ -28,7 +28,7 @@ export function registerContainerTools(server, docker) {
             return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
         }
     });
-    server.tool("start_container", "Start a stopped Docker container by ID or name.", StartContainerSchema.shape, async (params) => {
+    server.tool("start_container", "Start a stopped Docker container by ID or name.", StartContainerSchema.shape, { idempotentHint: true, openWorldHint: false }, async (params) => {
         try {
             const container = docker.getContainer(params.container_id);
             await container.start();
@@ -38,7 +38,7 @@ export function registerContainerTools(server, docker) {
             return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
         }
     });
-    server.tool("stop_container", "Stop a running Docker container by ID or name with optional timeout.", StopContainerSchema.shape, async (params) => {
+    server.tool("stop_container", "Stop a running Docker container by ID or name with optional timeout.", StopContainerSchema.shape, { destructiveHint: true, openWorldHint: false }, async (params) => {
         try {
             const container = docker.getContainer(params.container_id);
             await container.stop({ t: params.timeout ?? 10 });
@@ -62,7 +62,7 @@ export function registerContainerTools(server, docker) {
             return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
         }
     });
-    server.tool("remove_container", "Remove a Docker container by ID or name. Use force to remove running containers.", RemoveContainerSchema.shape, async (params) => {
+    server.tool("remove_container", "Remove a Docker container by ID or name. Use force to remove running containers.", RemoveContainerSchema.shape, { destructiveHint: true, openWorldHint: false }, async (params) => {
         try {
             const container = docker.getContainer(params.container_id);
             await container.remove({ force: params.force ?? false });
@@ -72,7 +72,7 @@ export function registerContainerTools(server, docker) {
             return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
         }
     });
-    server.tool("recreate_container", "Recreate a container with the same configuration (stop, remove, re-create). Useful for applying config changes.", RecreateContainerSchema.shape, async (params) => {
+    server.tool("recreate_container", "Recreate a container with the same configuration (stop, remove, re-create). Useful for applying config changes.", RecreateContainerSchema.shape, { destructiveHint: true, idempotentHint: true, openWorldHint: false }, async (params) => {
         try {
             const container = docker.getContainer(params.container_id);
             const info = await container.inspect();
@@ -107,7 +107,7 @@ export function registerContainerTools(server, docker) {
             return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
         }
     });
-    server.tool("run_container", "Create and start a new Docker container with one command. Supports image, env, ports, volumes, restart policy, and command override. Auto-pulls missing images.", RunContainerSchema.shape, async (params) => {
+    server.tool("run_container", "Create and start a new Docker container with one command. Supports image, env, ports, volumes, restart policy, and command override. Auto-pulls missing images.", RunContainerSchema.shape, { openWorldHint: false }, async (params) => {
         try {
             const createOpts = {
                 Image: params.image,

package/dist/tools/exec.js

@@ -1,7 +1,7 @@
 import { ExecInContainerSchema } from "../types.js";
-import { formatError } from "../docker.js";
+import { formatError, sanitizeOutput } from "../docker.js";
 export function registerExecTools(server, docker) {
-    server.tool("exec_in_container", "Execute a command inside a running Docker container. Returns stdout, stderr, and exit code.", ExecInContainerSchema.shape, async (params) => {
+    server.tool("exec_in_container", "Execute a command inside a running Docker container. Returns stdout, stderr, and exit code.", ExecInContainerSchema.shape, { openWorldHint: false }, async (params) => {
         try {
             const container = docker.getContainer(params.container_id);
             const exec = await container.exec({
@@ -18,7 +18,7 @@ export function registerExecTools(server, docker) {
                 stream.on("end", () => resolve(data));
             });
             const inspect = await exec.inspect();
-            const cleanOutput = output.replace(/^[\x00-\x0f]{8}/gm, "");
+            const cleanOutput = sanitizeOutput(output);
             return {
                 content: [{
                         type: "text",

package/dist/tools/health.js

@@ -1,7 +1,7 @@
 import { CheckHealthSchema, WatchHealthSchema, SetRestartPolicySchema } from "../types.js";
 import { formatError } from "../docker.js";
 export function registerHealthTools(server, docker) {
-    server.tool("check_health", "Run a health probe against a container. Supports HTTP, TCP, and exec probes. Auto-detects from container HEALTHCHECK if available.", CheckHealthSchema.shape, async (params) => {
+    server.tool("check_health", "Run a health probe against a container. Supports HTTP, TCP, and exec probes. Auto-detects from container HEALTHCHECK if available.", CheckHealthSchema.shape, { readOnlyHint: true, idempotentHint: true, openWorldHint: false }, async (params) => {
         try {
             const container = docker.getContainer(params.container_id);
             const info = await container.inspect();
@@ -62,7 +62,7 @@ export function registerHealthTools(server, docker) {
             return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
         }
     });
-    server.tool("watch_health", "Poll a container's health status until it becomes healthy or times out. Useful for waiting on service startup.", WatchHealthSchema.shape, async (params) => {
+    server.tool("watch_health", "Poll a container's health status until it becomes healthy or times out. Useful for waiting on service startup.", WatchHealthSchema.shape, { readOnlyHint: true, idempotentHint: true, openWorldHint: false }, async (params) => {
         try {
             const container = docker.getContainer(params.container_id);
             const timeout = (params.timeout ?? 60) * 1000;
@@ -108,7 +108,7 @@ export function registerHealthTools(server, docker) {
             return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
         }
     });
-    server.tool("set_restart_policy", "Change the restart policy of a running container without recreating it.", SetRestartPolicySchema.shape, async (params) => {
+    server.tool("set_restart_policy", "Change the restart policy of a running container without recreating it.", SetRestartPolicySchema.shape, { idempotentHint: true, openWorldHint: false }, async (params) => {
         try {
             const container = docker.getContainer(params.container_id);
             await container.update({

package/dist/tools/image.js

@@ -1,7 +1,7 @@
 import { ListImagesSchema, PullImageSchema, BuildImageSchema, RemoveImageSchema, } from "../types.js";
 import { formatImage, formatError } from "../docker.js";
 export function registerImageTools(server, docker) {
-    server.tool("list_images", "List Docker images with optional filters. Returns image IDs, tags, sizes, and creation dates.", ListImagesSchema.shape, async (params) => {
+    server.tool("list_images", "List Docker images with optional filters. Returns image IDs, tags, sizes, and creation dates.", ListImagesSchema.shape, { readOnlyHint: true, idempotentHint: true, openWorldHint: false }, async (params) => {
         try {
             const images = await docker.listImages({
                 all: params.all ?? false,
@@ -14,7 +14,7 @@ export function registerImageTools(server, docker) {
             return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
         }
     });
-    server.tool("pull_image", "Pull a Docker image from a registry. Returns pull progress events.", PullImageSchema.shape, async (params) => {
+    server.tool("pull_image", "Pull a Docker image from a registry. Returns pull progress events.", PullImageSchema.shape, { idempotentHint: true, openWorldHint: false }, async (params) => {
         try {
             const imageRef = params.tag ? `${params.image}:${params.tag}` : params.image;
             const stream = await docker.pull(imageRef);
@@ -33,7 +33,7 @@ export function registerImageTools(server, docker) {
             return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
         }
     });
-    server.tool("build_image", "Build a Docker image from a Dockerfile or build context path.", BuildImageSchema.shape, async (params) => {
+    server.tool("build_image", "Build a Docker image from a Dockerfile or build context path.", BuildImageSchema.shape, { idempotentHint: true, openWorldHint: false }, async (params) => {
         try {
             const stream = await docker.buildImage({
                 context: params.context,
@@ -53,7 +53,7 @@ export function registerImageTools(server, docker) {
             return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
         }
     });
-    server.tool("remove_image", "Remove a Docker image by name or ID. Use force to remove even if tagged.", RemoveImageSchema.shape, async (params) => {
+    server.tool("remove_image", "Remove a Docker image by name or ID. Use force to remove even if tagged.", RemoveImageSchema.shape, { destructiveHint: true, openWorldHint: false }, async (params) => {
         try {
             const image = docker.getImage(params.image);
             await image.remove({ force: params.force ?? false });

package/dist/tools/logs.js

@@ -1,5 +1,5 @@
 import { StreamLogsSchema, ContainerStatsSchema } from "../types.js";
-import { formatError, formatBytes } from "../docker.js";
+import { formatError, formatBytes, sanitizeOutput } from "../docker.js";
 export function registerLogsTools(server, docker) {
     server.tool("stream_logs", "Get logs from a single Docker container by ID or name. Use stream_logs for one container; use compose_logs for multi-service Compose stacks. Supports tail count (default 100 lines), since timestamp for filtering, and follow mode. Returns UTF-8 log text with multiplexed stream headers stripped, or 'No logs found.' when the container has no output. Read-only and safe to call repeatedly. Returns an error string if the container does not exist.", StreamLogsSchema.shape, { readOnlyHint: true, idempotentHint: true, openWorldHint: false }, async (params) => {
         try {
@@ -12,14 +12,15 @@ export function registerLogsTools(server, docker) {
                 follow: false,
             });
             // Dockerode returns a Buffer with multiplexed stream headers
-            const output = logs.toString("utf-8").replace(/^[\x00-\x0f]{8}/gm, "");
+            // Use 100KB cap for logs to keep LLM context small
+            const output = sanitizeOutput(logs.toString("utf-8"), 100_000);
             return { content: [{ type: "text", text: output || "No logs found." }] };
         }
         catch (error) {
             return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
         }
     });
-    server.tool("container_stats", "Get real-time resource usage statistics for a Docker container (CPU, memory, network, I/O).", ContainerStatsSchema.shape, async (params) => {
+    server.tool("container_stats", "Get real-time resource usage statistics for a Docker container (CPU, memory, network, I/O).", ContainerStatsSchema.shape, { readOnlyHint: true, idempotentHint: true, openWorldHint: false }, async (params) => {
         try {
             const container = docker.getContainer(params.container_id);
             const stats = await container.stats({ stream: false });

package/dist/tools/monitoring.js

@@ -1,7 +1,8 @@
 import { ContainerHealthStatusSchema, ContainerResourceUsageSchema, WatchEventsSchema, SearchLogsSchema, ResourceAlertCheckSchema, MonitorDashboardSchema, } from "../types.js";
+import { sanitizeOutput } from "../docker.js";
 export function registerMonitoringTools(server, docker) {
     // 1. fleet_status — health status of all running containers
-    server.tool("container_health_status", "Check health status, uptime, and restart count for all running Docker containers. Returns JSON with container name, state, health probe status, and restart count.", ContainerHealthStatusSchema.shape, async (params) => {
+    server.tool("container_health_status", "Check health status, uptime, and restart count for all running Docker containers. Returns JSON with container name, state, health probe status (healthy/unhealthy/no-healthcheck), and restart count. Use this for a quick fleet health overview; for resource metrics use container_resource_usage instead. Returns an array of objects with name, id, state, status, health, uptime, restartCount, and image fields. Read-only and safe to call repeatedly.", ContainerHealthStatusSchema.shape, { readOnlyHint: true, idempotentHint: true, openWorldHint: false }, async (params) => {
         try {
             const containers = await docker.listContainers({ all: false });
             const results = await Promise.all(containers.map(async (c) => {
@@ -29,7 +30,7 @@ export function registerMonitoringTools(server, docker) {
         }
     });
     // 2. fleet_stats — resource usage for all running containers
-    server.tool("container_resource_usage", "Monitor CPU, memory, and network I/O across all running Docker containers. Returns sorted resource usage metrics with percentage breakdowns.", ContainerResourceUsageSchema.shape, async (params) => {
+    server.tool("container_resource_usage", "Monitor CPU, memory, and network I/O across all running Docker containers. Returns sorted resource usage metrics with percentage breakdowns for each container. Use container_health_status for health probes; use resource_alert_check for threshold violations. Supports sort by cpu, memory, or network. Returns array of objects with name, id, cpu_percent, memory_usage_mb, memory_percent, network_rx_mb, network_tx_mb. Read-only and safe to call repeatedly.", ContainerResourceUsageSchema.shape, { readOnlyHint: true, idempotentHint: true, openWorldHint: false }, async (params) => {
         try {
             const containers = await docker.listContainers({ all: false });
             const results = await Promise.all(containers.map(async (c) => {
@@ -73,7 +74,7 @@ export function registerMonitoringTools(server, docker) {
         }
     });
     // 3. watch_events — stream Docker events (simplified: collect events for a duration)
-    server.tool("watch_events", "Stream Docker container events (start, stop, die, restart, health_status) over a configurable time window. Filter by specific container or event type.", WatchEventsSchema.shape, async (params) => {
+    server.tool("watch_events", "Stream Docker container events (start, stop, die, restart, health_status) over a configurable time window. Filter by specific container or event type. Use container_health_status for current state; use this tool to watch for changes over time. Returns array of event objects with type, action, container, and time fields. Returns 'No events captured in the time window.' when no events occur. Read-only and safe to call repeatedly.", WatchEventsSchema.shape, { readOnlyHint: true, idempotentHint: true, openWorldHint: false }, async (params) => {
         try {
             const durationMs = (params.duration || 30) * 1000;
             const filter = {};
@@ -122,7 +123,7 @@ export function registerMonitoringTools(server, docker) {
         }
     });
     // 4. search_logs — search logs across multiple containers
-    server.tool("search_logs", "Search Docker container logs across multiple containers using regex pattern matching. Returns matching log lines with container name and timestamp.", SearchLogsSchema.shape, async (params) => {
+    server.tool("search_logs", "Search Docker container logs across multiple containers using regex pattern matching. Use stream_logs for single-container log tailing; use this tool to search across multiple containers at once. Returns matching log lines with container name and line content. The pattern parameter accepts any valid regex; set ignore_case for case-insensitive matching. Returns 'No matches found.' when no lines match. Read-only and safe to call repeatedly.", SearchLogsSchema.shape, { readOnlyHint: true, idempotentHint: true, openWorldHint: false }, async (params) => {
         try {
             const targetContainers = params.containers || [];
             let containers;
@@ -146,7 +147,7 @@ export function registerMonitoringTools(server, docker) {
                         tail: params.tail || 500,
                         since: params.since ? Math.floor(new Date(params.since).getTime() / 1000) : undefined,
                     });
-                    const output = logStream.toString("utf-8").replace(/^[\x00-\x0f]{8}/gm, "");
+                    const output = sanitizeOutput(logStream.toString("utf-8"), 100_000);
                     const lines = output.split("\n");
                     for (const line of lines) {
                         if (regex.test(line)) {
@@ -168,7 +169,7 @@ export function registerMonitoringTools(server, docker) {
         }
     });
     // 5. check_thresholds — check all containers against thresholds
-    server.tool("resource_alert_check", "Alert when Docker containers exceed resource thresholds (CPU%, memory%, restart count). Returns violations with specific metrics that triggered alerts.", ResourceAlertCheckSchema.shape, async (params) => {
+    server.tool("resource_alert_check", "Check all running Docker containers against configurable CPU%, memory%, and restart count thresholds. Returns containers that violate thresholds with specific metrics that triggered alerts. Use container_resource_usage for raw metrics; use this tool for automated alerting. Default thresholds: 80% CPU, 80% memory, 5 restarts. Returns { violations: [...], checked: N } or { message: 'All containers within thresholds.', checked: N }. Read-only and safe to call repeatedly.", ResourceAlertCheckSchema.shape, { readOnlyHint: true, idempotentHint: true, openWorldHint: false }, async (params) => {
         try {
             const cpuThreshold = params.cpu_percent ?? 80;
             const memThreshold = params.memory_percent ?? 80;
@@ -223,7 +224,7 @@ export function registerMonitoringTools(server, docker) {
         }
     });
     // 6. monitor_dashboard — single-call fleet summary
-    server.tool("monitor_dashboard", "Comprehensive Docker fleet dashboard in a single API call. Returns health status, top resource consumers, recent events, and threshold violations.", MonitorDashboardSchema.shape, async (params) => {
+    server.tool("monitor_dashboard", "Comprehensive Docker fleet dashboard in a single API call. Aggregates health status of all containers, top 5 CPU consumers, recent events (last 5 minutes), and threshold violations into one response. Use individual tools (container_health_status, container_resource_usage, watch_events) for targeted queries; use this for a complete fleet overview. Returns object with summary (total, running, healthy, unhealthy), top_consumers, recent_events, and violations. Read-only and safe to call repeatedly.", MonitorDashboardSchema.shape, { readOnlyHint: true, idempotentHint: true, openWorldHint: false }, async (params) => {
         try {
             const containers = await docker.listContainers({ all: false });
             // Fleet health

package/dist/tools/network.js

@@ -1,7 +1,7 @@
 import { ListNetworksSchema, ListVolumesSchema } from "../types.js";
 import { formatError } from "../docker.js";
 export function registerNetworkTools(server, docker) {
-    server.tool("list_networks", "List Docker networks with optional filter. Returns network IDs, names, drivers, and scopes.", ListNetworksSchema.shape, async (params) => {
+    server.tool("list_networks", "List Docker networks with optional filter. Returns network IDs, names, drivers, and scopes.", ListNetworksSchema.shape, { readOnlyHint: true, idempotentHint: true, openWorldHint: false }, async (params) => {
         try {
             const networks = await docker.listNetworks({
                 filters: params.filter ? JSON.stringify({ name: [params.filter] }) : undefined,
@@ -25,7 +25,7 @@ export function registerNetworkTools(server, docker) {
             return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
         }
     });
-    server.tool("list_volumes", "List Docker volumes with optional filter. Returns volume names, drivers, mount points, and labels.", ListVolumesSchema.shape, async (params) => {
+    server.tool("list_volumes", "List Docker volumes with optional filter. Returns volume names, drivers, mount points, and labels.", ListVolumesSchema.shape, { readOnlyHint: true, idempotentHint: true, openWorldHint: false }, async (params) => {
         try {
             const result = await docker.listVolumes({
                 filters: params.filter ? JSON.stringify({ name: [params.filter] }) : undefined,

package/dist/types.d.ts

@@ -320,15 +320,15 @@ export declare const WatchEventsSchema: z.ZodObject<{
     since: z.ZodOptional<z.ZodString>;
     duration: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
+    duration?: number | undefined;
     since?: string | undefined;
     container?: string | undefined;
     event_type?: "all" | "start" | "stop" | "die" | "restart" | "health_status" | "oom" | undefined;
-    duration?: number | undefined;
 }, {
+    duration?: number | undefined;
     since?: string | undefined;
     container?: string | undefined;
     event_type?: "all" | "start" | "stop" | "die" | "restart" | "health_status" | "oom" | undefined;
-    duration?: number | undefined;
 }>;
 export declare const SearchLogsSchema: z.ZodObject<{
     pattern: z.ZodString;

package/dist/types.js

@@ -1,4 +1,9 @@
 import { z } from "zod";
+// Validation regexes (shared across schemas)
+const SAFE_CMD_ARG = /^[A-Za-z0-9_./:@%+=,\-]+$/;
+const SAFE_PATH = /^\/[A-Za-z0-9_./\-]+$/;
+const SAFE_ENV_KEY = /^[A-Z_][A-Z0-9_]*$/;
+const SAFE_BUILD_CONTEXT = /^\/[A-Za-z0-9_./\-]+$/;
 // Container lifecycle schemas
 export const ListContainersSchema = z.object({
     all: z.boolean().optional().describe("Include stopped containers (default: false)"),
@@ -48,11 +53,12 @@ export const PullImageSchema = z.object({
     tag: z.string().optional().describe("Tag to pull (default: 'latest')"),
 });
 export const BuildImageSchema = z.object({
-    context: z.string().describe("Build context path or Dockerfile content"),
+    context: z.string().regex(SAFE_BUILD_CONTEXT, "Build context must be a local absolute path (no URLs, no '..')")
+        .max(4096).describe("Build context path (local absolute path only)"),
     tag: z.string().describe("Tag for the built image (e.g., 'myapp:v1')"),
-    dockerfile: z.string().optional().describe("Dockerfile name relative to context (default: 'Dockerfile')"),
-    build_args: z.record(z.string()).optional().describe("Build arguments"),
-    target: z.string().optional().describe("Target build stage"),
+    dockerfile: z.string().max(256).optional().describe("Dockerfile name relative to context (default: 'Dockerfile')"),
+    build_args: z.record(z.string().regex(SAFE_ENV_KEY, "Build arg key must be POSIX-style").max(256), z.string().max(4096)).optional().describe("Build arguments (keys must be POSIX-style)"),
+    target: z.string().max(256).optional().describe("Target build stage"),
 });
 export const RemoveImageSchema = z.object({
     image: z.string().describe("Image name or ID"),
@@ -93,8 +99,8 @@ export const CheckHealthSchema = z.object({
 });
 export const WatchHealthSchema = z.object({
     container_id: z.string().describe("Container ID or name"),
-    timeout: z.number().optional().describe("Max seconds to wait (default: 60)"),
-    interval: z.number().optional().describe("Seconds between polls (default: 5)"),
+    timeout: z.number().max(600).optional().describe("Max seconds to wait (default: 60, max: 600)"),
+    interval: z.number().max(60).optional().describe("Seconds between polls (default: 5, max: 60)"),
 });
 export const SetRestartPolicySchema = z.object({
     container_id: z.string().describe("Container ID or name"),
@@ -104,19 +110,21 @@ export const SetRestartPolicySchema = z.object({
 // Logs schemas
 export const StreamLogsSchema = z.object({
     container_id: z.string().describe("Container ID or name"),
-    tail: z.number().optional().describe("Number of lines to show (default: 100)"),
+    tail: z.number().max(10000).optional().describe("Number of lines to show (default: 100, max: 10000)"),
     since: z.string().optional().describe("Show logs since timestamp (e.g., '2026-01-01T00:00:00Z')"),
     follow: z.boolean().optional().describe("Follow log output (default: false)"),
 });
 export const ContainerStatsSchema = z.object({
     container_id: z.string().describe("Container ID or name"),
 });
-// Exec schema
+// Exec schema (validated per Finding 8.1 — command/working_dir/env constraints)
 export const ExecInContainerSchema = z.object({
     container_id: z.string().describe("Container ID or name"),
-    command: z.array(z.string()).describe("Command to execute"),
-    working_dir: z.string().optional().describe("Working directory inside container"),
-    env: z.record(z.string()).optional().describe("Environment variables"),
+    command: z.array(z.string().max(500).regex(SAFE_CMD_ARG, "Command arg contains disallowed characters"))
+        .min(1).max(50).describe("Command to execute (max 50 args, alphanumeric + safe chars only)"),
+    working_dir: z.string().regex(SAFE_PATH, "Working directory must be an absolute path without '..'")
+        .max(1000).optional().describe("Working directory inside container (absolute path)"),
+    env: z.record(z.string().regex(SAFE_ENV_KEY, "Env key must be POSIX-style (A-Z, 0-9, _)").max(100), z.string().max(1000)).optional().describe("Environment variables (keys must be POSIX-style)"),
 });
 // Network/Volume schemas
 export const ListNetworksSchema = z.object({
@@ -134,12 +142,12 @@ export const WatchEventsSchema = z.object({
     container: z.string().optional().describe("Filter by container name or ID"),
     event_type: z.enum(["start", "stop", "die", "restart", "health_status", "oom", "all"]).optional().describe("Filter by event type (default: all)"),
     since: z.string().optional().describe("Show events since timestamp (e.g., '2026-01-01T00:00:00Z')"),
-    duration: z.number().optional().describe("Max seconds to listen (default: 30)"),
+    duration: z.number().max(300).optional().describe("Max seconds to listen (default: 30, max: 300)"),
 });
 export const SearchLogsSchema = z.object({
-    pattern: z.string().describe("Regex or grep pattern to search for"),
-    containers: z.array(z.string()).optional().describe("Specific containers to search (default: all running)"),
-    tail: z.number().optional().describe("Max lines to scan per container (default: 500)"),
+    pattern: z.string().max(1000).describe("Regex or grep pattern to search for"),
+    containers: z.array(z.string()).max(50).optional().describe("Specific containers to search (default: all running, max: 50)"),
+    tail: z.number().max(10000).optional().describe("Max lines to scan per container (default: 500, max: 10000)"),
     since: z.string().optional().describe("Only search logs since timestamp"),
     ignore_case: z.boolean().optional().describe("Case-insensitive search (default: false)"),
 });

package/glama.json

@@ -0,0 +1,12 @@
+{
+  "$schema": "https://glama.ai/schemas/glama.json",
+  "maintainers": ["friendlygeorge"],
+  "title": "Docker MCP Server",
+  "description": "31 tools for AI agent Docker management — container lifecycle, Compose stack operations, health checks, log streaming, and fleet monitoring through the Model Context Protocol.",
+  "tags": ["docker", "containers", "mcp", "compose", "health-checks", "monitoring", "devops", "ai-agents", "typescript", "self-healing"],
+  "repository": "https://github.com/friendlygeorge/docker-mcp-server",
+  "license": "MIT",
+  "categories": ["virtualization", "developer-tools"],
+  "language": "TypeScript",
+  "runtime": "node"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supernova123/docker-mcp-server",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "mcpName": "io.github.friendlygeorge/docker-mcp-server",
   "description": "MCP server for Docker — container management, health checks, auto-restart, Compose lifecycle, and log streaming for Claude, Cursor, and AI agents",
   "type": "module",

package/src/docker.ts

@@ -56,6 +56,26 @@ export function formatImage(image: Dockerode.ImageInfo): Record<string, unknown>
   };
 }
 
+/**
+ * Sanitize tool output: strip ANSI escapes, invisible Unicode, and truncate.
+ * Prevents prompt injection via output and caps LLM context cost.
+ */
+export function sanitizeOutput(text: string, maxLength = 1_000_000): string {
+  // Strip ANSI escape codes (CSI, OSC, simple sequences)
+  text = text.replace(/\x1b\[[0-9;?]*[a-zA-Z]/g, "");
+  text = text.replace(/\x1b\][^\x07]*\x07/g, ""); // OSC terminated by BEL
+  text = text.replace(/\x1b[@-Z\\-_]/g, "");       // Single-char escapes
+  // Strip invisible Unicode (Tag chars, bidi overrides, zero-width)
+  text = text.replace(/[\uE0001-\uE007F\u200B-\u200F\u202A-\u202E\u2060-\u206F\uFEFF]/g, "");
+  // Strip Docker stream-frame headers (8-byte prefix per frame)
+  text = text.replace(/^[\x00-\x0f]{8}/gm, "");
+  // Truncate to cap memory and LLM context cost
+  if (text.length > maxLength) {
+    return text.slice(0, maxLength) + `\n... [output truncated at ${maxLength} chars]`;
+  }
+  return text;
+}
+
 export function formatBytes(bytes: number): string {
   if (bytes === 0) return "0 B";
   const k = 1024;

package/src/tools/compose.ts

@@ -10,7 +10,7 @@ import {
   ComposeLogsSchema,
   ComposeRestartSchema,
 } from "../types.js";
-import { formatError } from "../docker.js";
+import { formatError, sanitizeOutput } from "../docker.js";
 
 const execAsync = promisify(execCb);
 
@@ -52,6 +52,7 @@ export function registerComposeTools(server: McpServer): void {
     "compose_up",
     "Bring up Docker Compose services from a docker-compose.yml file. Optionally build images first.",
     ComposeUpSchema.shape,
+    { idempotentHint: true, openWorldHint: false },
     async (params) => {
       try {
         const args = ["up", "-d"];
@@ -69,6 +70,7 @@ export function registerComposeTools(server: McpServer): void {
     "compose_down",
     "Tear down Docker Compose services. Optionally remove named volumes.",
     ComposeDownSchema.shape,
+    { destructiveHint: true, openWorldHint: false },
     async (params) => {
       try {
         const args = ["down"];
@@ -86,6 +88,7 @@ export function registerComposeTools(server: McpServer): void {
     "compose_ps",
     "List service states across a Docker Compose stack.",
     ComposePsSchema.shape,
+    { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
     async (params) => {
       try {
         const output = runCompose(params.path, ["ps", "--format", "json"]);
@@ -111,7 +114,8 @@ export function registerComposeTools(server: McpServer): void {
         if (params.follow) args.push("-f");
         if (params.services?.length) args.push(...params.services);
         const output = runCompose(params.path, args);
-        return { content: [{ type: "text", text: output || "No logs found." }] };
+        // Use 100KB cap for log output to keep LLM context small
+        return { content: [{ type: "text", text: sanitizeOutput(output, 100_000) || "No logs found." }] };
       } catch (error) {
         return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
       }
@@ -122,6 +126,7 @@ export function registerComposeTools(server: McpServer): void {
     "compose_restart",
     "Restart Docker Compose services. Restart specific services or the entire stack.",
     ComposeRestartSchema.shape,
+    { destructiveHint: true, idempotentHint: true, openWorldHint: false },
     async (params) => {
       try {
         const args = ["restart"];
@@ -134,4 +139,4 @@ export function registerComposeTools(server: McpServer): void {
       }
     }
   );
-}
+}

package/src/tools/container.ts

@@ -17,6 +17,7 @@ export function registerContainerTools(server: McpServer, docker: Dockerode): vo
     "list_containers",
     "List Docker containers with optional filters (state, label, name). Returns container IDs, names, images, states, ports, and labels.",
     ListContainersSchema.shape,
+    { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
     async (params) => {
       try {
         const containers = await docker.listContainers({
@@ -39,6 +40,7 @@ export function registerContainerTools(server: McpServer, docker: Dockerode): vo
     "inspect_container",
     "Get detailed configuration and state of a Docker container by ID or name.",
     InspectContainerSchema.shape,
+    { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
     async (params) => {
       try {
         const container = docker.getContainer(params.container_id);
@@ -54,6 +56,7 @@ export function registerContainerTools(server: McpServer, docker: Dockerode): vo
     "start_container",
     "Start a stopped Docker container by ID or name.",
     StartContainerSchema.shape,
+    { idempotentHint: true, openWorldHint: false },
     async (params) => {
       try {
         const container = docker.getContainer(params.container_id);
@@ -69,6 +72,7 @@ export function registerContainerTools(server: McpServer, docker: Dockerode): vo
     "stop_container",
     "Stop a running Docker container by ID or name with optional timeout.",
     StopContainerSchema.shape,
+    { destructiveHint: true, openWorldHint: false },
     async (params) => {
       try {
         const container = docker.getContainer(params.container_id);
@@ -104,6 +108,7 @@ export function registerContainerTools(server: McpServer, docker: Dockerode): vo
     "remove_container",
     "Remove a Docker container by ID or name. Use force to remove running containers.",
     RemoveContainerSchema.shape,
+    { destructiveHint: true, openWorldHint: false },
     async (params) => {
       try {
         const container = docker.getContainer(params.container_id);
@@ -119,6 +124,7 @@ export function registerContainerTools(server: McpServer, docker: Dockerode): vo
     "recreate_container",
     "Recreate a container with the same configuration (stop, remove, re-create). Useful for applying config changes.",
     RecreateContainerSchema.shape,
+    { destructiveHint: true, idempotentHint: true, openWorldHint: false },
     async (params) => {
       try {
         const container = docker.getContainer(params.container_id);
@@ -159,6 +165,7 @@ export function registerContainerTools(server: McpServer, docker: Dockerode): vo
     "run_container",
     "Create and start a new Docker container with one command. Supports image, env, ports, volumes, restart policy, and command override. Auto-pulls missing images.",
     RunContainerSchema.shape,
+    { openWorldHint: false },
     async (params) => {
       try {
         const createOpts: Dockerode.ContainerCreateOptions = {
@@ -213,4 +220,4 @@ export function registerContainerTools(server: McpServer, docker: Dockerode): vo
       }
     }
   );
-}
+}

package/src/tools/exec.ts

@@ -1,13 +1,14 @@
 import Dockerode from "dockerode";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { ExecInContainerSchema } from "../types.js";
-import { formatError } from "../docker.js";
+import { formatError, sanitizeOutput } from "../docker.js";
 
 export function registerExecTools(server: McpServer, docker: Dockerode): void {
   server.tool(
     "exec_in_container",
     "Execute a command inside a running Docker container. Returns stdout, stderr, and exit code.",
     ExecInContainerSchema.shape,
+    { openWorldHint: false },
     async (params) => {
       try {
         const container = docker.getContainer(params.container_id);
@@ -27,7 +28,7 @@ export function registerExecTools(server: McpServer, docker: Dockerode): void {
         });
 
         const inspect = await exec.inspect();
-        const cleanOutput = output.replace(/^[\x00-\x0f]{8}/gm, "");
+        const cleanOutput = sanitizeOutput(output);
 
         return {
           content: [{
@@ -45,4 +46,4 @@ export function registerExecTools(server: McpServer, docker: Dockerode): void {
       }
     }
   );
-}
+}

package/src/tools/health.ts

@@ -8,6 +8,7 @@ export function registerHealthTools(server: McpServer, docker: Dockerode): void
     "check_health",
     "Run a health probe against a container. Supports HTTP, TCP, and exec probes. Auto-detects from container HEALTHCHECK if available.",
     CheckHealthSchema.shape,
+    { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
     async (params) => {
       try {
         const container = docker.getContainer(params.container_id);
@@ -77,6 +78,7 @@ export function registerHealthTools(server: McpServer, docker: Dockerode): void
     "watch_health",
     "Poll a container's health status until it becomes healthy or times out. Useful for waiting on service startup.",
     WatchHealthSchema.shape,
+    { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
     async (params) => {
       try {
         const container = docker.getContainer(params.container_id);
@@ -130,6 +132,7 @@ export function registerHealthTools(server: McpServer, docker: Dockerode): void
     "set_restart_policy",
     "Change the restart policy of a running container without recreating it.",
     SetRestartPolicySchema.shape,
+    { idempotentHint: true, openWorldHint: false },
     async (params) => {
       try {
         const container = docker.getContainer(params.container_id);
@@ -147,4 +150,4 @@ export function registerHealthTools(server: McpServer, docker: Dockerode): void
       }
     }
   );
-}
+}

package/src/tools/image.ts

@@ -13,6 +13,7 @@ export function registerImageTools(server: McpServer, docker: Dockerode): void {
     "list_images",
     "List Docker images with optional filters. Returns image IDs, tags, sizes, and creation dates.",
     ListImagesSchema.shape,
+    { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
     async (params) => {
       try {
         const images = await docker.listImages({
@@ -31,6 +32,7 @@ export function registerImageTools(server: McpServer, docker: Dockerode): void {
     "pull_image",
     "Pull a Docker image from a registry. Returns pull progress events.",
     PullImageSchema.shape,
+    { idempotentHint: true, openWorldHint: false },
     async (params) => {
       try {
         const imageRef = params.tag ? `${params.image}:${params.tag}` : params.image;
@@ -53,6 +55,7 @@ export function registerImageTools(server: McpServer, docker: Dockerode): void {
     "build_image",
     "Build a Docker image from a Dockerfile or build context path.",
     BuildImageSchema.shape,
+    { idempotentHint: true, openWorldHint: false },
     async (params) => {
       try {
         const stream = await docker.buildImage(
@@ -79,6 +82,7 @@ export function registerImageTools(server: McpServer, docker: Dockerode): void {
     "remove_image",
     "Remove a Docker image by name or ID. Use force to remove even if tagged.",
     RemoveImageSchema.shape,
+    { destructiveHint: true, openWorldHint: false },
     async (params) => {
       try {
         const image = docker.getImage(params.image);
@@ -89,4 +93,4 @@ export function registerImageTools(server: McpServer, docker: Dockerode): void {
       }
     }
   );
-}
+}

package/src/tools/logs.ts

@@ -1,7 +1,7 @@
 import Dockerode from "dockerode";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StreamLogsSchema, ContainerStatsSchema } from "../types.js";
-import { formatError, formatBytes } from "../docker.js";
+import { formatError, formatBytes, sanitizeOutput } from "../docker.js";
 
 export function registerLogsTools(server: McpServer, docker: Dockerode): void {
   server.tool(
@@ -20,7 +20,8 @@ export function registerLogsTools(server: McpServer, docker: Dockerode): void {
           follow: false as const,
         });
         // Dockerode returns a Buffer with multiplexed stream headers
-        const output = logs.toString("utf-8").replace(/^[\x00-\x0f]{8}/gm, "");
+        // Use 100KB cap for logs to keep LLM context small
+        const output = sanitizeOutput(logs.toString("utf-8"), 100_000);
         return { content: [{ type: "text", text: output || "No logs found." }] };
       } catch (error) {
         return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
@@ -32,6 +33,7 @@ export function registerLogsTools(server: McpServer, docker: Dockerode): void {
     "container_stats",
     "Get real-time resource usage statistics for a Docker container (CPU, memory, network, I/O).",
     ContainerStatsSchema.shape,
+    { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
     async (params) => {
       try {
         const container = docker.getContainer(params.container_id);
@@ -83,4 +85,4 @@ export function registerLogsTools(server: McpServer, docker: Dockerode): void {
       }
     }
   );
-}
+}

package/src/tools/monitoring.ts

@@ -8,13 +8,15 @@ import {
   ResourceAlertCheckSchema,
   MonitorDashboardSchema,
 } from "../types.js";
+import { sanitizeOutput } from "../docker.js";
 
 export function registerMonitoringTools(server: McpServer, docker: Dockerode): void {
   // 1. fleet_status — health status of all running containers
   server.tool(
     "container_health_status",
-    "Check health status, uptime, and restart count for all running Docker containers. Returns JSON with container name, state, health probe status, and restart count.",
+    "Check health status, uptime, and restart count for all running Docker containers. Returns JSON with container name, state, health probe status (healthy/unhealthy/no-healthcheck), and restart count. Use this for a quick fleet health overview; for resource metrics use container_resource_usage instead. Returns an array of objects with name, id, state, status, health, uptime, restartCount, and image fields. Read-only and safe to call repeatedly.",
     ContainerHealthStatusSchema.shape,
+    { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
     async (params) => {
       try {
         const containers = await docker.listContainers({ all: false });
@@ -48,8 +50,9 @@ export function registerMonitoringTools(server: McpServer, docker: Dockerode): v
   // 2. fleet_stats — resource usage for all running containers
   server.tool(
     "container_resource_usage",
-    "Monitor CPU, memory, and network I/O across all running Docker containers. Returns sorted resource usage metrics with percentage breakdowns.",
+    "Monitor CPU, memory, and network I/O across all running Docker containers. Returns sorted resource usage metrics with percentage breakdowns for each container. Use container_health_status for health probes; use resource_alert_check for threshold violations. Supports sort by cpu, memory, or network. Returns array of objects with name, id, cpu_percent, memory_usage_mb, memory_percent, network_rx_mb, network_tx_mb. Read-only and safe to call repeatedly.",
     ContainerResourceUsageSchema.shape,
+    { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
     async (params) => {
       try {
         const containers = await docker.listContainers({ all: false });
@@ -100,8 +103,9 @@ export function registerMonitoringTools(server: McpServer, docker: Dockerode): v
   // 3. watch_events — stream Docker events (simplified: collect events for a duration)
   server.tool(
     "watch_events",
-    "Stream Docker container events (start, stop, die, restart, health_status) over a configurable time window. Filter by specific container or event type.",
+    "Stream Docker container events (start, stop, die, restart, health_status) over a configurable time window. Filter by specific container or event type. Use container_health_status for current state; use this tool to watch for changes over time. Returns array of event objects with type, action, container, and time fields. Returns 'No events captured in the time window.' when no events occur. Read-only and safe to call repeatedly.",
     WatchEventsSchema.shape,
+    { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
     async (params) => {
       try {
         const durationMs = (params.duration || 30) * 1000;
@@ -156,8 +160,9 @@ export function registerMonitoringTools(server: McpServer, docker: Dockerode): v
   // 4. search_logs — search logs across multiple containers
   server.tool(
     "search_logs",
-    "Search Docker container logs across multiple containers using regex pattern matching. Returns matching log lines with container name and timestamp.",
+    "Search Docker container logs across multiple containers using regex pattern matching. Use stream_logs for single-container log tailing; use this tool to search across multiple containers at once. Returns matching log lines with container name and line content. The pattern parameter accepts any valid regex; set ignore_case for case-insensitive matching. Returns 'No matches found.' when no lines match. Read-only and safe to call repeatedly.",
     SearchLogsSchema.shape,
+    { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
     async (params) => {
       try {
         const targetContainers = params.containers || [];
@@ -186,7 +191,7 @@ export function registerMonitoringTools(server: McpServer, docker: Dockerode): v
               tail: params.tail || 500,
               since: params.since ? Math.floor(new Date(params.since).getTime() / 1000) : undefined,
             });
-            const output = logStream.toString("utf-8").replace(/^[\x00-\x0f]{8}/gm, "");
+            const output = sanitizeOutput(logStream.toString("utf-8"), 100_000);
             const lines = output.split("\n");
             for (const line of lines) {
               if (regex.test(line)) {
@@ -211,8 +216,9 @@ export function registerMonitoringTools(server: McpServer, docker: Dockerode): v
   // 5. check_thresholds — check all containers against thresholds
   server.tool(
     "resource_alert_check",
-    "Alert when Docker containers exceed resource thresholds (CPU%, memory%, restart count). Returns violations with specific metrics that triggered alerts.",
+    "Check all running Docker containers against configurable CPU%, memory%, and restart count thresholds. Returns containers that violate thresholds with specific metrics that triggered alerts. Use container_resource_usage for raw metrics; use this tool for automated alerting. Default thresholds: 80% CPU, 80% memory, 5 restarts. Returns { violations: [...], checked: N } or { message: 'All containers within thresholds.', checked: N }. Read-only and safe to call repeatedly.",
     ResourceAlertCheckSchema.shape,
+    { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
     async (params) => {
       try {
         const cpuThreshold = params.cpu_percent ?? 80;
@@ -274,8 +280,9 @@ export function registerMonitoringTools(server: McpServer, docker: Dockerode): v
   // 6. monitor_dashboard — single-call fleet summary
   server.tool(
     "monitor_dashboard",
-    "Comprehensive Docker fleet dashboard in a single API call. Returns health status, top resource consumers, recent events, and threshold violations.",
+    "Comprehensive Docker fleet dashboard in a single API call. Aggregates health status of all containers, top 5 CPU consumers, recent events (last 5 minutes), and threshold violations into one response. Use individual tools (container_health_status, container_resource_usage, watch_events) for targeted queries; use this for a complete fleet overview. Returns object with summary (total, running, healthy, unhealthy), top_consumers, recent_events, and violations. Read-only and safe to call repeatedly.",
     MonitorDashboardSchema.shape,
+    { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
     async (params) => {
       try {
         const containers = await docker.listContainers({ all: false });

package/src/tools/network.ts

@@ -8,6 +8,7 @@ export function registerNetworkTools(server: McpServer, docker: Dockerode): void
     "list_networks",
     "List Docker networks with optional filter. Returns network IDs, names, drivers, and scopes.",
     ListNetworksSchema.shape,
+    { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
     async (params) => {
       try {
         const networks = await docker.listNetworks({
@@ -39,6 +40,7 @@ export function registerNetworkTools(server: McpServer, docker: Dockerode): void
     "list_volumes",
     "List Docker volumes with optional filter. Returns volume names, drivers, mount points, and labels.",
     ListVolumesSchema.shape,
+    { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
     async (params) => {
       try {
         const result = await docker.listVolumes({
@@ -57,4 +59,4 @@ export function registerNetworkTools(server: McpServer, docker: Dockerode): void
       }
     }
   );
-}
+}

package/src/types.ts

@@ -1,5 +1,11 @@
 import { z } from "zod";
 
+// Validation regexes (shared across schemas)
+const SAFE_CMD_ARG = /^[A-Za-z0-9_./:@%+=,\-]+$/;
+const SAFE_PATH = /^\/[A-Za-z0-9_./\-]+$/;
+const SAFE_ENV_KEY = /^[A-Z_][A-Z0-9_]*$/;
+const SAFE_BUILD_CONTEXT = /^\/[A-Za-z0-9_./\-]+$/;
+
 // Container lifecycle schemas
 export const ListContainersSchema = z.object({
   all: z.boolean().optional().describe("Include stopped containers (default: false)"),
@@ -59,11 +65,15 @@ export const PullImageSchema = z.object({
 });
 
 export const BuildImageSchema = z.object({
-  context: z.string().describe("Build context path or Dockerfile content"),
+  context: z.string().regex(SAFE_BUILD_CONTEXT, "Build context must be a local absolute path (no URLs, no '..')")
+    .max(4096).describe("Build context path (local absolute path only)"),
   tag: z.string().describe("Tag for the built image (e.g., 'myapp:v1')"),
-  dockerfile: z.string().optional().describe("Dockerfile name relative to context (default: 'Dockerfile')"),
-  build_args: z.record(z.string()).optional().describe("Build arguments"),
-  target: z.string().optional().describe("Target build stage"),
+  dockerfile: z.string().max(256).optional().describe("Dockerfile name relative to context (default: 'Dockerfile')"),
+  build_args: z.record(
+    z.string().regex(SAFE_ENV_KEY, "Build arg key must be POSIX-style").max(256),
+    z.string().max(4096)
+  ).optional().describe("Build arguments (keys must be POSIX-style)"),
+  target: z.string().max(256).optional().describe("Target build stage"),
 });
 
 export const RemoveImageSchema = z.object({
@@ -112,8 +122,8 @@ export const CheckHealthSchema = z.object({
 
 export const WatchHealthSchema = z.object({
   container_id: z.string().describe("Container ID or name"),
-  timeout: z.number().optional().describe("Max seconds to wait (default: 60)"),
-  interval: z.number().optional().describe("Seconds between polls (default: 5)"),
+  timeout: z.number().max(600).optional().describe("Max seconds to wait (default: 60, max: 600)"),
+  interval: z.number().max(60).optional().describe("Seconds between polls (default: 5, max: 60)"),
 });
 
 export const SetRestartPolicySchema = z.object({
@@ -125,7 +135,7 @@ export const SetRestartPolicySchema = z.object({
 // Logs schemas
 export const StreamLogsSchema = z.object({
   container_id: z.string().describe("Container ID or name"),
-  tail: z.number().optional().describe("Number of lines to show (default: 100)"),
+  tail: z.number().max(10000).optional().describe("Number of lines to show (default: 100, max: 10000)"),
   since: z.string().optional().describe("Show logs since timestamp (e.g., '2026-01-01T00:00:00Z')"),
   follow: z.boolean().optional().describe("Follow log output (default: false)"),
 });
@@ -134,12 +144,17 @@ export const ContainerStatsSchema = z.object({
   container_id: z.string().describe("Container ID or name"),
 });
 
-// Exec schema
+// Exec schema (validated per Finding 8.1 — command/working_dir/env constraints)
 export const ExecInContainerSchema = z.object({
   container_id: z.string().describe("Container ID or name"),
-  command: z.array(z.string()).describe("Command to execute"),
-  working_dir: z.string().optional().describe("Working directory inside container"),
-  env: z.record(z.string()).optional().describe("Environment variables"),
+  command: z.array(z.string().max(500).regex(SAFE_CMD_ARG, "Command arg contains disallowed characters"))
+    .min(1).max(50).describe("Command to execute (max 50 args, alphanumeric + safe chars only)"),
+  working_dir: z.string().regex(SAFE_PATH, "Working directory must be an absolute path without '..'")
+    .max(1000).optional().describe("Working directory inside container (absolute path)"),
+  env: z.record(
+    z.string().regex(SAFE_ENV_KEY, "Env key must be POSIX-style (A-Z, 0-9, _)").max(100),
+    z.string().max(1000)
+  ).optional().describe("Environment variables (keys must be POSIX-style)"),
 });
 
 // Network/Volume schemas
@@ -163,13 +178,13 @@ export const WatchEventsSchema = z.object({
   container: z.string().optional().describe("Filter by container name or ID"),
   event_type: z.enum(["start", "stop", "die", "restart", "health_status", "oom", "all"]).optional().describe("Filter by event type (default: all)"),
   since: z.string().optional().describe("Show events since timestamp (e.g., '2026-01-01T00:00:00Z')"),
-  duration: z.number().optional().describe("Max seconds to listen (default: 30)"),
+  duration: z.number().max(300).optional().describe("Max seconds to listen (default: 30, max: 300)"),
 });
 
 export const SearchLogsSchema = z.object({
-  pattern: z.string().describe("Regex or grep pattern to search for"),
-  containers: z.array(z.string()).optional().describe("Specific containers to search (default: all running)"),
-  tail: z.number().optional().describe("Max lines to scan per container (default: 500)"),
+  pattern: z.string().max(1000).describe("Regex or grep pattern to search for"),
+  containers: z.array(z.string()).max(50).optional().describe("Specific containers to search (default: all running, max: 50)"),
+  tail: z.number().max(10000).optional().describe("Max lines to scan per container (default: 500, max: 10000)"),
   since: z.string().optional().describe("Only search logs since timestamp"),
   ignore_case: z.boolean().optional().describe("Case-insensitive search (default: false)"),
 });