@mseep/mcp-swarmpit 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,119 @@
+export interface SwarmpitPort {
+    containerPort: number;
+    hostPort: number;
+    protocol: string;
+    mode: string;
+}
+export interface SwarmpitMount {
+    containerPath: string;
+    host: string;
+    type: string;
+    readOnly: boolean;
+}
+export interface SwarmpitEnvVar {
+    name: string;
+    value: string;
+}
+export interface SwarmpitLabel {
+    name: string;
+    value: string;
+}
+export interface SwarmpitSecretRef {
+    id: string;
+    secretName: string;
+    secretTarget: string;
+}
+export interface SwarmpitConfigRef {
+    id: string;
+    configName: string;
+    configTarget: string;
+}
+export interface SwarmpitRepository {
+    name: string;
+    tag: string;
+    image: string;
+    imageDigest: string;
+}
+export interface SwarmpitResources {
+    cpu: number;
+    memory: number;
+}
+export interface SwarmpitServiceStatus {
+    tasks: {
+        running: number;
+        total: number;
+    };
+    update: string;
+    message: string;
+}
+export interface SwarmpitService {
+    id: string;
+    version: number;
+    createdAt: string;
+    updatedAt: string;
+    repository: SwarmpitRepository;
+    serviceName: string;
+    mode: string;
+    replicas: number;
+    state: string;
+    status: SwarmpitServiceStatus;
+    ports: SwarmpitPort[];
+    mounts: SwarmpitMount[];
+    networks: SwarmpitNetwork[];
+    secrets: SwarmpitSecretRef[];
+    configs: SwarmpitConfigRef[];
+    variables: SwarmpitEnvVar[];
+    labels: SwarmpitLabel[];
+    command: string[] | null;
+    stack: string;
+    resources: {
+        reservation: SwarmpitResources;
+        limit: SwarmpitResources;
+    };
+}
+export interface SwarmpitStack {
+    stackName: string;
+    stackFile: string;
+    services: SwarmpitService[];
+}
+export interface SwarmpitNetwork {
+    id: string;
+    networkName: string;
+    driver: string;
+    scope: string;
+    internal: boolean;
+    stack: string;
+}
+export interface SwarmpitNode {
+    id: string;
+    nodeName: string;
+    role: string;
+    state: string;
+    availability: string;
+    address: string;
+    engine: string;
+}
+export interface SwarmpitTask {
+    id: string;
+    taskName: string;
+    serviceName: string;
+    state: string;
+    status: string;
+    desiredState: string;
+    createdAt: string;
+    repository: SwarmpitRepository;
+    nodeName: string;
+    nodeId: string;
+}
+export interface SwarmpitVolume {
+    volumeName: string;
+    driver: string;
+    scope: string;
+    stack: string;
+    mountpoint: string;
+}
+export interface SwarmpitLogEntry {
+    line: string;
+    timestamp?: string;
+    taskName?: string;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@mseep/mcp-swarmpit",
+  "version": "0.1.0",
+  "description": "MCP server for managing Swarmpit Docker Swarm instances",
+  "type": "module",
+  "bin": {
+    "mcp-swarmpit": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "test": "node --test dist/test/*.test.js",
+    "pretest": "tsc",
+    "prepare": "tsc"
+  },
+  "keywords": [
+    "mcp",
+    "swarmpit",
+    "docker",
+    "swarm",
+    "claude",
+    "mseep",
+    "mcp-server"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/swarmpit/mcp"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publisher": "mseep"
+}

package/src/client.ts

@@ -0,0 +1,391 @@
+import type {
+  SwarmpitService,
+  SwarmpitStack,
+  SwarmpitNetwork,
+  SwarmpitNode,
+  SwarmpitTask,
+  SwarmpitVolume,
+  SwarmpitLogEntry,
+} from "./types.js";
+
+export class SwarmpitApiError extends Error {
+  constructor(
+    public status: number,
+    public statusText: string,
+    public body: string
+  ) {
+    super(`Swarmpit API error ${status} ${statusText}: ${body}`);
+    this.name = "SwarmpitApiError";
+  }
+}
+
+export class SwarmpitClient {
+  private baseUrl: string;
+  private token: string;
+  private timeout: number;
+
+  constructor(baseUrl: string, token: string, timeout = 30_000) {
+    this.baseUrl = baseUrl;
+    this.token = token;
+    this.timeout = timeout;
+  }
+
+  private async request<T>(
+    method: string,
+    path: string,
+    body?: unknown
+  ): Promise<T> {
+    const url = `${this.baseUrl}${path}`;
+    const headers: Record<string, string> = {
+      Authorization: this.token.startsWith("Bearer ") ? this.token : `Bearer ${this.token}`,
+      Accept: "application/json",
+    };
+
+    if (body !== undefined) {
+      headers["Content-Type"] = "application/json";
+    }
+
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeout);
+
+    try {
+      const response = await fetch(url, {
+        method,
+        headers,
+        body: body !== undefined ? JSON.stringify(body) : undefined,
+        signal: controller.signal,
+      });
+
+      if (!response.ok) {
+        const text = await response.text().catch(() => "");
+        if (response.status === 401) {
+          throw new SwarmpitApiError(
+            401,
+            response.statusText,
+            "Token expired or invalid — regenerate the API token in Swarmpit"
+          );
+        }
+        throw new SwarmpitApiError(response.status, response.statusText, text);
+      }
+
+      const text = await response.text();
+      if (!text) return undefined as T;
+      return JSON.parse(text) as T;
+    } catch (err) {
+      if (err instanceof SwarmpitApiError) throw err;
+      if (err instanceof Error && err.name === "AbortError") {
+        throw new Error(`Swarmpit API request timed out after ${this.timeout}ms: ${method} ${path}`);
+      }
+      throw err;
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  // Services
+  async listServices(): Promise<SwarmpitService[]> {
+    return this.request<SwarmpitService[]>("GET", "/api/services");
+  }
+
+  async getService(id: string): Promise<SwarmpitService> {
+    return this.request<SwarmpitService>("GET", `/api/services/${encodeURIComponent(id)}`);
+  }
+
+  async getServiceLogs(id: string, since = "5m"): Promise<SwarmpitLogEntry[]> {
+    // Swarmpit accepts Go duration strings: "1s", "1m", "1h", "24h" etc.
+    return this.request<SwarmpitLogEntry[]>("GET", `/api/services/${encodeURIComponent(id)}/logs?since=${encodeURIComponent(since)}`);
+  }
+
+  async createService(spec: Record<string, unknown>): Promise<{ id: string }> {
+    return this.request<{ id: string }>("POST", "/api/services", spec);
+  }
+
+  async updateService(id: string, spec: Record<string, unknown>): Promise<void> {
+    await this.request<void>("POST", `/api/services/${encodeURIComponent(id)}`, spec);
+  }
+
+  async redeployService(id: string, tag?: string): Promise<void> {
+    const query = tag ? `?tag=${encodeURIComponent(tag)}` : "";
+    await this.request<void>("POST", `/api/services/${encodeURIComponent(id)}/redeploy${query}`);
+  }
+
+  async rollbackService(id: string): Promise<void> {
+    await this.request<void>("POST", `/api/services/${encodeURIComponent(id)}/rollback`);
+  }
+
+  async stopService(id: string): Promise<void> {
+    await this.request<void>("POST", `/api/services/${encodeURIComponent(id)}/stop`);
+  }
+
+  async deleteService(id: string): Promise<void> {
+    await this.request<void>("DELETE", `/api/services/${encodeURIComponent(id)}`);
+  }
+
+  async getServiceTasks(id: string): Promise<SwarmpitTask[]> {
+    return this.request<SwarmpitTask[]>("GET", `/api/services/${encodeURIComponent(id)}/tasks`);
+  }
+
+  async getServiceCompose(id: string): Promise<{ compose: string }> {
+    const result = await this.request<{ spec?: { compose: string }; compose?: string }>(
+      "GET", `/api/services/${encodeURIComponent(id)}/compose`
+    );
+    return { compose: result.spec?.compose ?? result.compose ?? "" };
+  }
+
+  async getServiceNetworks(id: string): Promise<SwarmpitNetwork[]> {
+    return this.request<SwarmpitNetwork[]>("GET", `/api/services/${encodeURIComponent(id)}/networks`);
+  }
+
+  // Stacks
+  async listStacks(): Promise<SwarmpitStack[]> {
+    return this.request<SwarmpitStack[]>("GET", "/api/stacks");
+  }
+
+  async getStackServices(name: string): Promise<SwarmpitService[]> {
+    return this.request<SwarmpitService[]>("GET", `/api/stacks/${encodeURIComponent(name)}/services`);
+  }
+
+  async getStackFile(name: string): Promise<{ compose: string }> {
+    const result = await this.request<{ spec?: { compose: string }; compose?: string }>(
+      "GET", `/api/stacks/${encodeURIComponent(name)}/file`
+    );
+    // API returns { spec: { compose } } but we normalize to { compose }
+    const compose = result.spec?.compose ?? result.compose ?? "";
+    return { compose };
+  }
+
+  async createStack(spec: { name: string; spec: { compose: string } }): Promise<void> {
+    await this.request<void>("POST", "/api/stacks", spec);
+  }
+
+  async updateStack(name: string, compose: string): Promise<void> {
+    await this.request<void>("POST", `/api/stacks/${encodeURIComponent(name)}`, {
+      name,
+      spec: { compose },
+    });
+  }
+
+  async redeployStack(name: string): Promise<void> {
+    await this.request<void>("POST", `/api/stacks/${encodeURIComponent(name)}/redeploy`);
+  }
+
+  async rollbackStack(name: string): Promise<void> {
+    await this.request<void>("POST", `/api/stacks/${encodeURIComponent(name)}/rollback`);
+  }
+
+  async deactivateStack(name: string): Promise<void> {
+    await this.request<void>("POST", `/api/stacks/${encodeURIComponent(name)}/deactivate`);
+  }
+
+  async getStackTasks(name: string): Promise<SwarmpitTask[]> {
+    return this.request<SwarmpitTask[]>("GET", `/api/stacks/${encodeURIComponent(name)}/tasks`);
+  }
+
+  async getStackVolumes(name: string): Promise<SwarmpitVolume[]> {
+    return this.request<SwarmpitVolume[]>("GET", `/api/stacks/${encodeURIComponent(name)}/volumes`);
+  }
+
+  async getStackNetworks(name: string): Promise<SwarmpitNetwork[]> {
+    return this.request<SwarmpitNetwork[]>("GET", `/api/stacks/${encodeURIComponent(name)}/networks`);
+  }
+
+  async getStackCompose(name: string): Promise<{ compose: string }> {
+    const result = await this.request<{ spec?: { compose: string }; compose?: string }>(
+      "GET", `/api/stacks/${encodeURIComponent(name)}/compose`
+    );
+    return { compose: result.spec?.compose ?? result.compose ?? "" };
+  }
+
+  async getStackSecrets(name: string): Promise<Record<string, unknown>[]> {
+    return this.request<Record<string, unknown>[]>("GET", `/api/stacks/${encodeURIComponent(name)}/secrets`);
+  }
+
+  async getStackConfigs(name: string): Promise<Record<string, unknown>[]> {
+    return this.request<Record<string, unknown>[]>("GET", `/api/stacks/${encodeURIComponent(name)}/configs`);
+  }
+
+  async createStackFile(name: string, compose: string): Promise<void> {
+    await this.request<void>("POST", `/api/stacks/${encodeURIComponent(name)}/file`, { name, spec: { compose } });
+  }
+
+  async deleteStackFile(name: string): Promise<void> {
+    await this.request<void>("DELETE", `/api/stacks/${encodeURIComponent(name)}/file`);
+  }
+
+  async deleteStack(name: string): Promise<void> {
+    await this.request<void>("DELETE", `/api/stacks/${encodeURIComponent(name)}`);
+  }
+
+  // Networks
+  async listNetworks(): Promise<SwarmpitNetwork[]> {
+    return this.request<SwarmpitNetwork[]>("GET", "/api/networks");
+  }
+
+  async getNetwork(id: string): Promise<SwarmpitNetwork> {
+    return this.request<SwarmpitNetwork>("GET", `/api/networks/${encodeURIComponent(id)}`);
+  }
+
+  async getNetworkServices(id: string): Promise<SwarmpitService[]> {
+    return this.request<SwarmpitService[]>("GET", `/api/networks/${encodeURIComponent(id)}/services`);
+  }
+
+  async createNetwork(spec: Record<string, unknown>): Promise<void> {
+    await this.request<void>("POST", "/api/networks", spec);
+  }
+
+  async deleteNetwork(id: string): Promise<void> {
+    await this.request<void>("DELETE", `/api/networks/${encodeURIComponent(id)}`);
+  }
+
+  // Nodes
+  async listNodes(): Promise<SwarmpitNode[]> {
+    return this.request<SwarmpitNode[]>("GET", "/api/nodes");
+  }
+
+  async getNode(id: string): Promise<SwarmpitNode> {
+    return this.request<SwarmpitNode>("GET", `/api/nodes/${encodeURIComponent(id)}`);
+  }
+
+  async editNode(id: string, spec: Record<string, unknown>): Promise<void> {
+    await this.request<void>("POST", `/api/nodes/${encodeURIComponent(id)}`, spec);
+  }
+
+  async deleteNode(id: string): Promise<void> {
+    await this.request<void>("DELETE", `/api/nodes/${encodeURIComponent(id)}`);
+  }
+
+  async getNodeTasks(id: string): Promise<SwarmpitTask[]> {
+    return this.request<SwarmpitTask[]>("GET", `/api/nodes/${encodeURIComponent(id)}/tasks`);
+  }
+
+  // Tasks
+  async listTasks(): Promise<SwarmpitTask[]> {
+    return this.request<SwarmpitTask[]>("GET", "/api/tasks");
+  }
+
+  async getTask(id: string): Promise<SwarmpitTask> {
+    return this.request<SwarmpitTask>("GET", `/api/tasks/${encodeURIComponent(id)}`);
+  }
+
+  // Volumes
+  async listVolumes(): Promise<SwarmpitVolume[]> {
+    return this.request<SwarmpitVolume[]>("GET", "/api/volumes");
+  }
+
+  async getVolume(name: string): Promise<SwarmpitVolume> {
+    return this.request<SwarmpitVolume>("GET", `/api/volumes/${encodeURIComponent(name)}`);
+  }
+
+  async getVolumeServices(name: string): Promise<SwarmpitService[]> {
+    return this.request<SwarmpitService[]>("GET", `/api/volumes/${encodeURIComponent(name)}/services`);
+  }
+
+  async createVolume(spec: Record<string, unknown>): Promise<void> {
+    await this.request<void>("POST", "/api/volumes", spec);
+  }
+
+  async deleteVolume(name: string): Promise<void> {
+    await this.request<void>("DELETE", `/api/volumes/${encodeURIComponent(name)}`);
+  }
+
+  // Secrets
+  async listSecrets(): Promise<Record<string, unknown>[]> {
+    return this.request<Record<string, unknown>[]>("GET", "/api/secrets");
+  }
+
+  async getSecret(id: string): Promise<Record<string, unknown>> {
+    return this.request<Record<string, unknown>>("GET", `/api/secrets/${encodeURIComponent(id)}`);
+  }
+
+  async getSecretServices(id: string): Promise<SwarmpitService[]> {
+    return this.request<SwarmpitService[]>("GET", `/api/secrets/${encodeURIComponent(id)}/services`);
+  }
+
+  async createSecret(spec: { secretName: string; data: string }): Promise<void> {
+    // Swarmpit expects base64-encoded data
+    const encoded = Buffer.from(spec.data, "utf-8").toString("base64");
+    await this.request<void>("POST", "/api/secrets", { ...spec, data: encoded });
+  }
+
+  async deleteSecret(id: string): Promise<void> {
+    await this.request<void>("DELETE", `/api/secrets/${encodeURIComponent(id)}`);
+  }
+
+  // Configs
+  async listConfigs(): Promise<Record<string, unknown>[]> {
+    return this.request<Record<string, unknown>[]>("GET", "/api/configs");
+  }
+
+  async getConfig(id: string): Promise<Record<string, unknown>> {
+    return this.request<Record<string, unknown>>("GET", `/api/configs/${encodeURIComponent(id)}`);
+  }
+
+  async getConfigServices(id: string): Promise<SwarmpitService[]> {
+    return this.request<SwarmpitService[]>("GET", `/api/configs/${encodeURIComponent(id)}/services`);
+  }
+
+  async createConfig(spec: { configName: string; data: string }): Promise<void> {
+    // Swarmpit expects base64-encoded data
+    const encoded = Buffer.from(spec.data, "utf-8").toString("base64");
+    await this.request<void>("POST", "/api/configs", { ...spec, data: encoded });
+  }
+
+  async deleteConfig(id: string): Promise<void> {
+    await this.request<void>("DELETE", `/api/configs/${encodeURIComponent(id)}`);
+  }
+
+  // Admin
+  async listUsers(): Promise<Record<string, unknown>[]> {
+    return this.request<Record<string, unknown>[]>("GET", "/api/admin/users");
+  }
+
+  async getUser(id: string): Promise<Record<string, unknown>> {
+    return this.request<Record<string, unknown>>("GET", `/api/admin/users/${encodeURIComponent(id)}`);
+  }
+
+  async createUser(spec: { username: string; password: string; role: string; email?: string }): Promise<void> {
+    await this.request<void>("POST", "/api/admin/users", spec);
+  }
+
+  async editUser(id: string, spec: Record<string, unknown>): Promise<void> {
+    await this.request<void>("POST", `/api/admin/users/${encodeURIComponent(id)}`, spec);
+  }
+
+  async deleteUser(id: string): Promise<void> {
+    await this.request<void>("DELETE", `/api/admin/users/${encodeURIComponent(id)}`);
+  }
+
+  // Dashboard
+  async pinNodeToDashboard(id: string): Promise<void> {
+    await this.request<void>("POST", `/api/nodes/${encodeURIComponent(id)}/dashboard`);
+  }
+
+  async unpinNodeFromDashboard(id: string): Promise<void> {
+    await this.request<void>("DELETE", `/api/nodes/${encodeURIComponent(id)}/dashboard`);
+  }
+
+  async pinServiceToDashboard(id: string): Promise<void> {
+    await this.request<void>("POST", `/api/services/${encodeURIComponent(id)}/dashboard`);
+  }
+
+  async unpinServiceFromDashboard(id: string): Promise<void> {
+    await this.request<void>("DELETE", `/api/services/${encodeURIComponent(id)}/dashboard`);
+  }
+
+  // Timeseries
+  async getNodesTimeseries(): Promise<unknown> {
+    return this.request<unknown>("GET", "/api/nodes/ts");
+  }
+
+  async getServicesCpuTimeseries(): Promise<unknown> {
+    return this.request<unknown>("GET", "/api/services/ts/cpu");
+  }
+
+  async getServicesMemoryTimeseries(): Promise<unknown> {
+    return this.request<unknown>("GET", "/api/services/ts/memory");
+  }
+
+  async getTaskTimeseries(name: string): Promise<unknown> {
+    return this.request<unknown>("GET", `/api/tasks/${encodeURIComponent(name)}/ts`);
+  }
+}

package/src/config.ts

@@ -0,0 +1,57 @@
+import { readFileSync } from "node:fs";
+
+export type RedactMode = "all" | "sensitive" | "none";
+
+export interface SwarmpitConfig {
+  url: string;
+  token: string;
+  redact: RedactMode;
+  redactPatterns: string[];
+}
+
+function loadToken(): string {
+  const tokenFile = process.env.SWARMPIT_TOKEN_FILE;
+  if (tokenFile) {
+    try {
+      return readFileSync(tokenFile, "utf-8").trim();
+    } catch (err) {
+      throw new Error(
+        `SWARMPIT_TOKEN_FILE "${tokenFile}" could not be read: ${err instanceof Error ? err.message : err}`
+      );
+    }
+  }
+  const token = process.env.SWARMPIT_TOKEN;
+  if (!token) {
+    throw new Error(
+      "Neither SWARMPIT_TOKEN nor SWARMPIT_TOKEN_FILE is set. Use SWARMPIT_TOKEN_FILE to avoid storing the token in MCP client config files."
+    );
+  }
+  return token;
+}
+
+export function loadConfig(): SwarmpitConfig {
+  const url = process.env.SWARMPIT_URL;
+  if (!url) throw new Error("SWARMPIT_URL is not set");
+
+  const token = loadToken();
+
+  const redactRaw = process.env.SWARMPIT_REDACT;
+  let redact: RedactMode = "all";
+  if (redactRaw !== undefined) {
+    if (redactRaw !== "all" && redactRaw !== "sensitive" && redactRaw !== "none") {
+      throw new Error('SWARMPIT_REDACT must be "all" (default), "sensitive", or "none"');
+    }
+    redact = redactRaw;
+  }
+
+  const redactPatterns = process.env.SWARMPIT_REDACT_PATTERNS
+    ? process.env.SWARMPIT_REDACT_PATTERNS.split(",").map((p) => p.trim()).filter(Boolean)
+    : [];
+
+  return {
+    url: url.replace(/\/+$/, ""),
+    token,
+    redact,
+    redactPatterns,
+  };
+}

package/src/index.ts

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { loadConfig } from "./config.js";
+import { SwarmpitClient } from "./client.js";
+import { setExtraRedactPatterns } from "./sanitize.js";
+import { registerAllTools } from "./tools/register.js";
+
+async function checkConnection(url: string, token: string): Promise<void> {
+  const client = new SwarmpitClient(url, token, 10_000);
+  try {
+    await client.listNodes();
+    console.error(`mcp-swarmpit: connected to ${url}`);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(`mcp-swarmpit: WARNING — cannot reach ${url}: ${msg}`);
+    console.error(`mcp-swarmpit: tools will be available but API calls may fail`);
+  }
+}
+
+async function main() {
+  const config = loadConfig();
+
+  if (config.redactPatterns.length > 0) {
+    setExtraRedactPatterns(config.redactPatterns);
+    console.error(`mcp-swarmpit: extra redact patterns: ${config.redactPatterns.join(", ")}`);
+  }
+
+  await checkConnection(config.url, config.token);
+
+  const server = new McpServer({
+    name: "mcp-swarmpit",
+    version: "0.1.0",
+  });
+
+  registerAllTools(server, config);
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("mcp-swarmpit: running on stdio");
+}
+
+main().catch((err) => {
+  console.error("mcp-swarmpit fatal:", err);
+  process.exit(1);
+});
+
+process.on("SIGINT", () => process.exit(0));