@mseep/mcp-swarmpit 0.1.0

package/src/test/sanitize.test.ts

@@ -0,0 +1,234 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import {
+  sanitizeService,
+  sanitizeServices,
+  sanitizeComposeYaml,
+  resolveComposeEnvRefs,
+  restoreRedactedValues,
+  setExtraRedactPatterns,
+} from "../sanitize.js";
+import type { SwarmpitService } from "../types.js";
+
+function makeService(overrides: Partial<SwarmpitService> = {}): SwarmpitService {
+  return {
+    id: "test-id",
+    version: 1,
+    createdAt: "2024-01-01T00:00:00Z",
+    updatedAt: "2024-01-01T00:00:00Z",
+    repository: { name: "test", tag: "latest", image: "test:latest", imageDigest: "sha256:abc" },
+    serviceName: "test_service",
+    mode: "replicated",
+    replicas: 1,
+    state: "running",
+    status: { tasks: { running: 1, total: 1 }, update: "", message: "" },
+    ports: [],
+    mounts: [],
+    networks: [],
+    secrets: [],
+    configs: [],
+    variables: [],
+    labels: [],
+    command: null,
+    stack: "test",
+    resources: { reservation: { cpu: 0, memory: 0 }, limit: { cpu: 0, memory: 0 } },
+    ...overrides,
+  };
+}
+
+describe("sanitizeService", () => {
+  it("redacts all env vars when redactAll=true", () => {
+    const service = makeService({
+      variables: [
+        { name: "NODE_ENV", value: "production" },
+        { name: "DB_PASS", value: "secret123" },
+      ],
+    });
+    const result = sanitizeService(service, true);
+    assert.equal(result.variables[0].value, "[REDACTED]");
+    assert.equal(result.variables[1].value, "[REDACTED]");
+  });
+
+  it("only redacts sensitive vars when redactAll=false", () => {
+    const service = makeService({
+      variables: [
+        { name: "NODE_ENV", value: "production" },
+        { name: "DB_PASS", value: "secret123" },
+        { name: "API_KEY", value: "key123" },
+        { name: "LOG_LEVEL", value: "debug" },
+        { name: "SECRET_VALUE", value: "hidden" },
+        { name: "AUTH_HEADER", value: "bearer xyz" },
+      ],
+    });
+    const result = sanitizeService(service, false);
+    assert.equal(result.variables[0].value, "production");  // NODE_ENV — not sensitive
+    assert.equal(result.variables[1].value, "[REDACTED]");  // DB_PASS — matches "pass"
+    assert.equal(result.variables[2].value, "[REDACTED]");  // API_KEY — matches "key"
+    assert.equal(result.variables[3].value, "debug");        // LOG_LEVEL — not sensitive
+    assert.equal(result.variables[4].value, "[REDACTED]");  // SECRET_VALUE — matches "secret"
+    assert.equal(result.variables[5].value, "[REDACTED]");  // AUTH_HEADER — matches "auth"
+  });
+
+  it("redacts extra custom patterns", () => {
+    setExtraRedactPatterns(["GRAFANA", "RPC"]);
+    const service = makeService({
+      variables: [
+        { name: "GRAFANA", value: "https://grafana.example.com" },
+        { name: "RPC_URL", value: "ws://node:9999" },
+        { name: "LOG_LEVEL", value: "debug" },
+      ],
+    });
+    const result = sanitizeService(service, false);
+    assert.equal(result.variables[0].value, "[REDACTED]");  // GRAFANA — custom pattern
+    assert.equal(result.variables[1].value, "[REDACTED]");  // RPC_URL — custom pattern
+    assert.equal(result.variables[2].value, "debug");        // LOG_LEVEL — no match
+    setExtraRedactPatterns([]);  // clean up
+  });
+
+  it("preserves env var names", () => {
+    const service = makeService({
+      variables: [{ name: "PASSWORD", value: "secret" }],
+    });
+    const result = sanitizeService(service, true);
+    assert.equal(result.variables[0].name, "PASSWORD");
+  });
+
+  it("does not modify command args", () => {
+    const service = makeService({
+      command: ["--db", "postgres://user:secret@host:5432/db"],
+    });
+    const result = sanitizeService(service, true);
+    assert.deepEqual(result.command, ["--db", "postgres://user:secret@host:5432/db"]);
+  });
+
+  it("strips secret data fields but keeps references", () => {
+    const service = makeService({
+      secrets: [{ id: "s1", secretName: "db_pass", secretTarget: "/run/secrets/db_pass" }],
+      configs: [{ id: "c1", configName: "app_config", configTarget: "/etc/app.conf" }],
+    });
+    const result = sanitizeService(service);
+    assert.deepEqual(result.secrets, [{ id: "s1", secretName: "db_pass", secretTarget: "/run/secrets/db_pass" }]);
+    assert.deepEqual(result.configs, [{ id: "c1", configName: "app_config", configTarget: "/etc/app.conf" }]);
+  });
+});
+
+describe("sanitizeServices", () => {
+  it("sanitizes an array of services", () => {
+    const services = [
+      makeService({ variables: [{ name: "PASSWORD", value: "s1" }] }),
+      makeService({ variables: [{ name: "TOKEN", value: "s2" }] }),
+    ];
+    const result = sanitizeServices(services, false);
+    assert.equal(result[0].variables[0].value, "[REDACTED]");
+    assert.equal(result[1].variables[0].value, "[REDACTED]");
+  });
+});
+
+describe("sanitizeComposeYaml", () => {
+  it("redacts all env vars in key-value form when redactAll=true", () => {
+    const yaml = `services:
+  app:
+    environment:
+      NODE_ENV: production
+      DB_HOST: localhost`;
+    const result = sanitizeComposeYaml(yaml, true);
+    assert.ok(result.includes("NODE_ENV: [REDACTED]"));
+    assert.ok(result.includes("DB_HOST: [REDACTED]"));
+  });
+
+  it("only redacts sensitive vars when redactAll=false", () => {
+    const yaml = `services:
+  app:
+    environment:
+      NODE_ENV: production
+      DB_PASSWORD: secret123`;
+    const result = sanitizeComposeYaml(yaml, false);
+    assert.ok(result.includes("NODE_ENV: production"));
+    assert.ok(result.includes("DB_PASSWORD: [REDACTED]"));
+  });
+
+  it("redacts list form env vars", () => {
+    const yaml = `services:
+  app:
+    environment:
+      - NODE_ENV=production
+      - DB_PASSWORD=secret123`;
+    const result = sanitizeComposeYaml(yaml, false);
+    assert.ok(result.includes("- NODE_ENV=production"));
+    assert.ok(result.includes("- DB_PASSWORD=[REDACTED]"));
+  });
+
+  it("does not redact YAML references or objects", () => {
+    const yaml = `services:
+  app:
+    environment:
+      CONFIG: &default_config
+      REF: *default_config`;
+    const result = sanitizeComposeYaml(yaml, true);
+    assert.ok(result.includes("CONFIG: &default_config"));
+    assert.ok(result.includes("REF: *default_config"));
+  });
+
+  it("does not modify commands in compose", () => {
+    const yaml = `services:
+  app:
+    command: ["--db", "postgres://user:secret@host/db"]`;
+    const result = sanitizeComposeYaml(yaml, true);
+    assert.ok(result.includes("postgres://user:secret@host/db"));
+  });
+});
+
+describe("resolveComposeEnvRefs", () => {
+  it("resolves $env:VAR_NAME in key-value form", () => {
+    process.env.TEST_SECRET = "resolved-value";
+    const yaml = `    DB_PASSWORD: $env:TEST_SECRET`;
+    const result = resolveComposeEnvRefs(yaml);
+    assert.ok(result.includes("DB_PASSWORD: resolved-value"));
+    delete process.env.TEST_SECRET;
+  });
+
+  it("resolves $env:VAR_NAME in list form", () => {
+    process.env.TEST_SECRET = "resolved-value";
+    const yaml = `      - DB_PASSWORD=$env:TEST_SECRET`;
+    const result = resolveComposeEnvRefs(yaml);
+    assert.ok(result.includes("- DB_PASSWORD=resolved-value"));
+    delete process.env.TEST_SECRET;
+  });
+
+  it("passes through plain values unchanged", () => {
+    const yaml = `    NODE_ENV: production`;
+    const result = resolveComposeEnvRefs(yaml);
+    assert.equal(result, yaml);
+  });
+
+  it("throws on missing env var", () => {
+    delete process.env.NONEXISTENT_VAR;
+    const yaml = `    DB_PASSWORD: $env:NONEXISTENT_VAR`;
+    assert.throws(() => resolveComposeEnvRefs(yaml), /NONEXISTENT_VAR/);
+  });
+});
+
+describe("restoreRedactedValues", () => {
+  it("restores [REDACTED] from original in key-value form", () => {
+    const edited = `    DB_PASSWORD: [REDACTED]\n    NODE_ENV: staging`;
+    const original = `    DB_PASSWORD: secret123\n    NODE_ENV: production`;
+    const result = restoreRedactedValues(edited, original);
+    assert.ok(result.includes("DB_PASSWORD: secret123"));
+    assert.ok(result.includes("NODE_ENV: staging"));
+  });
+
+  it("restores [REDACTED] from original in list form", () => {
+    const edited = `      - DB_PASSWORD=[REDACTED]\n      - NODE_ENV=staging`;
+    const original = `      - DB_PASSWORD=secret123\n      - NODE_ENV=production`;
+    const result = restoreRedactedValues(edited, original);
+    assert.ok(result.includes("- DB_PASSWORD=secret123"));
+    assert.ok(result.includes("- NODE_ENV=staging"));
+  });
+
+  it("leaves non-redacted values as-is", () => {
+    const edited = `    NODE_ENV: staging`;
+    const original = `    NODE_ENV: production`;
+    const result = restoreRedactedValues(edited, original);
+    assert.ok(result.includes("NODE_ENV: staging"));
+  });
+});

package/src/tools/admin.ts

@@ -0,0 +1,93 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { SwarmpitClient } from "../client.js";
+import { toolResult, toolError } from "./helpers.js";
+
+export function registerAdminTools(
+  server: McpServer,
+  client: SwarmpitClient
+): void {
+  server.tool(
+    "list_users",
+    "List all Swarmpit users (admin)",
+    {},
+    async () => {
+      try {
+        const users = await client.listUsers();
+        return toolResult(users);
+      } catch (e) {
+        return toolError(e);
+      }
+    }
+  );
+
+  server.tool(
+    "get_user",
+    "Get Swarmpit user details (admin)",
+    { id: z.string().describe("User ID") },
+    async ({ id }) => {
+      try {
+        const user = await client.getUser(id);
+        return toolResult(user);
+      } catch (e) {
+        return toolError(e);
+      }
+    }
+  );
+
+  server.tool(
+    "create_user",
+    "Create a Swarmpit user (admin)",
+    {
+      username: z.string().describe("Username"),
+      password: z.string().describe("Password"),
+      role: z.string().describe("Role (admin or user)"),
+      email: z.string().optional().describe("Email address"),
+    },
+    async ({ username, password, role, email }) => {
+      try {
+        await client.createUser({ username, password, role, email });
+        return toolResult({ created: true, username });
+      } catch (e) {
+        return toolError(e);
+      }
+    }
+  );
+
+  server.tool(
+    "edit_user",
+    "Edit a Swarmpit user (admin)",
+    {
+      id: z.string().describe("User ID"),
+      spec: z.record(z.unknown()).describe("User fields to update (role, email, etc.)"),
+    },
+    async ({ id, spec }) => {
+      try {
+        await client.editUser(id, spec);
+        return toolResult({ updated: true, id });
+      } catch (e) {
+        return toolError(e);
+      }
+    }
+  );
+
+  server.tool(
+    "delete_user",
+    "Delete a Swarmpit user (admin). DESTRUCTIVE: requires confirm=true",
+    {
+      id: z.string().describe("User ID"),
+      confirm: z.boolean().describe("Must be true to confirm deletion"),
+    },
+    async ({ id, confirm }) => {
+      if (!confirm) {
+        return toolError("Destructive operation: set confirm=true to delete this user");
+      }
+      try {
+        await client.deleteUser(id);
+        return toolResult({ deleted: true, id });
+      } catch (e) {
+        return toolError(e);
+      }
+    }
+  );
+}

package/src/tools/configs.ts

@@ -0,0 +1,101 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import type { RedactMode } from "../config.js";
+import { SwarmpitClient } from "../client.js";
+import { toolResult, toolError, resolveData } from "./helpers.js";
+
+function redactConfig(config: Record<string, unknown>, redact: RedactMode): Record<string, unknown> {
+  if (redact === "none") return config;
+  const { data, ...rest } = config;
+  return { ...rest, data: data ? "[REDACTED]" : undefined };
+}
+
+export function registerConfigTools(
+  server: McpServer,
+  client: SwarmpitClient,
+  redact: RedactMode
+): void {
+  server.tool(
+    "list_configs",
+    "List all Docker Swarm configs",
+    {},
+    async () => {
+      try {
+        const configs = await client.listConfigs();
+        return toolResult(configs.map((c) => redactConfig(c, redact)));
+      } catch (e) {
+        return toolError(e);
+      }
+    }
+  );
+
+  server.tool(
+    "get_config",
+    "Get details of a specific Docker Swarm config",
+    { id: z.string().describe("Config ID or name") },
+    async ({ id }) => {
+      try {
+        const config = await client.getConfig(id);
+        return toolResult(redactConfig(config, redact));
+      } catch (e) {
+        return toolError(e);
+      }
+    }
+  );
+
+  server.tool(
+    "create_config",
+    "Create a Docker Swarm config. Data can be plain, { $env: VAR_NAME } to resolve from env, or { $file: /path } to read from a local file (avoids sending large content through LLM context).",
+    {
+      configName: z.string().describe("Config name"),
+      data: z.union([
+        z.string(),
+        z.object({ $env: z.string() }).describe('Reference to local env var'),
+        z.object({ $file: z.string() }).describe('Read from local file path'),
+      ]).describe("Config data — string, { $env: VAR_NAME }, or { $file: /path }"),
+    },
+    async ({ configName, data }) => {
+      try {
+        const resolved = resolveData(data);
+        await client.createConfig({ configName, data: resolved });
+        return toolResult({ created: true, configName });
+      } catch (e) {
+        return toolError(e);
+      }
+    }
+  );
+
+  server.tool(
+    "delete_config",
+    "Delete a Docker Swarm config. DESTRUCTIVE: requires confirm=true",
+    {
+      id: z.string().describe("Config ID or name"),
+      confirm: z.boolean().describe("Must be true to confirm deletion"),
+    },
+    async ({ id, confirm }) => {
+      if (!confirm) {
+        return toolError("Destructive operation: set confirm=true to delete this config");
+      }
+      try {
+        await client.deleteConfig(id);
+        return toolResult({ deleted: true, id });
+      } catch (e) {
+        return toolError(e);
+      }
+    }
+  );
+
+  server.tool(
+    "get_config_services",
+    "List services using a specific config",
+    { id: z.string().describe("Config ID or name") },
+    async ({ id }) => {
+      try {
+        const services = await client.getConfigServices(id);
+        return toolResult(services);
+      } catch (e) {
+        return toolError(e);
+      }
+    }
+  );
+}

package/src/tools/dashboard.ts

@@ -0,0 +1,65 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { SwarmpitClient } from "../client.js";
+import { toolResult, toolError } from "./helpers.js";
+
+export function registerDashboardTools(
+  server: McpServer,
+  client: SwarmpitClient
+): void {
+  server.tool(
+    "pin_node_to_dashboard",
+    "Pin a node to the Swarmpit dashboard",
+    { id: z.string().describe("Node ID") },
+    async ({ id }) => {
+      try {
+        await client.pinNodeToDashboard(id);
+        return toolResult({ pinned: true, id });
+      } catch (e) {
+        return toolError(e);
+      }
+    }
+  );
+
+  server.tool(
+    "unpin_node_from_dashboard",
+    "Remove a node from the Swarmpit dashboard",
+    { id: z.string().describe("Node ID") },
+    async ({ id }) => {
+      try {
+        await client.unpinNodeFromDashboard(id);
+        return toolResult({ unpinned: true, id });
+      } catch (e) {
+        return toolError(e);
+      }
+    }
+  );
+
+  server.tool(
+    "pin_service_to_dashboard",
+    "Pin a service to the Swarmpit dashboard",
+    { id: z.string().describe("Service ID or name") },
+    async ({ id }) => {
+      try {
+        await client.pinServiceToDashboard(id);
+        return toolResult({ pinned: true, id });
+      } catch (e) {
+        return toolError(e);
+      }
+    }
+  );
+
+  server.tool(
+    "unpin_service_from_dashboard",
+    "Remove a service from the Swarmpit dashboard",
+    { id: z.string().describe("Service ID or name") },
+    async ({ id }) => {
+      try {
+        await client.unpinServiceFromDashboard(id);
+        return toolResult({ unpinned: true, id });
+      } catch (e) {
+        return toolError(e);
+      }
+    }
+  );
+}

package/src/tools/helpers.ts

@@ -0,0 +1,91 @@
+import { readFileSync } from "node:fs";
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+
+export function toolResult(data: unknown): CallToolResult {
+  return {
+    content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+  };
+}
+
+export function toolError(error: unknown): CallToolResult {
+  const message =
+    error instanceof Error ? error.message : String(error);
+  return {
+    content: [{ type: "text", text: message }],
+    isError: true,
+  };
+}
+
+/**
+ * Prepare a service object from GET response for use in POST update.
+ * - Strips null values (API rejects them for optional fields)
+ * - Strips read-only fields not accepted by the edit endpoint
+ * - Trims repository to { name, tag } (API rejects imageDigest/image)
+ */
+export function prepareServiceForUpdate(service: Record<string, unknown>): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  const readOnlyKeys = new Set(["id", "createdAt", "updatedAt", "state", "status"]);
+
+  for (const [key, value] of Object.entries(service)) {
+    if (value === null || readOnlyKeys.has(key)) continue;
+    result[key] = value;
+  }
+
+  // Repository: API only accepts { name, tag }
+  const repo = service.repository as Record<string, unknown> | undefined;
+  if (repo) {
+    result.repository = { name: repo.name, tag: repo.tag };
+  }
+
+  return result;
+}
+
+export function resolveEnvRef(
+  value: unknown
+): string {
+  if (typeof value === "string") return value;
+  if (
+    value &&
+    typeof value === "object" &&
+    "$env" in value &&
+    typeof (value as Record<string, unknown>).$env === "string"
+  ) {
+    const varName = (value as Record<string, string>).$env;
+    const resolved = process.env[varName];
+    if (!resolved) {
+      throw new Error(
+        `$env reference "${varName}" is not set in environment`
+      );
+    }
+    return resolved;
+  }
+  throw new Error(
+    `Invalid env var value: expected a string or { "$env": "VAR_NAME" }`
+  );
+}
+
+/**
+ * Resolve a data value that may be a plain string, { $file: path }, or { $env: var }.
+ * Used for config/secret data to avoid sending large payloads through the LLM context.
+ */
+export function resolveData(value: unknown): string {
+  if (typeof value === "string") return value;
+  if (value && typeof value === "object") {
+    if ("$file" in value && typeof (value as Record<string, unknown>).$file === "string") {
+      const path = (value as Record<string, string>).$file;
+      try {
+        return readFileSync(path, "utf-8");
+      } catch (err) {
+        throw new Error(
+          `$file reference "${path}" could not be read: ${err instanceof Error ? err.message : err}`
+        );
+      }
+    }
+    if ("$env" in value && typeof (value as Record<string, unknown>).$env === "string") {
+      return resolveEnvRef(value);
+    }
+  }
+  throw new Error(
+    'Invalid data: expected a string, { "$file": "/path" }, or { "$env": "VAR_NAME" }'
+  );
+}

package/src/tools/networks.ts

@@ -0,0 +1,99 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { SwarmpitClient } from "../client.js";
+import { toolResult, toolError } from "./helpers.js";
+
+export function registerNetworkTools(
+  server: McpServer,
+  client: SwarmpitClient
+): void {
+  server.tool(
+    "list_networks",
+    "List all Docker Swarm networks",
+    {},
+    async () => {
+      try {
+        const networks = await client.listNetworks();
+        return toolResult(networks);
+      } catch (e) {
+        return toolError(e);
+      }
+    }
+  );
+
+  server.tool(
+    "get_network",
+    "Get details of a specific Docker Swarm network",
+    { id: z.string().describe("Network ID or name") },
+    async ({ id }) => {
+      try {
+        const network = await client.getNetwork(id);
+        return toolResult(network);
+      } catch (e) {
+        return toolError(e);
+      }
+    }
+  );
+
+  server.tool(
+    "create_network",
+    "Create a Docker Swarm network",
+    {
+      networkName: z.string().describe("Network name"),
+      driver: z.string().default("overlay").describe("Network driver (default: overlay)"),
+      attachable: z.boolean().default(false).describe("Whether containers can attach to this network"),
+      internal: z.boolean().default(false).describe("Restrict external access"),
+    },
+    async ({ networkName, driver, attachable, internal }) => {
+      try {
+        await client.createNetwork({
+          networkName,
+          driver,
+          attachable,
+          internal,
+          ingress: false,
+          enableIPv6: false,
+          ipam: { subnet: "", gateway: "" },
+          options: [],
+        });
+        return toolResult({ created: true, networkName });
+      } catch (e) {
+        return toolError(e);
+      }
+    }
+  );
+
+  server.tool(
+    "delete_network",
+    "Delete a Docker Swarm network. DESTRUCTIVE: requires confirm=true",
+    {
+      id: z.string().describe("Network ID or name"),
+      confirm: z.boolean().describe("Must be true to confirm deletion"),
+    },
+    async ({ id, confirm }) => {
+      if (!confirm) {
+        return toolError("Destructive operation: set confirm=true to delete this network");
+      }
+      try {
+        await client.deleteNetwork(id);
+        return toolResult({ deleted: true, id });
+      } catch (e) {
+        return toolError(e);
+      }
+    }
+  );
+
+  server.tool(
+    "get_network_services",
+    "List services using a specific network",
+    { id: z.string().describe("Network ID or name") },
+    async ({ id }) => {
+      try {
+        const services = await client.getNetworkServices(id);
+        return toolResult(services);
+      } catch (e) {
+        return toolError(e);
+      }
+    }
+  );
+}