@mseep/mcp-swarmpit 0.1.0

package/src/sanitize.ts

@@ -0,0 +1,218 @@
+import type { SwarmpitService, SwarmpitEnvVar } from "./types.js";
+
+const DEFAULT_SENSITIVE_PATTERNS: RegExp[] = [
+  /pass/i,
+  /secret/i,
+  /token/i,
+  /key/i,
+  /auth/i,
+  /credential/i,
+  /private/i,
+  /connection.?string/i,
+  /dsn/i,
+];
+
+let extraPatterns: RegExp[] = [];
+
+export function setExtraRedactPatterns(patterns: string[]): void {
+  extraPatterns = patterns.map((p) => new RegExp(p, "i"));
+}
+
+function isSensitiveEnvVar(name: string): boolean {
+  return DEFAULT_SENSITIVE_PATTERNS.some((p) => p.test(name))
+    || extraPatterns.some((p) => p.test(name));
+}
+
+function redactEnvVars(
+  variables: SwarmpitEnvVar[] | undefined,
+  redactAll: boolean
+): SwarmpitEnvVar[] | undefined {
+  if (!variables) return undefined;
+  return variables.map((v) => ({
+    name: v.name,
+    value: redactAll || isSensitiveEnvVar(v.name) ? "[REDACTED]" : v.value,
+  }));
+}
+
+export function sanitizeService(
+  service: SwarmpitService,
+  redactAll = true
+): SwarmpitService {
+  return {
+    ...service,
+    variables: redactEnvVars(service.variables, redactAll) ?? [],
+    secrets: service.secrets?.map(({ id, secretName, secretTarget }) => ({
+      id,
+      secretName,
+      secretTarget,
+    })) ?? [],
+    configs: service.configs?.map(({ id, configName, configTarget }) => ({
+      id,
+      configName,
+      configTarget,
+    })) ?? [],
+  };
+}
+
+export function sanitizeServices(
+  services: SwarmpitService[],
+  redactAll = true
+): SwarmpitService[] {
+  return services.map((s) => sanitizeService(s, redactAll));
+}
+
+/**
+ * Sanitize a Docker Compose YAML string by redacting environment variable
+ * values that look sensitive. Handles both forms:
+ *
+ *   environment:
+ *     DATABASE_PASSWORD: supersecret     →  DATABASE_PASSWORD: [REDACTED]
+ *     - DATABASE_PASSWORD=supersecret    →  - DATABASE_PASSWORD=[REDACTED]
+ */
+export function sanitizeComposeYaml(yaml: string, redactAll = true): string {
+  if (!yaml) return yaml;
+
+  // Key-value form:  SOME_KEY: some_value
+  const sanitized = yaml.replace(
+    /^(\s+)([A-Z_][A-Z0-9_]*):\s*(.+)$/gm,
+    (match, indent: string, key: string, value: string) => {
+      // Skip non-env-var-looking keys (lowercase, contains dots, etc.)
+      if (key !== key.toUpperCase()) return match;
+      // Skip values that look like YAML references, objects, or arrays
+      if (value.startsWith("&") || value.startsWith("*") || value.startsWith("{") || value.startsWith("[")) return match;
+      if (redactAll || isSensitiveEnvVar(key)) {
+        return `${indent}${key}: [REDACTED]`;
+      }
+      return match;
+    }
+  );
+
+  // List form:  - SOME_KEY=some_value
+  return sanitized.replace(
+    /^(\s+-\s+)([A-Z_][A-Z0-9_]*)=(.+)$/gm,
+    (match, prefix: string, key: string, value: string) => {
+      if (redactAll || isSensitiveEnvVar(key)) {
+        return `${prefix}${key}=[REDACTED]`;
+      }
+      return match;
+    }
+  );
+}
+
+/**
+ * Resolve $env:VAR_NAME references in a compose YAML string.
+ * Plain values pass through unchanged. Only $env: prefixed values
+ * are resolved from process.env.
+ *
+ *   DATABASE_PASSWORD: $env:MY_DB_PASS  →  DATABASE_PASSWORD: actual-value
+ *   NODE_ENV: production                →  NODE_ENV: production
+ */
+/**
+ * Resolve $env:VAR_NAME references in a compose YAML string.
+ * Plain values pass through unchanged. Only $env: prefixed values
+ * are resolved from process.env.
+ *
+ *   DATABASE_PASSWORD: $env:MY_DB_PASS  →  DATABASE_PASSWORD: actual-value
+ *   NODE_ENV: production                →  NODE_ENV: production
+ */
+export function resolveComposeEnvRefs(yaml: string): string {
+  if (!yaml) return yaml;
+
+  // Key-value form:  KEY: $env:VAR_NAME
+  const resolved = yaml.replace(
+    /^(\s+[A-Z_][A-Z0-9_]*:\s*)\$env:([A-Z_][A-Z0-9_]*)$/gm,
+    (match, prefix: string, varName: string) => {
+      const value = process.env[varName];
+      if (!value) {
+        throw new Error(
+          `$env:${varName} referenced in compose but not set in environment`
+        );
+      }
+      return `${prefix}${value}`;
+    }
+  );
+
+  // List form:  - KEY=$env:VAR_NAME
+  return resolved.replace(
+    /^(\s+-\s+[A-Z_][A-Z0-9_]*=)\$env:([A-Z_][A-Z0-9_]*)$/gm,
+    (match, prefix: string, varName: string) => {
+      const value = process.env[varName];
+      if (!value) {
+        throw new Error(
+          `$env:${varName} referenced in compose but not set in environment`
+        );
+      }
+      return `${prefix}${value}`;
+    }
+  );
+}
+
+/**
+ * Build env var lookup from raw compose YAML. Extracts KEY=value pairs
+ * so [REDACTED] values can be restored from the original.
+ */
+function extractComposeEnvVars(yaml: string): Map<string, string> {
+  const vars = new Map<string, string>();
+  if (!yaml) return vars;
+
+  // Key-value form:  KEY: value
+  for (const match of yaml.matchAll(
+    /^\s+([A-Z_][A-Z0-9_]*):\s*(.+)$/gm
+  )) {
+    vars.set(match[1], match[2]);
+  }
+
+  // List form:  - KEY=value
+  for (const match of yaml.matchAll(
+    /^\s+-\s+([A-Z_][A-Z0-9_]*)=(.+)$/gm
+  )) {
+    vars.set(match[1], match[2]);
+  }
+
+  return vars;
+}
+
+/**
+ * Restore [REDACTED] values in an edited compose YAML from the original
+ * raw compose. This allows safe round-tripping:
+ *
+ * 1. swarmpit_get_stack returns compose with sensitive values as [REDACTED]
+ * 2. Claude edits only what it needs, leaves [REDACTED] in place
+ * 3. This function restores original values where [REDACTED] remains
+ * 4. $env:VAR references are resolved from process.env
+ * 5. Plaintext values pass through as-is
+ */
+export function restoreRedactedValues(
+  editedYaml: string,
+  originalYaml: string
+): string {
+  if (!editedYaml) return editedYaml;
+
+  const origVars = extractComposeEnvVars(originalYaml);
+
+  // Key-value form: restore KEY: [REDACTED]
+  let restored = editedYaml.replace(
+    /^(\s+)([A-Z_][A-Z0-9_]*):\s*\[REDACTED\]$/gm,
+    (match, indent: string, key: string) => {
+      const original = origVars.get(key);
+      if (original) {
+        return `${indent}${key}: ${original}`;
+      }
+      return match;
+    }
+  );
+
+  // List form: restore - KEY=[REDACTED]
+  restored = restored.replace(
+    /^(\s+-\s+)([A-Z_][A-Z0-9_]*)=\[REDACTED\]$/gm,
+    (match, prefix: string, key: string) => {
+      const original = origVars.get(key);
+      if (original) {
+        return `${prefix}${key}=${original}`;
+      }
+      return match;
+    }
+  );
+
+  return restored;
+}

package/src/test/config.test.ts

@@ -0,0 +1,118 @@
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { loadConfig } from "../config.js";
+
+describe("loadConfig", () => {
+  const saved = { ...process.env };
+
+  beforeEach(() => {
+    // Clear all SWARMPIT_ vars
+    for (const key of Object.keys(process.env)) {
+      if (key.startsWith("SWARMPIT_")) delete process.env[key];
+    }
+  });
+
+  afterEach(() => {
+    // Restore original env
+    for (const key of Object.keys(process.env)) {
+      if (key.startsWith("SWARMPIT_")) delete process.env[key];
+    }
+    Object.assign(process.env, saved);
+  });
+
+  it("loads config from env vars", () => {
+    process.env.SWARMPIT_URL = "https://swarmpit.example.com";
+    process.env.SWARMPIT_TOKEN = "test-token";
+
+    const config = loadConfig();
+    assert.equal(config.url, "https://swarmpit.example.com");
+    assert.equal(config.token, "test-token");
+    assert.equal(config.redact, "all");
+  });
+
+  it("strips trailing slashes from URL", () => {
+    process.env.SWARMPIT_URL = "https://swarmpit.example.com///";
+    process.env.SWARMPIT_TOKEN = "test-token";
+
+    const config = loadConfig();
+    assert.equal(config.url, "https://swarmpit.example.com");
+  });
+
+  it("reads SWARMPIT_REDACT mode", () => {
+    process.env.SWARMPIT_URL = "https://swarmpit.example.com";
+    process.env.SWARMPIT_TOKEN = "test-token";
+    process.env.SWARMPIT_REDACT = "sensitive";
+
+    const config = loadConfig();
+    assert.equal(config.redact, "sensitive");
+  });
+
+  it("accepts none redact mode", () => {
+    process.env.SWARMPIT_URL = "https://swarmpit.example.com";
+    process.env.SWARMPIT_TOKEN = "test-token";
+    process.env.SWARMPIT_REDACT = "none";
+
+    const config = loadConfig();
+    assert.equal(config.redact, "none");
+  });
+
+  it("throws on missing SWARMPIT_URL", () => {
+    process.env.SWARMPIT_TOKEN = "test-token";
+    assert.throws(() => loadConfig(), /SWARMPIT_URL is not set/);
+  });
+
+  it("throws on missing SWARMPIT_TOKEN", () => {
+    process.env.SWARMPIT_URL = "https://swarmpit.example.com";
+    assert.throws(
+      () => loadConfig(),
+      /Neither SWARMPIT_TOKEN nor SWARMPIT_TOKEN_FILE is set/
+    );
+  });
+
+  it("loads token from SWARMPIT_TOKEN_FILE", async () => {
+    const { writeFileSync, unlinkSync, mkdtempSync, rmSync } = await import("node:fs");
+    const { tmpdir } = await import("node:os");
+    const { join } = await import("node:path");
+    const dir = mkdtempSync(join(tmpdir(), "mcp-token-"));
+    const path = join(dir, "token");
+    writeFileSync(path, "file-loaded-token\n"); // trailing newline should be stripped
+    try {
+      process.env.SWARMPIT_URL = "https://swarmpit.example.com";
+      process.env.SWARMPIT_TOKEN_FILE = path;
+      const config = loadConfig();
+      assert.equal(config.token, "file-loaded-token");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("SWARMPIT_TOKEN_FILE takes precedence over SWARMPIT_TOKEN", async () => {
+    const { writeFileSync, mkdtempSync, rmSync } = await import("node:fs");
+    const { tmpdir } = await import("node:os");
+    const { join } = await import("node:path");
+    const dir = mkdtempSync(join(tmpdir(), "mcp-token-"));
+    const path = join(dir, "token");
+    writeFileSync(path, "from-file");
+    try {
+      process.env.SWARMPIT_URL = "https://swarmpit.example.com";
+      process.env.SWARMPIT_TOKEN = "from-env";
+      process.env.SWARMPIT_TOKEN_FILE = path;
+      assert.equal(loadConfig().token, "from-file");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("throws when SWARMPIT_TOKEN_FILE points to missing file", () => {
+    process.env.SWARMPIT_URL = "https://swarmpit.example.com";
+    process.env.SWARMPIT_TOKEN_FILE = "/nonexistent/token-file";
+    assert.throws(() => loadConfig(), /could not be read/);
+  });
+
+  it("throws on invalid SWARMPIT_REDACT", () => {
+    process.env.SWARMPIT_URL = "https://swarmpit.example.com";
+    process.env.SWARMPIT_TOKEN = "test-token";
+    process.env.SWARMPIT_REDACT = "invalid";
+    assert.throws(() => loadConfig(), /SWARMPIT_REDACT/);
+  });
+});

package/src/test/file-ref.test.ts

@@ -0,0 +1,191 @@
+import { describe, it, beforeEach, afterEach } from "node:test";
+import assert from "node:assert/strict";
+import { writeFileSync, unlinkSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { registerConfigTools } from "../tools/configs.js";
+import { registerSecretTools } from "../tools/secrets.js";
+import { registerStackTools } from "../tools/stacks.js";
+
+/**
+ * Minimal mock that captures tool handlers registered on the MCP server,
+ * so we can invoke them directly in tests without the transport layer.
+ */
+function mockServer(): { handlers: Record<string, Function>; tool: Function } {
+  const handlers: Record<string, Function> = {};
+  return {
+    handlers,
+    tool(name: string, _desc: string, _schema: unknown, handler: Function) {
+      handlers[name] = handler;
+    },
+  } as unknown as { handlers: Record<string, Function>; tool: Function };
+}
+
+function mockClient() {
+  const calls: Record<string, unknown[][]> = {};
+  const record = (method: string) => (...args: unknown[]) => {
+    (calls[method] ||= []).push(args);
+    return Promise.resolve(undefined as unknown);
+  };
+  return {
+    calls,
+    listSecrets: record("listSecrets"),
+    listConfigs: record("listConfigs"),
+    createSecret: record("createSecret"),
+    createConfig: record("createConfig"),
+    createStack: record("createStack"),
+    updateStack: record("updateStack"),
+    getStackFile: () => Promise.resolve({ compose: "" }),
+    createStackFile: record("createStackFile"),
+  };
+}
+
+describe("$file integration", () => {
+  let tmpDir: string;
+  let filePath: string;
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), "mcp-swarmpit-test-"));
+    filePath = join(tmpDir, "data.txt");
+  });
+
+  afterEach(() => {
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("create_config reads data from $file", async () => {
+    writeFileSync(filePath, "<html>hello from file</html>");
+    const server = mockServer();
+    const client = mockClient();
+    registerConfigTools(server as never, client as never, "sensitive");
+
+    const result = await server.handlers.create_config({
+      configName: "my_config",
+      data: { $file: filePath },
+    });
+
+    assert.equal(result.isError, undefined);
+    const [arg] = client.calls.createConfig[0] as [{ configName: string; data: string }];
+    assert.equal(arg.configName, "my_config");
+    assert.equal(arg.data, "<html>hello from file</html>");
+  });
+
+  it("create_secret reads data from $file", async () => {
+    writeFileSync(filePath, "super-secret-token");
+    const server = mockServer();
+    const client = mockClient();
+    registerSecretTools(server as never, client as never, "sensitive");
+
+    const result = await server.handlers.create_secret({
+      secretName: "api_token",
+      data: { $file: filePath },
+    });
+
+    assert.equal(result.isError, undefined);
+    const [arg] = client.calls.createSecret[0] as [{ secretName: string; data: string }];
+    assert.equal(arg.secretName, "api_token");
+    assert.equal(arg.data, "super-secret-token");
+  });
+
+  it("create_stack reads compose from $file", async () => {
+    const compose = "version: '3.3'\nservices:\n  web:\n    image: nginx\n";
+    writeFileSync(filePath, compose);
+    const server = mockServer();
+    const client = mockClient();
+    registerStackTools(server as never, client as never, "sensitive");
+
+    const result = await server.handlers.create_stack({
+      name: "myapp",
+      compose: { $file: filePath },
+    });
+
+    assert.equal(result.isError, undefined);
+    const [arg] = client.calls.createStack[0] as [{ name: string; spec: { compose: string } }];
+    assert.equal(arg.name, "myapp");
+    assert.equal(arg.spec.compose, compose);
+  });
+
+  it("update_stack reads compose from $file", async () => {
+    const compose = "version: '3.3'\nservices:\n  web:\n    image: nginx:updated\n";
+    writeFileSync(filePath, compose);
+    const server = mockServer();
+    const client = mockClient();
+    registerStackTools(server as never, client as never, "sensitive");
+
+    const result = await server.handlers.update_stack({
+      name: "myapp",
+      compose: { $file: filePath },
+    });
+
+    assert.equal(result.isError, undefined);
+    const [name, yaml] = client.calls.updateStack[0] as [string, string];
+    assert.equal(name, "myapp");
+    assert.equal(yaml, compose);
+  });
+
+  it("create_stack_file reads compose from $file", async () => {
+    const compose = "version: '3.3'\nservices: {}\n";
+    writeFileSync(filePath, compose);
+    const server = mockServer();
+    const client = mockClient();
+    registerStackTools(server as never, client as never, "sensitive");
+
+    const result = await server.handlers.create_stack_file({
+      name: "myapp",
+      compose: { $file: filePath },
+    });
+
+    assert.equal(result.isError, undefined);
+    const [name, yaml] = client.calls.createStackFile[0] as [string, string];
+    assert.equal(name, "myapp");
+    assert.equal(yaml, compose);
+  });
+
+  it("create_config with $file does not resolve $env: inside raw config data", async () => {
+    writeFileSync(filePath, "$env:SHOULD_NOT_RESOLVE");
+    const server = mockServer();
+    const client = mockClient();
+    registerConfigTools(server as never, client as never, "sensitive");
+
+    await server.handlers.create_config({
+      configName: "x",
+      data: { $file: filePath },
+    });
+
+    const [arg] = client.calls.createConfig[0] as [{ data: string }];
+    assert.equal(arg.data, "$env:SHOULD_NOT_RESOLVE");
+  });
+
+  it("create_stack with $file resolves $env: refs inside compose", async () => {
+    process.env.TEST_STACK_FILE_VAR = "resolved-value";
+    const compose = "services:\n  app:\n    environment:\n      SECRET: $env:TEST_STACK_FILE_VAR\n";
+    writeFileSync(filePath, compose);
+    const server = mockServer();
+    const client = mockClient();
+    registerStackTools(server as never, client as never, "sensitive");
+
+    const result = await server.handlers.create_stack({
+      name: "myapp",
+      compose: { $file: filePath },
+    });
+
+    assert.equal(result.isError, undefined);
+    const [arg] = client.calls.createStack[0] as [{ spec: { compose: string } }];
+    assert.ok(arg.spec.compose.includes("SECRET: resolved-value"));
+    delete process.env.TEST_STACK_FILE_VAR;
+  });
+
+  it("returns isError for missing file", async () => {
+    const server = mockServer();
+    const client = mockClient();
+    registerConfigTools(server as never, client as never, "sensitive");
+
+    const result = await server.handlers.create_config({
+      configName: "x",
+      data: { $file: "/nonexistent/path/xyz" },
+    });
+
+    assert.equal(result.isError, true);
+    assert.equal(client.calls.createConfig, undefined);
+  });
+});

package/src/test/helpers.test.ts

@@ -0,0 +1,147 @@
+import { describe, it } from "node:test";
+import assert from "node:assert/strict";
+import { toolResult, toolError, resolveEnvRef, prepareServiceForUpdate, resolveData } from "../tools/helpers.js";
+import { writeFileSync, unlinkSync } from "node:fs";
+
+describe("toolResult", () => {
+  it("wraps data as JSON text content", () => {
+    const result = toolResult({ foo: "bar" });
+    assert.equal(result.content.length, 1);
+    assert.equal(result.content[0].type, "text");
+    assert.deepEqual(JSON.parse((result.content[0] as { text: string }).text), { foo: "bar" });
+  });
+});
+
+describe("toolError", () => {
+  it("wraps Error as text with isError flag", () => {
+    const result = toolError(new Error("something broke"));
+    assert.equal(result.isError, true);
+    assert.equal((result.content[0] as { text: string }).text, "something broke");
+  });
+
+  it("wraps string as text with isError flag", () => {
+    const result = toolError("plain string error");
+    assert.equal(result.isError, true);
+    assert.equal((result.content[0] as { text: string }).text, "plain string error");
+  });
+});
+
+describe("resolveEnvRef", () => {
+  it("returns plain strings as-is", () => {
+    assert.equal(resolveEnvRef("hello"), "hello");
+  });
+
+  it("resolves { $env: VAR } from process.env", () => {
+    process.env.TEST_RESOLVE_VAR = "resolved-value";
+    assert.equal(resolveEnvRef({ $env: "TEST_RESOLVE_VAR" }), "resolved-value");
+    delete process.env.TEST_RESOLVE_VAR;
+  });
+
+  it("throws on missing env var ref", () => {
+    delete process.env.NONEXISTENT_REF;
+    assert.throws(() => resolveEnvRef({ $env: "NONEXISTENT_REF" }), /NONEXISTENT_REF/);
+  });
+
+  it("throws on invalid value type", () => {
+    assert.throws(() => resolveEnvRef(42), /Invalid env var value/);
+  });
+});
+
+describe("prepareServiceForUpdate", () => {
+  it("strips null values", () => {
+    const result = prepareServiceForUpdate({
+      serviceName: "test",
+      mode: "replicated",
+      tty: null,
+      dir: null,
+      command: null,
+    });
+    assert.equal(result.serviceName, "test");
+    assert.equal("tty" in result, false);
+    assert.equal("dir" in result, false);
+    assert.equal("command" in result, false);
+  });
+
+  it("strips read-only fields", () => {
+    const result = prepareServiceForUpdate({
+      id: "abc123",
+      createdAt: "2024-01-01",
+      updatedAt: "2024-01-02",
+      state: "running",
+      status: { tasks: { running: 1, total: 1 } },
+      serviceName: "test",
+      mode: "replicated",
+    });
+    assert.equal("id" in result, false);
+    assert.equal("createdAt" in result, false);
+    assert.equal("updatedAt" in result, false);
+    assert.equal("state" in result, false);
+    assert.equal("status" in result, false);
+    assert.equal(result.serviceName, "test");
+  });
+
+  it("trims repository to name and tag only", () => {
+    const result = prepareServiceForUpdate({
+      serviceName: "test",
+      mode: "replicated",
+      repository: {
+        name: "nginx",
+        tag: "alpine",
+        image: "nginx:alpine",
+        imageDigest: "sha256:abc123",
+      },
+    });
+    const repo = result.repository as Record<string, unknown>;
+    assert.equal(repo.name, "nginx");
+    assert.equal(repo.tag, "alpine");
+    assert.equal("image" in repo, false);
+    assert.equal("imageDigest" in repo, false);
+  });
+
+  it("handles repository with empty imageDigest", () => {
+    const result = prepareServiceForUpdate({
+      serviceName: "test",
+      mode: "replicated",
+      repository: {
+        name: "nginx",
+        tag: "alpine",
+        image: "nginx:alpine",
+        imageDigest: "",
+      },
+    });
+    const repo = result.repository as Record<string, unknown>;
+    assert.equal(repo.name, "nginx");
+    assert.equal(repo.tag, "alpine");
+    assert.equal("imageDigest" in repo, false);
+  });
+});
+
+describe("resolveData", () => {
+  it("returns plain strings as-is", () => {
+    assert.equal(resolveData("hello"), "hello");
+  });
+
+  it("reads from file path via $file", () => {
+    const path = "/tmp/mcp-swarmpit-test-data.txt";
+    writeFileSync(path, "contents from file");
+    try {
+      assert.equal(resolveData({ $file: path }), "contents from file");
+    } finally {
+      unlinkSync(path);
+    }
+  });
+
+  it("resolves $env references", () => {
+    process.env.TEST_DATA_VAR = "env-value";
+    assert.equal(resolveData({ $env: "TEST_DATA_VAR" }), "env-value");
+    delete process.env.TEST_DATA_VAR;
+  });
+
+  it("throws on missing file", () => {
+    assert.throws(() => resolveData({ $file: "/nonexistent/path/xyz" }), /could not be read/);
+  });
+
+  it("throws on invalid value type", () => {
+    assert.throws(() => resolveData(42), /Invalid data/);
+  });
+});