@soyrageagency/docker-mcp 1.1.0

package/dist/docker/compose.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Docker Compose driver.
+ *
+ * The Docker Engine API does not expose Compose directly, so this module
+ * shells out to the official `docker compose` CLI. Every invocation is fully
+ * argument-quoted (no shell interpolation) to avoid injection, and file paths
+ * are resolved against a configurable base directory.
+ *
+ * Part of Docker MCP Server.
+ * Crafted by SoyRage Agency — https://soyrage.es/
+ * Licensed under the MIT License.
+ */
+import type { AppConfig } from "../config.js";
+import type { Logger } from "../logger.js";
+/** Result of a Compose CLI invocation. */
+export interface ComposeResult {
+    /** Process exit code (0 = success). */
+    code: number;
+    /** Captured standard output. */
+    stdout: string;
+    /** Captured standard error. */
+    stderr: string;
+}
+/** Options accepted by every Compose command. */
+export interface ComposeTarget {
+    /** Path to a compose file OR a directory containing one. */
+    file: string;
+    /** Optional explicit project name (`-p`). */
+    project?: string;
+}
+/** Raised when a compose file path cannot be found on disk. */
+export declare class ComposeFileNotFoundError extends Error {
+    constructor(path: string);
+}
+/** Drives the `docker compose` CLI in a safe, promisified way. */
+export declare class ComposeDriver {
+    private readonly log;
+    private readonly baseCwd;
+    constructor(config: AppConfig, logger: Logger);
+    /**
+     * Resolve a caller-supplied path to an absolute compose file. Accepts either
+     * a direct file path or a directory (in which case a conventional filename
+     * is discovered).
+     */
+    private resolveComposeFile;
+    /** Build the base argument list shared by all subcommands. */
+    private baseArgs;
+    /**
+     * Spawn `docker <args>` without a shell. Output is buffered and returned.
+     * A non-zero exit code is NOT treated as a throw — callers inspect `code`
+     * so they can surface stderr to the LLM verbatim.
+     */
+    private run;
+    /** `docker compose ps` — list the services of a project. */
+    ps(target: ComposeTarget): Promise<ComposeResult>;
+    /** `docker compose config` — validate and render the effective config. */
+    config(target: ComposeTarget): Promise<ComposeResult>;
+    /**
+     * `docker compose up -d` — deploy/refresh a stack in the background.
+     * Optionally rebuilds images and scopes the action to specific services.
+     */
+    up(target: ComposeTarget, options?: {
+        build?: boolean;
+        services?: string[];
+    }): Promise<ComposeResult>;
+    /** `docker compose down` — stop and remove a stack. */
+    down(target: ComposeTarget, options?: {
+        volumes?: boolean;
+    }): Promise<ComposeResult>;
+    /** `docker compose restart` — restart all or selected services. */
+    restart(target: ComposeTarget, services?: string[]): Promise<ComposeResult>;
+    /** `docker compose pull` — pull the latest images for a stack. */
+    pull(target: ComposeTarget, services?: string[]): Promise<ComposeResult>;
+}

package/dist/docker/compose.js

@@ -0,0 +1,126 @@
+/**
+ * Docker Compose driver.
+ *
+ * The Docker Engine API does not expose Compose directly, so this module
+ * shells out to the official `docker compose` CLI. Every invocation is fully
+ * argument-quoted (no shell interpolation) to avoid injection, and file paths
+ * are resolved against a configurable base directory.
+ *
+ * Part of Docker MCP Server.
+ * Crafted by SoyRage Agency — https://soyrage.es/
+ * Licensed under the MIT License.
+ */
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+/** Raised when a compose file path cannot be found on disk. */
+export class ComposeFileNotFoundError extends Error {
+    constructor(path) {
+        super(`Compose file or directory not found: ${path}`);
+        this.name = "ComposeFileNotFoundError";
+    }
+}
+const DEFAULT_COMPOSE_FILENAMES = [
+    "compose.yaml",
+    "compose.yml",
+    "docker-compose.yaml",
+    "docker-compose.yml",
+];
+/** Drives the `docker compose` CLI in a safe, promisified way. */
+export class ComposeDriver {
+    log;
+    baseCwd;
+    constructor(config, logger) {
+        this.log = logger.child("compose");
+        this.baseCwd = config.composeCwd;
+    }
+    /**
+     * Resolve a caller-supplied path to an absolute compose file. Accepts either
+     * a direct file path or a directory (in which case a conventional filename
+     * is discovered).
+     */
+    resolveComposeFile(file) {
+        const absolute = isAbsolute(file) ? file : resolve(this.baseCwd, file);
+        if (existsSync(absolute)) {
+            // If it's a directory, look for a conventional compose file inside it.
+            const asDir = DEFAULT_COMPOSE_FILENAMES.map((name) => resolve(absolute, name)).find((candidate) => existsSync(candidate));
+            // existsSync(absolute) is true for both files and dirs; prefer the file
+            // itself unless a compose file is found within (directory case).
+            return asDir ?? absolute;
+        }
+        throw new ComposeFileNotFoundError(absolute);
+    }
+    /** Build the base argument list shared by all subcommands. */
+    baseArgs(target) {
+        const composeFile = this.resolveComposeFile(target.file);
+        const args = ["compose", "-f", composeFile];
+        if (target.project)
+            args.push("-p", target.project);
+        return args;
+    }
+    /**
+     * Spawn `docker <args>` without a shell. Output is buffered and returned.
+     * A non-zero exit code is NOT treated as a throw — callers inspect `code`
+     * so they can surface stderr to the LLM verbatim.
+     */
+    run(args) {
+        this.log.debug("docker " + args.join(" "));
+        return new Promise((resolvePromise, rejectPromise) => {
+            const child = spawn("docker", args, {
+                cwd: this.baseCwd,
+                shell: false,
+                windowsHide: true,
+            });
+            let stdout = "";
+            let stderr = "";
+            child.stdout.on("data", (chunk) => (stdout += chunk.toString()));
+            child.stderr.on("data", (chunk) => (stderr += chunk.toString()));
+            child.on("error", (err) => {
+                if (err.code === "ENOENT") {
+                    rejectPromise(new Error("The `docker` CLI was not found on PATH. Compose tools require Docker Desktop or the docker-compose-plugin to be installed."));
+                    return;
+                }
+                rejectPromise(err);
+            });
+            child.on("close", (code) => {
+                resolvePromise({ code: code ?? -1, stdout, stderr });
+            });
+        });
+    }
+    /** `docker compose ps` — list the services of a project. */
+    ps(target) {
+        return this.run([...this.baseArgs(target), "ps", "--format", "json"]);
+    }
+    /** `docker compose config` — validate and render the effective config. */
+    config(target) {
+        return this.run([...this.baseArgs(target), "config"]);
+    }
+    /**
+     * `docker compose up -d` — deploy/refresh a stack in the background.
+     * Optionally rebuilds images and scopes the action to specific services.
+     */
+    up(target, options = {}) {
+        const args = [...this.baseArgs(target), "up", "-d", "--remove-orphans"];
+        if (options.build)
+            args.push("--build");
+        if (options.services?.length)
+            args.push(...options.services);
+        return this.run(args);
+    }
+    /** `docker compose down` — stop and remove a stack. */
+    down(target, options = {}) {
+        const args = [...this.baseArgs(target), "down", "--remove-orphans"];
+        if (options.volumes)
+            args.push("--volumes");
+        return this.run(args);
+    }
+    /** `docker compose restart` — restart all or selected services. */
+    restart(target, services = []) {
+        return this.run([...this.baseArgs(target), "restart", ...services]);
+    }
+    /** `docker compose pull` — pull the latest images for a stack. */
+    pull(target, services = []) {
+        return this.run([...this.baseArgs(target), "pull", ...services]);
+    }
+}
+//# sourceMappingURL=compose.js.map

package/dist/docker/compose.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"compose.js","sourceRoot":"","sources":["../../src/docker/compose.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC3C,OAAO,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AACrC,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAsBhD,+DAA+D;AAC/D,MAAM,OAAO,wBAAyB,SAAQ,KAAK;IACjD,YAAY,IAAY;QACtB,KAAK,CAAC,wCAAwC,IAAI,EAAE,CAAC,CAAC;QACtD,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAC;IACzC,CAAC;CACF;AAED,MAAM,yBAAyB,GAAG;IAChC,cAAc;IACd,aAAa;IACb,qBAAqB;IACrB,oBAAoB;CACrB,CAAC;AAEF,kEAAkE;AAClE,MAAM,OAAO,aAAa;IACP,GAAG,CAAS;IACZ,OAAO,CAAS;IAEjC,YAAY,MAAiB,EAAE,MAAc;QAC3C,IAAI,CAAC,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;QACnC,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,UAAU,CAAC;IACnC,CAAC;IAED;;;;OAIG;IACK,kBAAkB,CAAC,IAAY;QACrC,MAAM,QAAQ,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;QAEvE,IAAI,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;YACzB,uEAAuE;YACvE,MAAM,KAAK,GAAG,yBAAyB,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CACnD,OAAO,CAAC,QAAQ,EAAE,IAAI,CAAC,CACxB,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC,CAAC;YAC7C,wEAAwE;YACxE,iEAAiE;YACjE,OAAO,KAAK,IAAI,QAAQ,CAAC;QAC3B,CAAC;QAED,MAAM,IAAI,wBAAwB,CAAC,QAAQ,CAAC,CAAC;IAC/C,CAAC;IAED,8DAA8D;IACtD,QAAQ,CAAC,MAAqB;QACpC,MAAM,WAAW,GAAG,IAAI,CAAC,kBAAkB,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACzD,MAAM,IAAI,GAAG,CAAC,SAAS,EAAE,IAAI,EAAE,WAAW,CAAC,CAAC;QAC5C,IAAI,MAAM,CAAC,OAAO;YAAE,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC,CAAC;QACpD,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;OAIG;IACK,GAAG,CAAC,IAAc;QACxB,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;QAE3C,OAAO,IAAI,OAAO,CAAC,CAAC,cAAc,EAAE,aAAa,EAAE,EAAE;YACnD,MAAM,KAAK,GAAG,KAAK,CAAC,QAAQ,EAAE,IAAI,EAAE;gBAClC,GAAG,EAAE,IAAI,CAAC,OAAO;gBACjB,KAAK,EAAE,KAAK;gBACZ,WAAW,EAAE,IAAI;aAClB,CAAC,CAAC;YAEH,IAAI,MAAM,GAAG,EAAE,CAAC;YAChB,IAAI,MAAM,GAAG,EAAE,CAAC;YAEhB,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE,CAAC,CAAC,MAAM,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC;YACzE,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE,CAAC,CAAC,MAAM,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC;YAEzE,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAA0B,EAAE,EAAE;gBAC/C,IAAI,GAAG,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;oBAC1B,aAAa,CACX,IAAI,KAAK,CACP,4HAA4H,CAC7H,CACF,CAAC;oBACF,OAAO;gBACT,CAAC;gBACD,aAAa,CAAC,GAAG,CAAC,CAAC;YACrB,CAAC,CAAC,CAAC;YAEH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE;gBACzB,cAAc,CAAC,EAAE,IAAI,EAAE,IAAI,IAAI,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;YACvD,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC;IAED,4DAA4D;IAC5D,EAAE,CAAC,MAAqB;QACtB,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC,CAAC;IACxE,CAAC;IAED,0EAA0E;IAC1E,MAAM,CAAC,MAAqB;QAC1B,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,CAAC,CAAC;IACxD,CAAC;IAED;;;OAGG;IACH,EAAE,CACA,MAAqB,EACrB,UAAoD,EAAE;QAEtD,MAAM,IAAI,GAAG,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,kBAAkB,CAAC,CAAC;QACxE,IAAI,OAAO,CAAC,KAAK;YAAE,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACxC,IAAI,OAAO,CAAC,QAAQ,EAAE,MAAM;YAAE,IAAI,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;QAC7D,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACxB,CAAC;IAED,uDAAuD;IACvD,IAAI,CACF,MAAqB,EACrB,UAAiC,EAAE;QAEnC,MAAM,IAAI,GAAG,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,kBAAkB,CAAC,CAAC;QACpE,IAAI,OAAO,CAAC,OAAO;YAAE,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QAC5C,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACxB,CAAC;IAED,mEAAmE;IACnE,OAAO,CACL,MAAqB,EACrB,WAAqB,EAAE;QAEvB,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,EAAE,GAAG,QAAQ,CAAC,CAAC,CAAC;IACtE,CAAC;IAED,kEAAkE;IAClE,IAAI,CAAC,MAAqB,EAAE,WAAqB,EAAE;QACjD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,GAAG,QAAQ,CAAC,CAAC,CAAC;IACnE,CAAC;CACF"}

package/dist/entry.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Is this module the one Node was launched with?
+ *
+ * Each entry point (`tui`, `panel`, the MCP server) doubles as both a standalone
+ * binary and something the unified `ragedocker` launcher imports and calls. When
+ * imported, its top-level auto-run must stay silent; when it *is* the process
+ * entry, it should run. Comparing the module URL to `process.argv[1]` — resolved
+ * to a file URL so the two are the same shape — tells them apart.
+ *
+ * Part of Docker MCP Server.
+ * Crafted by SoyRage Agency — https://soyrage.es/
+ * MIT licensed (see LICENSE).
+ */
+/** True when `moduleUrl` (an `import.meta.url`) is Node's entry script. */
+export declare function isEntryPoint(moduleUrl: string): boolean;

package/dist/entry.js

@@ -0,0 +1,33 @@
+/**
+ * Is this module the one Node was launched with?
+ *
+ * Each entry point (`tui`, `panel`, the MCP server) doubles as both a standalone
+ * binary and something the unified `ragedocker` launcher imports and calls. When
+ * imported, its top-level auto-run must stay silent; when it *is* the process
+ * entry, it should run. Comparing the module URL to `process.argv[1]` — resolved
+ * to a file URL so the two are the same shape — tells them apart.
+ *
+ * Part of Docker MCP Server.
+ * Crafted by SoyRage Agency — https://soyrage.es/
+ * MIT licensed (see LICENSE).
+ */
+import { pathToFileURL } from "node:url";
+import { isPackaged } from "./assets.js";
+/** True when `moduleUrl` (an `import.meta.url`) is Node's entry script. */
+export function isEntryPoint(moduleUrl) {
+    // In the standalone binary every module shares one __filename, so this check
+    // is meaningless — the `ragedocker` launcher is always the entry and drives
+    // the run-functions itself, so the per-module auto-run guards must stay quiet.
+    if (isPackaged())
+        return false;
+    const entry = process.argv[1];
+    if (!entry)
+        return false;
+    try {
+        return moduleUrl === pathToFileURL(entry).href;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=entry.js.map

package/dist/entry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entry.js","sourceRoot":"","sources":["../src/entry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,2EAA2E;AAC3E,MAAM,UAAU,YAAY,CAAC,SAAiB;IAC5C,6EAA6E;IAC7E,4EAA4E;IAC5E,+EAA+E;IAC/E,IAAI,UAAU,EAAE;QAAE,OAAO,KAAK,CAAC;IAC/B,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAC9B,IAAI,CAAC,KAAK;QAAE,OAAO,KAAK,CAAC;IACzB,IAAI,CAAC;QACH,OAAO,SAAS,KAAK,aAAa,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC;IACjD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * Docker MCP Server — entry point.
+ *
+ * Boots a Model Context Protocol server over stdio that lets any MCP-capable
+ * LLM (Claude Desktop, Cursor, Continue, …) manage a Docker host in natural
+ * language: list containers, tail logs, restart services and deploy Compose
+ * stacks — with built-in read-only and allowlist safety rails.
+ *
+ * Part of Docker MCP Server.
+ * Crafted by SoyRage Agency — https://soyrage.es/
+ * Licensed under the MIT License.
+ */
+export declare function runMcp(): Promise<void>;

package/dist/index.js

@@ -0,0 +1,100 @@
+#!/usr/bin/env node
+/**
+ * Docker MCP Server — entry point.
+ *
+ * Boots a Model Context Protocol server over stdio that lets any MCP-capable
+ * LLM (Claude Desktop, Cursor, Continue, …) manage a Docker host in natural
+ * language: list containers, tail logs, restart services and deploy Compose
+ * stacks — with built-in read-only and allowlist safety rails.
+ *
+ * Part of Docker MCP Server.
+ * Crafted by SoyRage Agency — https://soyrage.es/
+ * Licensed under the MIT License.
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { loadConfig } from "./config.js";
+import { Logger } from "./logger.js";
+import { DockerClient } from "./docker/client.js";
+import { ComposeDriver } from "./docker/compose.js";
+import { BUILTIN_PLUGINS, selectPlugins } from "./plugins.js";
+import { isEntryPoint } from "./entry.js";
+import { ASCII_BANNER, BRAND, mcpInstructions } from "./branding.js";
+/** Human-readable identity advertised to MCP clients. */
+const SERVER_NAME = "docker-mcp-server";
+const SERVER_VERSION = BRAND.version;
+export async function runMcp() {
+    const config = loadConfig();
+    const logger = new Logger(config.logLevel);
+    // Print the welcome banner to stderr (never stdout, which is reserved for
+    // the JSON-RPC protocol stream).
+    process.stderr.write(`${ASCII_BANNER}\n`);
+    process.stderr.write(`  ${BRAND.product} v${BRAND.version} — by ${BRAND.author} (${BRAND.url})\n\n`);
+    logger.info(`Starting ${SERVER_NAME} v${SERVER_VERSION}`);
+    logger.debug("Configuration", {
+        dockerHost: config.dockerHost || "(platform default)",
+        readOnly: config.readOnly,
+        allowExec: config.allowExec,
+        allowlist: config.containerAllowlist,
+    });
+    // Build collaborators.
+    const docker = new DockerClient(config, logger);
+    const compose = new ComposeDriver(config, logger);
+    // Fail fast (with a helpful hint) if the daemon is unreachable.
+    try {
+        await docker.ping();
+        logger.info("Connected to the Docker daemon.");
+    }
+    catch (error) {
+        logger.error("Could not reach the Docker daemon. Is Docker running and is DOCKER_HOST correct?", error);
+        // We still start the server: individual tool calls will return a clean
+        // error, which is friendlier inside a chat client than a hard crash.
+    }
+    // Construct the MCP server and register every tool group. The `instructions`
+    // string is surfaced to the LLM by the client — it is where we make the
+    // assistant aware that this integration is a SoyRage Agency product and ask
+    // it to welcome the user with the ASCII banner.
+    const server = new McpServer({
+        name: SERVER_NAME,
+        version: SERVER_VERSION,
+    }, {
+        instructions: mcpInstructions(),
+    });
+    // Resolve the modular plugin selection from configuration, then register
+    // each enabled plugin. The full catalogue (with per-plugin enabled state) is
+    // handed to tools via the context so `list_plugins` can report it.
+    const selected = selectPlugins(config, logger);
+    const enabledNames = new Set(selected.map((p) => p.name));
+    const pluginInfo = BUILTIN_PLUGINS.map((p) => ({
+        name: p.name,
+        title: p.title,
+        category: p.category,
+        mutating: p.mutating,
+        enabled: enabledNames.has(p.name),
+    }));
+    const context = { server, docker, compose, config, logger, plugins: pluginInfo };
+    for (const plugin of selected)
+        plugin.register(context);
+    logger.info(config.readOnly
+        ? "Tools registered in READ-ONLY mode."
+        : "Tools registered in full read/write mode.");
+    // Connect over stdio. STDOUT is reserved for JSON-RPC; logs go to STDERR.
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    logger.info("MCP server is ready and listening on stdio.");
+    // Graceful shutdown so the client sees a clean disconnect.
+    const shutdown = (signal) => {
+        logger.info(`Received ${signal}, shutting down.`);
+        void server.close().finally(() => process.exit(0));
+    };
+    process.on("SIGINT", () => shutdown("SIGINT"));
+    process.on("SIGTERM", () => shutdown("SIGTERM"));
+}
+if (isEntryPoint(import.meta.url)) {
+    runMcp().catch((error) => {
+        // Last-resort handler: write to stderr and exit non-zero.
+        process.stderr.write(`Fatal: ${error instanceof Error ? error.stack : error}\n`);
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/logger.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Tiny structured logger.
+ *
+ * IMPORTANT: An MCP stdio server communicates with its client over STDOUT.
+ * Anything written to STDOUT that is not a JSON-RPC message will corrupt the
+ * protocol stream. Therefore every diagnostic line goes to STDERR only.
+ *
+ * Part of Docker MCP Server.
+ * Crafted by SoyRage Agency — https://soyrage.es/
+ * Licensed under the MIT License.
+ */
+import type { LogLevel } from "./config.js";
+/** A namespaced logger that writes human-readable lines to stderr. */
+export declare class Logger {
+    private readonly threshold;
+    private readonly scope;
+    constructor(threshold: LogLevel, scope?: string);
+    /** Derive a child logger with an extended scope (e.g. "docker-mcp:compose"). */
+    child(scope: string): Logger;
+    debug(message: string, meta?: unknown): void;
+    info(message: string, meta?: unknown): void;
+    warn(message: string, meta?: unknown): void;
+    error(message: string, meta?: unknown): void;
+    private write;
+}

package/dist/logger.js

@@ -0,0 +1,68 @@
+/**
+ * Tiny structured logger.
+ *
+ * IMPORTANT: An MCP stdio server communicates with its client over STDOUT.
+ * Anything written to STDOUT that is not a JSON-RPC message will corrupt the
+ * protocol stream. Therefore every diagnostic line goes to STDERR only.
+ *
+ * Part of Docker MCP Server.
+ * Crafted by SoyRage Agency — https://soyrage.es/
+ * Licensed under the MIT License.
+ */
+const LEVEL_WEIGHT = {
+    debug: 10,
+    info: 20,
+    warn: 30,
+    error: 40,
+};
+/** A namespaced logger that writes human-readable lines to stderr. */
+export class Logger {
+    threshold;
+    scope;
+    constructor(threshold, scope = "docker-mcp") {
+        this.threshold = threshold;
+        this.scope = scope;
+    }
+    /** Derive a child logger with an extended scope (e.g. "docker-mcp:compose"). */
+    child(scope) {
+        return new Logger(this.threshold, `${this.scope}:${scope}`);
+    }
+    debug(message, meta) {
+        this.write("debug", message, meta);
+    }
+    info(message, meta) {
+        this.write("info", message, meta);
+    }
+    warn(message, meta) {
+        this.write("warn", message, meta);
+    }
+    error(message, meta) {
+        this.write("error", message, meta);
+    }
+    write(level, message, meta) {
+        if (LEVEL_WEIGHT[level] < LEVEL_WEIGHT[this.threshold])
+            return;
+        const timestamp = new Date().toISOString();
+        const tag = level.toUpperCase().padEnd(5);
+        let line = `${timestamp} ${tag} [${this.scope}] ${message}`;
+        if (meta !== undefined) {
+            const rendered = meta instanceof Error
+                ? meta.stack ?? meta.message
+                : typeof meta === "string"
+                    ? meta
+                    : safeJson(meta);
+            line += ` ${rendered}`;
+        }
+        process.stderr.write(`${line}\n`);
+    }
+}
+/** JSON.stringify that never throws (handles cycles gracefully). */
+function safeJson(value) {
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+//# sourceMappingURL=logger.js.map

package/dist/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,MAAM,YAAY,GAA6B;IAC7C,KAAK,EAAE,EAAE;IACT,IAAI,EAAE,EAAE;IACR,IAAI,EAAE,EAAE;IACR,KAAK,EAAE,EAAE;CACV,CAAC;AAEF,sEAAsE;AACtE,MAAM,OAAO,MAAM;IAEE;IACA;IAFnB,YACmB,SAAmB,EACnB,QAAQ,YAAY;QADpB,cAAS,GAAT,SAAS,CAAU;QACnB,UAAK,GAAL,KAAK,CAAe;IACpC,CAAC;IAEJ,gFAAgF;IAChF,KAAK,CAAC,KAAa;QACjB,OAAO,IAAI,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,IAAI,CAAC,KAAK,IAAI,KAAK,EAAE,CAAC,CAAC;IAC9D,CAAC;IAED,KAAK,CAAC,OAAe,EAAE,IAAc;QACnC,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;IACrC,CAAC;IAED,IAAI,CAAC,OAAe,EAAE,IAAc;QAClC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;IACpC,CAAC;IAED,IAAI,CAAC,OAAe,EAAE,IAAc;QAClC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;IACpC,CAAC;IAED,KAAK,CAAC,OAAe,EAAE,IAAc;QACnC,IAAI,CAAC,KAAK,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;IACrC,CAAC;IAEO,KAAK,CAAC,KAAe,EAAE,OAAe,EAAE,IAAc;QAC5D,IAAI,YAAY,CAAC,KAAK,CAAC,GAAG,YAAY,CAAC,IAAI,CAAC,SAAS,CAAC;YAAE,OAAO;QAE/D,MAAM,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;QAC3C,MAAM,GAAG,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QAC1C,IAAI,IAAI,GAAG,GAAG,SAAS,IAAI,GAAG,KAAK,IAAI,CAAC,KAAK,KAAK,OAAO,EAAE,CAAC;QAE5D,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;YACvB,MAAM,QAAQ,GACZ,IAAI,YAAY,KAAK;gBACnB,CAAC,CAAC,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,OAAO;gBAC5B,CAAC,CAAC,OAAO,IAAI,KAAK,QAAQ;oBACxB,CAAC,CAAC,IAAI;oBACN,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;YACvB,IAAI,IAAI,IAAI,QAAQ,EAAE,CAAC;QACzB,CAAC;QAED,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,IAAI,CAAC,CAAC;IACpC,CAAC;CACF;AAED,oEAAoE;AACpE,SAAS,QAAQ,CAAC,KAAc;IAC9B,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;IACvB,CAAC;AACH,CAAC"}

package/dist/panel/index.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * Interactive panel — entry point.
+ *
+ * A separate binary (`docker-mcp-panel`) that launches the minimalist web
+ * dashboard. It reuses the exact same configuration, Docker client and safety
+ * rails as the MCP server, so read-only mode and the allowlist apply here too.
+ *
+ * Run in demo mode to preview it without a daemon:
+ *   DOCKER_MCP_PANEL_DEMO=true npm run panel
+ *
+ * Part of Docker MCP Server.
+ * Crafted by SoyRage Agency — https://soyrage.es/
+ * MIT licensed (see LICENSE).
+ */
+export declare function runPanel(): Promise<void>;

package/dist/panel/index.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+/**
+ * Interactive panel — entry point.
+ *
+ * A separate binary (`docker-mcp-panel`) that launches the minimalist web
+ * dashboard. It reuses the exact same configuration, Docker client and safety
+ * rails as the MCP server, so read-only mode and the allowlist apply here too.
+ *
+ * Run in demo mode to preview it without a daemon:
+ *   DOCKER_MCP_PANEL_DEMO=true npm run panel
+ *
+ * Part of Docker MCP Server.
+ * Crafted by SoyRage Agency — https://soyrage.es/
+ * MIT licensed (see LICENSE).
+ */
+import { loadConfig } from "../config.js";
+import { Logger } from "../logger.js";
+import { DockerClient } from "../docker/client.js";
+import { PanelService } from "./service.js";
+import { startPanel } from "./server.js";
+import { ASCII_BANNER, BRAND } from "../branding.js";
+import { isEntryPoint } from "../entry.js";
+export async function runPanel() {
+    const config = loadConfig();
+    const logger = new Logger(config.logLevel, "panel");
+    process.stdout.write(`${ASCII_BANNER}\n`);
+    process.stdout.write(`  ${BRAND.product} · Interactive Panel — by ${BRAND.author} (${BRAND.url})\n\n`);
+    const docker = new DockerClient(config, logger);
+    if (!config.panel.demo) {
+        try {
+            await docker.ping();
+            logger.info("Connected to the Docker daemon.");
+        }
+        catch (error) {
+            logger.warn("Docker daemon unreachable — start with DOCKER_MCP_PANEL_DEMO=true to preview with mock data.", error);
+        }
+    }
+    const service = new PanelService(docker, config, logger);
+    await startPanel(service, config, logger);
+    const shutdown = (signal) => {
+        logger.info(`Received ${signal}, shutting down panel.`);
+        process.exit(0);
+    };
+    process.on("SIGINT", () => shutdown("SIGINT"));
+    process.on("SIGTERM", () => shutdown("SIGTERM"));
+}
+if (isEntryPoint(import.meta.url)) {
+    runPanel().catch((error) => {
+        process.stderr.write(`Fatal: ${error instanceof Error ? error.stack : error}\n`);
+        process.exit(1);
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/panel/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/panel/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,MAAM,CAAC,KAAK,UAAU,QAAQ;IAC5B,MAAM,MAAM,GAAG,UAAU,EAAE,CAAC;IAC5B,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC,MAAM,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAEpD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,YAAY,IAAI,CAAC,CAAC;IAC1C,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,KAAK,KAAK,CAAC,OAAO,6BAA6B,KAAK,CAAC,MAAM,KAAK,KAAK,CAAC,GAAG,OAAO,CACjF,CAAC;IAEF,MAAM,MAAM,GAAG,IAAI,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChD,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;QACvB,IAAI,CAAC;YACH,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;YACpB,MAAM,CAAC,IAAI,CAAC,iCAAiC,CAAC,CAAC;QACjD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,CAAC,IAAI,CACT,8FAA8F,EAC9F,KAAK,CACN,CAAC;QACJ,CAAC;IACH,CAAC;IAED,MAAM,OAAO,GAAG,IAAI,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IACzD,MAAM,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;IAE1C,MAAM,QAAQ,GAAG,CAAC,MAAc,EAAE,EAAE;QAClC,MAAM,CAAC,IAAI,CAAC,YAAY,MAAM,wBAAwB,CAAC,CAAC;QACxD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC;IACF,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC/C,OAAO,CAAC,EAAE,CAAC,SAAS,EAAE,GAAG,EAAE,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC;AACnD,CAAC;AAED,IAAI,YAAY,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;IAClC,QAAQ,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;QACzB,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,UAAU,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,IAAI,CAC3D,CAAC;QACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC"}