@supernova123/docker-mcp-server 0.2.2 → 0.2.4

package/dist/tools/compose.js

@@ -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);
@@ -84,7 +84,7 @@ export function registerComposeTools(server) {
             return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
         }
     });
-    server.tool("compose_logs", "Tail logs from Docker Compose services. Supports filtering by service and line count.", ComposeLogsSchema.shape, async (params) => {
+    server.tool("compose_logs", "Tail logs from one or more services in a Docker Compose stack defined by docker-compose.yml at path. Use this for multi-service log inspection; for single-container logs use stream_logs instead. The services filter limits output to named services; tail controls how many recent lines to return (default 100); follow=true streams new lines until cancelled. Returns UTF-8 log text with stream headers stripped, or 'No logs found.' when the stack has not produced output. Read-only and safe to call repeatedly. Returns an error string if path does not resolve to a Compose project.", ComposeLogsSchema.shape, { readOnlyHint: true, idempotentHint: true, openWorldHint: false }, async (params) => {
         try {
             const args = ["logs", "--tail", String(params.tail ?? 100)];
             if (params.follow)
@@ -98,7 +98,7 @@ export function registerComposeTools(server) {
             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 });
@@ -52,7 +52,7 @@ export function registerContainerTools(server, docker) {
             return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
         }
     });
-    server.tool("restart_container", "Restart a Docker container by ID or name with optional timeout.", RestartContainerSchema.shape, async (params) => {
+    server.tool("restart_container", "Restart a Docker container by ID or name with optional timeout. This tears down the running process and starts a new one — use stop_container for a graceful shutdown or remove_container to delete entirely. The timeout parameter (default 10s) controls how long to wait before force-killing. Returns a confirmation string on success. Idempotent: restarting an already-stopped container starts it again. Returns an error string if the container does not exist or is not running.", RestartContainerSchema.shape, { destructiveHint: true, idempotentHint: true, openWorldHint: false }, async (params) => {
         try {
             const container = docker.getContainer(params.container_id);
             await container.restart({ 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";
 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({

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,7 +1,7 @@
 import { StreamLogsSchema, ContainerStatsSchema } from "../types.js";
 import { formatError, formatBytes } from "../docker.js";
 export function registerLogsTools(server, docker) {
-    server.tool("stream_logs", "Get logs from a Docker container. Supports tail count, timestamp filtering, and follow mode.", StreamLogsSchema.shape, async (params) => {
+    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 {
             const container = docker.getContainer(params.container_id);
             const logs = await container.logs({
@@ -19,7 +19,7 @@ export function registerLogsTools(server, docker) {
             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,7 @@
 import { ContainerHealthStatusSchema, ContainerResourceUsageSchema, WatchEventsSchema, SearchLogsSchema, ResourceAlertCheckSchema, MonitorDashboardSchema, } from "../types.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 +29,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 +73,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 +122,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;
@@ -168,7 +168,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 +223,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supernova123/docker-mcp-server",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "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/tools/compose.ts

@@ -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"]);
@@ -102,8 +105,9 @@ export function registerComposeTools(server: McpServer): void {
 
   server.tool(
     "compose_logs",
-    "Tail logs from Docker Compose services. Supports filtering by service and line count.",
+    "Tail logs from one or more services in a Docker Compose stack defined by docker-compose.yml at path. Use this for multi-service log inspection; for single-container logs use stream_logs instead. The services filter limits output to named services; tail controls how many recent lines to return (default 100); follow=true streams new lines until cancelled. Returns UTF-8 log text with stream headers stripped, or 'No logs found.' when the stack has not produced output. Read-only and safe to call repeatedly. Returns an error string if path does not resolve to a Compose project.",
     ComposeLogsSchema.shape,
+    { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
     async (params) => {
       try {
         const args = ["logs", "--tail", String(params.tail ?? 100)];
@@ -121,6 +125,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"];
@@ -133,4 +138,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);
@@ -86,8 +90,9 @@ export function registerContainerTools(server: McpServer, docker: Dockerode): vo
 
   server.tool(
     "restart_container",
-    "Restart a Docker container by ID or name with optional timeout.",
+    "Restart a Docker container by ID or name with optional timeout. This tears down the running process and starts a new one — use stop_container for a graceful shutdown or remove_container to delete entirely. The timeout parameter (default 10s) controls how long to wait before force-killing. Returns a confirmation string on success. Idempotent: restarting an already-stopped container starts it again. Returns an error string if the container does not exist or is not running.",
     RestartContainerSchema.shape,
+    { destructiveHint: true, idempotentHint: true, openWorldHint: false },
     async (params) => {
       try {
         const container = docker.getContainer(params.container_id);
@@ -103,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);
@@ -118,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);
@@ -158,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 = {
@@ -212,4 +220,4 @@ export function registerContainerTools(server: McpServer, docker: Dockerode): vo
       }
     }
   );
-}
+}

package/src/tools/exec.ts

@@ -8,6 +8,7 @@ export function registerExecTools(server: McpServer, docker: Dockerode): void {
     "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);
@@ -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

@@ -6,8 +6,9 @@ import { formatError, formatBytes } from "../docker.js";
 export function registerLogsTools(server: McpServer, docker: Dockerode): void {
   server.tool(
     "stream_logs",
-    "Get logs from a Docker container. Supports tail count, timestamp filtering, and follow mode.",
+    "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 {
         const container = docker.getContainer(params.container_id);
@@ -31,6 +32,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);
@@ -82,4 +84,4 @@ export function registerLogsTools(server: McpServer, docker: Dockerode): void {
       }
     }
   );
-}
+}

package/src/tools/monitoring.ts

@@ -13,8 +13,9 @@ export function registerMonitoringTools(server: McpServer, docker: Dockerode): v
   // 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 +49,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 +102,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 +159,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 || [];
@@ -211,8 +215,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 +279,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/tests/container.test.ts

@@ -32,7 +32,9 @@ import { createDockerClient } from "../src/docker.js";
 function createMockServer() {
   const tools: Record<string, { description: string; handler: Function }> = {};
   return {
-    tool: (name: string, description: string, _schema: unknown, handler: Function) => {
+    tool: (name: string, description: string, _schemaOrAnnotations: unknown, _annotationsOrHandler: unknown, _maybeHandler?: Function) => {
+      // Support both 4-param (name, desc, schema, handler) and 5-param (name, desc, schema, annotations, handler)
+      const handler = typeof _annotationsOrHandler === 'function' ? _annotationsOrHandler : (_maybeHandler as Function);
       tools[name] = { description, handler };
     },
     tools,