@soyrageagency/docker-mcp 1.1.0

package/dist/utils/format.js

@@ -0,0 +1,69 @@
+/**
+ * Presentation helpers.
+ *
+ * Tools return human-readable text that an LLM can quote back to the user, so
+ * these helpers turn raw Docker payloads into compact, aligned tables and
+ * friendly units (bytes → "1.4 GB", uptime → "3 days ago").
+ *
+ * Part of Docker MCP Server.
+ * Crafted by SoyRage Agency — https://soyrage.es/
+ * Licensed under the MIT License.
+ */
+/** Render a value as a human-readable byte size (SI-ish, base 1024). */
+export function formatBytes(bytes) {
+    if (!Number.isFinite(bytes) || bytes <= 0)
+        return "0 B";
+    const units = ["B", "KB", "MB", "GB", "TB", "PB"];
+    const exponent = Math.min(Math.floor(Math.log(bytes) / Math.log(1024)), units.length - 1);
+    const value = bytes / Math.pow(1024, exponent);
+    const decimals = exponent === 0 ? 0 : value >= 100 ? 0 : 1;
+    return `${value.toFixed(decimals)} ${units[exponent]}`;
+}
+/** Turn a Unix timestamp (seconds) into a relative "x ago" string. */
+export function formatRelativeTime(unixSeconds) {
+    if (!unixSeconds)
+        return "unknown";
+    const deltaMs = Date.now() - unixSeconds * 1000;
+    const seconds = Math.round(deltaMs / 1000);
+    if (seconds < 60)
+        return `${seconds}s ago`;
+    const minutes = Math.round(seconds / 60);
+    if (minutes < 60)
+        return `${minutes}m ago`;
+    const hours = Math.round(minutes / 60);
+    if (hours < 24)
+        return `${hours}h ago`;
+    const days = Math.round(hours / 24);
+    if (days < 30)
+        return `${days}d ago`;
+    const months = Math.round(days / 30);
+    if (months < 12)
+        return `${months}mo ago`;
+    return `${Math.round(months / 12)}y ago`;
+}
+/** Truncate a string to `max` characters with an ellipsis. */
+export function truncate(value, max) {
+    if (value.length <= max)
+        return value;
+    return `${value.slice(0, Math.max(0, max - 1))}…`;
+}
+/**
+ * Render a fixed-width, left-aligned ASCII table. Empty tables render a short
+ * placeholder so the model gets a clear "nothing here" signal.
+ */
+export function renderTable(headers, rows) {
+    if (rows.length === 0)
+        return "(no results)";
+    const widths = headers.map((header, columnIndex) => Math.max(header.length, ...rows.map((row) => (row[columnIndex] ?? "").length)));
+    const pad = (cells) => cells
+        .map((cell, index) => (cell ?? "").padEnd(widths[index]))
+        .join("  ")
+        .trimEnd();
+    const separator = widths.map((width) => "-".repeat(width)).join("  ");
+    return [pad(headers), separator, ...rows.map((row) => pad(row))].join("\n");
+}
+/** Pretty-print an object as fenced JSON for the model to read. */
+export function asJsonBlock(value) {
+    return "```json\n" + JSON.stringify(value, null, 2) + "\n```";
+}
+//# sourceMappingURL=format.js.map

package/dist/utils/format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.js","sourceRoot":"","sources":["../../src/utils/format.ts"],"names":[],"mappings":"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"}

package/dist/utils/result.d.ts

@@ -0,0 +1,35 @@
+/**
+ * MCP tool-result helpers.
+ *
+ * Every tool returns the same `{ content: [...] }` shape. These wrappers keep
+ * call sites terse and guarantee consistent error surfacing: failures come
+ * back as `isError: true` text so the LLM can react instead of the transport
+ * throwing.
+ *
+ * Part of Docker MCP Server.
+ * Crafted by SoyRage Agency — https://soyrage.es/
+ * Licensed under the MIT License.
+ */
+/**
+ * The subset of the MCP tool-result shape this server produces.
+ *
+ * The index signature keeps us structurally compatible with the SDK's
+ * `CallToolResult` type (which allows arbitrary extra fields via `_meta`).
+ */
+export interface ToolResult {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError?: boolean;
+    [key: string]: unknown;
+}
+/** Build a successful text result. */
+export declare function ok(text: string): ToolResult;
+/** Build an error text result the LLM can read and recover from. */
+export declare function fail(message: string): ToolResult;
+/**
+ * Wrap an async tool handler so any thrown error becomes a clean `fail(...)`
+ * result. This keeps individual handlers focused on the happy path.
+ */
+export declare function guard(handler: () => Promise<ToolResult>): Promise<ToolResult>;

package/dist/utils/result.js

@@ -0,0 +1,31 @@
+/**
+ * MCP tool-result helpers.
+ *
+ * Every tool returns the same `{ content: [...] }` shape. These wrappers keep
+ * call sites terse and guarantee consistent error surfacing: failures come
+ * back as `isError: true` text so the LLM can react instead of the transport
+ * throwing.
+ *
+ * Part of Docker MCP Server.
+ * Crafted by SoyRage Agency — https://soyrage.es/
+ * Licensed under the MIT License.
+ */
+/** Build a successful text result. */
+export function ok(text) {
+    return { content: [{ type: "text", text }] };
+}
+/** Build an error text result the LLM can read and recover from. */
+export function fail(message) {
+    return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
+}
+/**
+ * Wrap an async tool handler so any thrown error becomes a clean `fail(...)`
+ * result. This keeps individual handlers focused on the happy path.
+ */
+export function guard(handler) {
+    return handler().catch((error) => {
+        const message = error instanceof Error ? error.message : String(error ?? "unknown error");
+        return fail(message);
+    });
+}
+//# sourceMappingURL=result.js.map

package/dist/utils/result.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.js","sourceRoot":"","sources":["../../src/utils/result.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAcH,sCAAsC;AACtC,MAAM,UAAU,EAAE,CAAC,IAAY;IAC7B,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;AAC/C,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,IAAI,CAAC,OAAe;IAClC,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,OAAO,EAAE,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AACnF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,KAAK,CACnB,OAAkC;IAElC,OAAO,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;QACxC,MAAM,OAAO,GACX,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,IAAI,eAAe,CAAC,CAAC;QAC5E,OAAO,IAAI,CAAC,OAAO,CAAC,CAAC;IACvB,CAAC,CAAC,CAAC;AACL,CAAC"}

package/package.json

@@ -0,0 +1,90 @@
+{
+  "name": "@soyrageagency/docker-mcp",
+  "version": "1.1.0",
+  "description": "Chat with your Docker host. A Model Context Protocol (MCP) server that lets any LLM list containers, read logs, manage lifecycle and deploy Compose stacks — safely. Built by SoyRage Agency.",
+  "type": "module",
+  "license": "MIT",
+  "mcpName": "io.github.soyrageagency/docker-mcp-server",
+  "author": "SoyRage Agency (https://soyrage.es/)",
+  "homepage": "https://soyrage.es/tools/docker-mcp",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/soyrageagency/docker-mcp-server.git"
+  },
+  "bugs": {
+    "url": "https://github.com/soyrageagency/docker-mcp-server/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "docker",
+    "docker-compose",
+    "devops",
+    "llm",
+    "ai",
+    "claude",
+    "self-hosted",
+    "containers"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "docker-mcp": "dist/index.js",
+    "ragedocker": "dist/ragedocker.js",
+    "docker-mcp-server": "dist/index.js",
+    "docker-mcp-panel": "dist/panel/index.js",
+    "docker-mcp-tui": "dist/tui/index.js",
+    "docker-mcp-install": "scripts/install.mjs"
+  },
+  "funding": {
+    "type": "paypal",
+    "url": "https://www.paypal.com/paypalme/soyrageagency"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "scripts/install.mjs",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc && node scripts/copy-public.mjs",
+    "prepublishOnly": "npm run build",
+    "dev": "tsx watch src/index.ts",
+    "start": "node dist/index.js",
+    "panel": "node dist/panel/index.js",
+    "panel:dev": "tsx watch src/panel/index.ts",
+    "panel:demo": "node -e \"process.env.DOCKER_MCP_PANEL_DEMO='true';import('./dist/panel/index.js')\"",
+    "tui": "node dist/tui/index.js",
+    "tui:dev": "tsx src/tui/index.ts",
+    "tui:demo": "node -e \"process.env.DOCKER_MCP_PANEL_DEMO='true';import('./dist/tui/index.js')\"",
+    "ragedocker": "node dist/ragedocker.js",
+    "ia": "node dist/ragedocker.js ia",
+    "doctor": "node dist/ragedocker.js doctor",
+    "build:sea": "node scripts/build-sea.mjs",
+    "inspect": "npx @modelcontextprotocol/inspector node dist/index.js",
+    "setup": "npm run build && node scripts/install.mjs",
+    "install:claude": "node scripts/install.mjs",
+    "shots": "node scripts/shots.mjs",
+    "typecheck": "tsc --noEmit",
+    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\""
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "dockerode": "^4.0.2",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/dockerode": "^3.3.31",
+    "@types/node": "^20.14.0",
+    "esbuild": "^0.28.1",
+    "playwright": "^1.61.1",
+    "postject": "^1.0.0-alpha.6",
+    "tsx": "^4.16.0",
+    "typescript": "^5.5.0"
+  }
+}

package/scripts/install.mjs

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+/**
+ * One-command installer / configurator for beginners.
+ *
+ * Registers this Docker MCP Server in your AI client's config (Claude Desktop
+ * by default) with the correct absolute path — no manual JSON editing. It
+ * builds the project first if needed, backs up any existing config, and MERGES
+ * the entry so your other MCP servers are preserved.
+ *
+ *   node scripts/install.mjs                 # configure Claude Desktop
+ *   node scripts/install.mjs --client claude # (same)
+ *   node scripts/install.mjs --print         # just print the JSON snippet
+ *
+ * Crafted by SoyRage Agency — https://soyrage.es/  ·  https://www.paypal.com/paypalme/soyrageagency
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync, copyFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { homedir, platform } from "node:os";
+import { spawnSync } from "node:child_process";
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const DIST = join(ROOT, "dist", "index.js");
+const argv = process.argv.slice(2);
+const has = (flag) => argv.includes(flag);
+
+const c = {
+  reset: "\x1b[0m", dim: "\x1b[2m", bold: "\x1b[1m",
+  blue: "\x1b[38;5;39m", green: "\x1b[32m", yellow: "\x1b[33m", red: "\x1b[31m",
+};
+const say = (s) => process.stdout.write(s + "\n");
+const ok = (s) => say(`${c.green}✓${c.reset} ${s}`);
+const warn = (s) => say(`${c.yellow}!${c.reset} ${s}`);
+
+say("");
+say(`${c.blue}${c.bold}  Docker MCP Server — installer${c.reset}  ${c.dim}by SoyRage Agency${c.reset}`);
+say(`${c.dim}  https://soyrage.es/${c.reset}`);
+say("");
+
+// 1) Ensure the project is built.
+if (!existsSync(DIST)) {
+  warn("Build output not found — building now (npm install && npm run build)…");
+  const npm = platform() === "win32" ? "npm.cmd" : "npm";
+  if (!existsSync(join(ROOT, "node_modules"))) run(npm, ["install"]);
+  run(npm, ["run", "build"]);
+}
+if (!existsSync(DIST)) fail("Build failed: dist/index.js is still missing.");
+ok(`Server built at ${c.dim}${DIST}${c.reset}`);
+
+// 2) The MCP server entry we want to install.
+const entry = {
+  command: "node",
+  args: [DIST],
+  env: {
+    DOCKER_MCP_READONLY: "false",
+    DOCKER_MCP_ALLOW_EXEC: "false",
+    DOCKER_MCP_DEFAULT_LOG_TAIL: "200",
+  },
+};
+
+if (has("--print")) {
+  say("");
+  say(JSON.stringify({ mcpServers: { docker: entry } }, null, 2));
+  say("");
+  process.exit(0);
+}
+
+// 3) Locate the Claude Desktop config for this OS.
+const configPath = claudeConfigPath();
+if (!configPath) fail("Unsupported platform for auto-config. Use --print and paste it manually.");
+say(`${c.dim}Target config:${c.reset} ${configPath}`);
+
+// 4) Merge & write (with a backup).
+let config = {};
+if (existsSync(configPath)) {
+  try {
+    config = JSON.parse(readFileSync(configPath, "utf8"));
+  } catch {
+    warn("Existing config is not valid JSON; a fresh one will be written (old kept as .bak).");
+  }
+  copyFileSync(configPath, configPath + ".bak");
+  ok(`Backed up existing config → ${c.dim}${configPath}.bak${c.reset}`);
+} else {
+  mkdirSync(dirname(configPath), { recursive: true });
+  warn("No existing config found — creating a new one. (Is Claude Desktop installed?)");
+}
+
+config.mcpServers = config.mcpServers || {};
+const existed = Boolean(config.mcpServers.docker);
+config.mcpServers.docker = entry;
+writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
+ok(`${existed ? "Updated" : "Added"} the "docker" MCP server in your Claude config.`);
+
+// 5) Done — next steps + a friendly nudge.
+say("");
+say(`${c.green}${c.bold}  All set!${c.reset}`);
+say(`  1. Fully ${c.bold}restart Claude Desktop${c.reset} (quit from the tray, not just the window).`);
+say(`  2. Ask it: ${c.blue}"What Docker containers are running?"${c.reset}`);
+say("");
+say(`  ${c.dim}Optional visual dashboard:${c.reset} ${c.bold}npm run panel${c.reset}  →  http://127.0.0.1:4600`);
+say(`  ${c.dim}Terminal UI:${c.reset}              ${c.bold}npm run tui${c.reset}`);
+say("");
+say(`  ${c.yellow}Enjoying it?${c.reset} Support development: ${c.blue}https://www.paypal.com/paypalme/soyrageagency${c.reset}`);
+say(`  ${c.yellow}★${c.reset} And a star helps a lot: ${c.blue}https://github.com/soyrageagency/docker-mcp-server${c.reset}`);
+say("");
+
+// ---- helpers --------------------------------------------------------------
+
+function claudeConfigPath() {
+  const home = homedir();
+  switch (platform()) {
+    case "win32":
+      return join(process.env.APPDATA || join(home, "AppData", "Roaming"), "Claude", "claude_desktop_config.json");
+    case "darwin":
+      return join(home, "Library", "Application Support", "Claude", "claude_desktop_config.json");
+    case "linux":
+      return join(process.env.XDG_CONFIG_HOME || join(home, ".config"), "Claude", "claude_desktop_config.json");
+    default:
+      return null;
+  }
+}
+
+function run(cmd, args) {
+  const r = spawnSync(cmd, args, { cwd: ROOT, stdio: "inherit" });
+  if (r.status !== 0) fail(`Command failed: ${cmd} ${args.join(" ")}`);
+}
+
+function fail(msg) {
+  say(`${c.red}✗ ${msg}${c.reset}`);
+  process.exit(1);
+}