@supernova123/docker-mcp-server 0.3.4 → 0.3.5

package/.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node-version: [18, 20, 22]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: npm
+      - run: npm ci
+      - run: npm test
+      - run: npx tsc --noEmit

package/CHANGELOG.md

@@ -1,7 +1,27 @@
 # Changelog
 
+## [0.3.5] - 2026-06-14
+
+### Added
+- `prune_containers` — Remove all stopped Docker containers with optional label filters
+- `prune_images` — Remove unused Docker images (dangling and unreferenced) with optional filters
+- `update_container` — Update container resource limits (CPU, memory, CPU shares)
+
+### Changed
+- Improved tool descriptions for Glama Quality optimization (commit 255cf60)
+- Added CI workflow (GitHub Actions, Node 18/20/22)
+- Added `relatedServers` to glama.json
+
+
 All notable changes to @supernova123/docker-mcp-server will be documented in this file.
 
+## [0.3.4] - 2026-06-14
+
+### Added
+- **copy_from_container** tool — copy files from a container to the host filesystem
+- **copy_to_container** tool — copy files from the host to a container filesystem
+- Glama "Try it now" link in README for zero-install tool testing
+
 ## [0.3.3] - 2026-06-13
 
 ### Added
@@ -101,4 +121,4 @@ All notable changes to @supernova123/docker-mcp-server will be documented in thi
 ## [0.1.0] - 2026-06-10
 
 ### Added
-- Initial release: 25 tools across container, compose, exec, health, logs, image, and network modules
+- Initial release: 25 tools across container, compose, exec, health, logs, image, and network modules

package/README.md

@@ -55,6 +55,8 @@ Here's what an agent actually does with this server during a deployment:
 
 If the health check fails at step 2, your agent catches it immediately — no 3am alerts, no user complaints. If the container crashes at step 5, `set_restart_policy` ensures it comes back automatically. The agent doesn't just deploy containers — it keeps them running.
 
+**[▶ Try it now on Glama](https://glama.ai/mcp/servers/friendlygeorge/docker-mcp-server)** — test all 31 tools in your browser, no install required.
+
 ## Quick Start
 
 One command to run:

package/dist/server.js

@@ -13,7 +13,7 @@ import { registerTransferTools } from "./tools/transfer.js";
 export function createServer(docker, options) {
     const server = new McpServer({
         name: "docker-mcp-server",
-        version: "0.3.3",
+        version: "0.3.4",
     });
     // Register all tool categories
     registerContainerTools(server, docker);

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, { idempotentHint: true, openWorldHint: false }, async (params) => {
+    server.tool("compose_up", "Bring up Docker Compose services from a docker-compose.yml file at path. Use compose_ps to check service states after bringing them up; use compose_logs to inspect output. Optionally rebuild images before starting (build=true). Returns a confirmation string listing which services were started. Idempotent: already-running services are left untouched. Returns an error string if the Compose file is missing or invalid.", ComposeUpSchema.shape, { idempotentHint: true, openWorldHint: false }, async (params) => {
         try {
             const args = ["up", "-d"];
             if (params.build)
@@ -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, { readOnlyHint: true, idempotentHint: true, openWorldHint: false }, async (params) => {
+    server.tool("compose_ps", "List service states across a Docker Compose stack defined by docker-compose.yml at path. Returns an array of services with name, state (running, exited, etc.), health status, and port mappings. Use compose_up to start services; use compose_logs to inspect output. Read-only and safe to call repeatedly. Returns an error string if the Compose file is missing.", 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);

package/dist/tools/container.js

@@ -1,4 +1,4 @@
-import { ListContainersSchema, InspectContainerSchema, StartContainerSchema, StopContainerSchema, RestartContainerSchema, RemoveContainerSchema, RecreateContainerSchema, RunContainerSchema, } from "../types.js";
+import { ListContainersSchema, InspectContainerSchema, StartContainerSchema, StopContainerSchema, RestartContainerSchema, RemoveContainerSchema, RecreateContainerSchema, RunContainerSchema, PruneContainersSchema, UpdateContainerSchema, } from "../types.js";
 import { formatContainer, formatError, withRetry } 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, { readOnlyHint: true, idempotentHint: true, openWorldHint: false }, async (params) => {
@@ -161,5 +161,90 @@ export function registerContainerTools(server, docker) {
             return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
         }
     });
+    // prune_containers — remove stopped containers
+    server.tool("prune_containers", "Remove all stopped Docker containers. Returns the number of containers removed and reclaimed disk space. This is a destructive operation — stopped containers and their non-persisted data will be deleted. Use list_containers first to see what will be removed. Useful for cleanup after deployments or when disk space is low.", PruneContainersSchema.shape, { readOnlyHint: false, idempotentHint: false, openWorldHint: false }, async (params) => {
+        try {
+            const filterObj = {};
+            if (params.filter) {
+                const parts = params.filter.split('=');
+                if (parts.length === 2) {
+                    filterObj[parts[0]] = [parts[1]];
+                }
+            }
+            const result = await withRetry(() => docker.pruneContainers({ filters: filterObj }), { label: "prune_containers" });
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            containers_deleted: (result.ContainersDeleted || []).length,
+                            space_reclaimed: result.SpaceReclaimed || 0,
+                            space_reclaimed_human: formatBytes(result.SpaceReclaimed || 0),
+                            deleted_ids: (result.ContainersDeleted || []).map((id) => id.substring(0, 12)),
+                        }, null, 2),
+                    }],
+            };
+        }
+        catch (error) {
+            return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
+        }
+    });
+    // update_container — update container resource limits
+    server.tool("update_container", "Update a Docker container's resource limits (CPU, memory, CPU shares). Requires the container to be stopped first. Returns the updated resource limits. Use this to right-size containers based on actual usage — set CPU limits to prevent runaway processes and memory limits to prevent OOM kills.", UpdateContainerSchema.shape, { readOnlyHint: false, idempotentHint: false, openWorldHint: false }, async (params) => {
+        try {
+            const updateConfig = {};
+            if (params.cpu_limit !== undefined) {
+                updateConfig.NanoCpus = Math.round(params.cpu_limit * 1e9);
+            }
+            if (params.memory_limit !== undefined) {
+                updateConfig.Memory = parseMemory(params.memory_limit);
+            }
+            if (params.cpu_shares !== undefined) {
+                updateConfig.CpuShares = params.cpu_shares;
+            }
+            if (Object.keys(updateConfig).length === 0) {
+                return { content: [{ type: "text", text: "Error: No resource limits specified. Provide at least one of: cpu_limit, memory_limit, cpu_shares." }], isError: true };
+            }
+            const container = docker.getContainer(params.container_id);
+            await withRetry(() => container.update(updateConfig), { label: "update_container" });
+            // Inspect to return current state
+            const info = await withRetry(() => container.inspect(), { label: "update_container_inspect" });
+            const hostConfig = info.HostConfig || {};
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            container: params.container_id,
+                            state: info.State?.Status,
+                            resource_limits: {
+                                cpu_limit_cores: hostConfig.NanoCpus ? hostConfig.NanoCpus / 1e9 : null,
+                                memory_limit: hostConfig.Memory || null,
+                                memory_limit_human: hostConfig.Memory ? formatBytes(hostConfig.Memory) : null,
+                                cpu_shares: hostConfig.CpuShares || null,
+                            },
+                        }, null, 2),
+                    }],
+            };
+        }
+        catch (error) {
+            return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
+        }
+    });
+}
+function formatBytes(bytes) {
+    if (bytes === 0)
+        return '0 B';
+    const k = 1024;
+    const sizes = ['B', 'KB', 'MB', 'GB', 'TB'];
+    const i = Math.floor(Math.log(bytes) / Math.log(k));
+    return `${parseFloat((bytes / Math.pow(k, i)).toFixed(1))} ${sizes[i]}`;
+}
+function parseMemory(mem) {
+    const match = mem.match(/^(\d+)(b|k|m|g|t)?$/i);
+    if (!match)
+        throw new Error(`Invalid memory format: ${mem}`);
+    const value = parseInt(match[1]);
+    const unit = (match[2] || 'b').toLowerCase();
+    const multipliers = { b: 1, k: 1024, m: 1024 ** 2, g: 1024 ** 3, t: 1024 ** 4 };
+    return value * (multipliers[unit] || 1);
 }
 //# sourceMappingURL=container.js.map

package/dist/tools/health.js

@@ -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, { idempotentHint: true, openWorldHint: false }, async (params) => {
+    server.tool("set_restart_policy", "Change the restart policy of a running container without recreating it. Use restart_container for an immediate restart; use this tool to change the policy (always, unless-stopped, on-failure, no) for future restarts. Returns a confirmation string on success. Idempotent: setting the same policy is a no-op. Returns an error string if the container does not exist.", 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,4 +1,4 @@
-import { ListImagesSchema, PullImageSchema, BuildImageSchema, RemoveImageSchema, } from "../types.js";
+import { ListImagesSchema, PullImageSchema, BuildImageSchema, RemoveImageSchema, PruneImagesSchema, } from "../types.js";
 import { formatImage, formatError, withRetry } 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, { readOnlyHint: true, idempotentHint: true, openWorldHint: false }, async (params) => {
@@ -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, { idempotentHint: true, openWorldHint: false }, async (params) => {
+    server.tool("pull_image", "Pull a Docker image from a registry by image name (e.g. nginx:latest). Use list_images to see locally available images after pulling. Returns pull progress events as text. Idempotent: pulling an already-up-to-date image is a no-op. Returns an error string if the image does not exist on the registry or the pull fails.", 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);
@@ -63,5 +63,47 @@ export function registerImageTools(server, docker) {
             return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
         }
     });
+    // prune_images — remove unused Docker images
+    server.tool("prune_images", "Remove unused Docker images (dangling and unreferenced). Returns the number of images deleted and reclaimed disk space. Only removes images not used by any container. Use list_images first to see what will be removed. Useful for reclaiming disk space after builds or when switching base images frequently.", PruneImagesSchema.shape, { readOnlyHint: false, idempotentHint: false, openWorldHint: false }, async (params) => {
+        try {
+            const filterObj = {};
+            if (params.filter) {
+                try {
+                    const parsed = JSON.parse(params.filter);
+                    Object.assign(filterObj, parsed);
+                }
+                catch {
+                    // If not JSON, try key=value format
+                    const parts = params.filter.split('=');
+                    if (parts.length === 2) {
+                        filterObj[parts[0]] = [parts[1]];
+                    }
+                }
+            }
+            const result = await withRetry(() => docker.pruneImages({ filters: filterObj }), { label: "prune_images" });
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            images_deleted: (result.ImagesDeleted || []).length,
+                            space_reclaimed: result.SpaceReclaimed || 0,
+                            space_reclaimed_human: formatBytes(result.SpaceReclaimed || 0),
+                            deleted_ids: (result.ImagesDeleted || []).map((img) => typeof img === 'string' ? img.substring(0, 19) : img.Deleted?.substring(0, 19) || 'unknown'),
+                        }, null, 2),
+                    }],
+            };
+        }
+        catch (error) {
+            return { content: [{ type: "text", text: `Error: ${formatError(error)}` }], isError: true };
+        }
+    });
+}
+function formatBytes(bytes) {
+    if (bytes === 0)
+        return '0 B';
+    const k = 1024;
+    const sizes = ['B', 'KB', 'MB', 'GB', 'TB'];
+    const i = Math.floor(Math.log(bytes) / Math.log(k));
+    return `${parseFloat((bytes / Math.pow(k, i)).toFixed(1))} ${sizes[i]}`;
 }
 //# sourceMappingURL=image.js.map

package/dist/types.d.ts

@@ -346,6 +346,36 @@ export declare const PruneVolumesSchema: z.ZodObject<{
 }, {
     filter?: string | undefined;
 }>;
+export declare const PruneContainersSchema: z.ZodObject<{
+    filter: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    filter?: string | undefined;
+}, {
+    filter?: string | undefined;
+}>;
+export declare const PruneImagesSchema: z.ZodObject<{
+    filter: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    filter?: string | undefined;
+}, {
+    filter?: string | undefined;
+}>;
+export declare const UpdateContainerSchema: z.ZodObject<{
+    container_id: z.ZodString;
+    cpu_limit: z.ZodOptional<z.ZodNumber>;
+    memory_limit: z.ZodOptional<z.ZodString>;
+    cpu_shares: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    container_id: string;
+    cpu_limit?: number | undefined;
+    memory_limit?: string | undefined;
+    cpu_shares?: number | undefined;
+}, {
+    container_id: string;
+    cpu_limit?: number | undefined;
+    memory_limit?: string | undefined;
+    cpu_shares?: number | undefined;
+}>;
 export declare const ContainerHealthStatusSchema: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
 export declare const ContainerResourceUsageSchema: z.ZodObject<{
     sort_by: z.ZodOptional<z.ZodEnum<["cpu", "memory", "network"]>>;

package/dist/types.js

@@ -149,6 +149,18 @@ export const RemoveVolumeSchema = z.object({
 export const PruneVolumesSchema = z.object({
     filter: z.string().optional().describe("Filter by label (e.g., 'label=key=value')"),
 });
+export const PruneContainersSchema = z.object({
+    filter: z.string().optional().describe("Filter by label (e.g., 'label=key=value')"),
+});
+export const PruneImagesSchema = z.object({
+    filter: z.string().optional().describe('Docker filters JSON (e.g. "dangling=true")'),
+});
+export const UpdateContainerSchema = z.object({
+    container_id: z.string().describe('Container ID or name'),
+    cpu_limit: z.number().optional().describe('CPU limit in cores (e.g. 1.5 for 1.5 CPUs)'),
+    memory_limit: z.string().optional().describe('Memory limit (e.g. "512m", "1g", "2048m")'),
+    cpu_shares: z.number().optional().describe('CPU shares (relative weight, 0-1024)'),
+});
 // Monitoring schemas (v0.2.0)
 export const ContainerHealthStatusSchema = z.object({});
 export const ContainerResourceUsageSchema = z.object({

package/glama.json

@@ -1,12 +1,35 @@
 {
   "$schema": "https://glama.ai/schemas/glama.json",
-  "maintainers": ["friendlygeorge"],
+  "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"],
+  "description": "31 tools for AI agent Docker management \u2014 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"],
+  "categories": [
+    "virtualization",
+    "developer-tools"
+  ],
   "language": "TypeScript",
-  "runtime": "node"
+  "runtime": "node",
+  "relatedServers": [
+    "https://github.com/friendlygeorge/resend-mcp-server",
+    "https://github.com/friendlygeorge/defillama-mcp-server",
+    "https://github.com/friendlygeorge/coingecko-mcp-server",
+    "https://github.com/friendlygeorge/etherscan-mcp-server",
+    "https://github.com/friendlygeorge/jobber-mcp-server"
+  ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supernova123/docker-mcp-server",
-  "version": "0.3.4",
+  "version": "0.3.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",
@@ -13,7 +13,10 @@
     "start": "node dist/index.js",
     "dev": "tsc && node dist/index.js",
     "test": "vitest run",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "cf:dev": "wrangler dev src/cf-worker/index.ts",
+    "cf:deploy": "wrangler deploy src/cf-worker/index.ts",
+    "cf:typecheck": "tsc --noEmit src/cf-worker/*.ts"
   },
   "keywords": [
     "mcp",
@@ -60,9 +63,11 @@
     "zod": "^3.24.0"
   },
   "devDependencies": {
+    "@cloudflare/workers-types": "^4.20260613.1",
     "@types/dockerode": "^3.3.31",
     "@types/node": "^22.0.0",
     "typescript": "^5.7.0",
-    "vitest": "^3.1.0"
+    "vitest": "^3.1.0",
+    "wrangler": "^4.100.0"
   }
-}
+}

package/src/cf-worker/README.md

@@ -0,0 +1,73 @@
+# Docker MCP — Cloudflare Workers Hosted (MCPaaS)
+
+Hosted version of Docker MCP server deployed on Cloudflare Workers. Users connect their Docker daemon via Cloudflare Tunnel; Nova runs the edge.
+
+## Architecture
+
+```
+Client (Claude/Cursor/Agent)
+  → Routing Worker (auth, CORS, rate limiting)
+    → McpAgentDO (per-user Durable Object: tool dispatch)
+      → User's Docker daemon via Cloudflare Tunnel
+```
+
+## Tiers
+
+| Tier | Price | Tools | Rate Limit |
+|------|-------|-------|------------|
+| Free | $0 | Read-only (10 tools) | 50 calls/day |
+| Standard | $19/mo | Full access (17 tools) | 500 calls/day |
+
+## Setup (Deploy)
+
+```bash
+cd /home/nova/docker-mcp-server
+
+# 1. Authenticate with Cloudflare
+wrangler login
+
+# 2. Create KV namespace for API keys
+wrangler kv:namespace create API_KEYS
+# Copy the namespace ID into wrangler.jsonc
+
+# 3. Deploy
+wrangler deploy
+
+# 4. (Future) Add Stripe for billing
+wrangler secret put STRIPE_KEY
+```
+
+## Setup (User)
+
+Users run Docker MCP locally + expose their Docker daemon:
+
+```bash
+# Install and run Docker MCP server
+npx @supernova123/docker-mcp-server
+
+# Expose Docker daemon via Cloudflare Tunnel
+cloudflared tunnel --url http://localhost:2375
+```
+
+Then configure their MCP client with the hosted Worker URL + API key.
+
+## Files
+
+| File | Purpose |
+|------|---------|
+| `index.ts` | Routing Worker — auth via KV, CORS, DO routing |
+| `mcp-agent.ts` | McpAgent Durable Object — 17 tools, per-user rate limits, tunnel proxy |
+| `types.ts` | Type definitions: Env, ApiKeyRecord, UserState |
+| `wrangler.jsonc` | Worker config: DO binding, KV binding, nodejs_compat |
+
+## Tools (17)
+
+`list_containers`, `inspect_container`, `start_container`, `stop_container`, `restart_container`, `remove_container`, `create_container`, `compose_up`, `compose_down`, `compose_ps`, `compose_logs`, `fleet_status`, `search_logs`, `watch_events`, `list_images`, `pull_image`, `list_networks`, `list_volumes`
+
+## Status
+
+- ✅ TypeScript compiles clean (both main and CF tsconfigs)
+- ✅ wrangler deploy --dry-run passes (815 KiB bundle)
+- ⏳ Needs Cloudflare account to deploy
+- ⏳ KV namespace creation pending
+- ⏳ Stripe/x402 integration for billing (Phase 4)