@koller-nexus/vps-ops-mcp 0.1.0

package/src/index.ts

@@ -0,0 +1,73 @@
+#!/usr/bin/env bun
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { loadConfig } from "./config.js";
+import { buildReadonlyTools, type ToolDef } from "./tools/readonly.js";
+import { buildMutationTools } from "./tools/mutations.js";
+import type { SshResult } from "./ssh.js";
+
+function resultToText(result: SshResult): string {
+  return JSON.stringify(result, null, 2);
+}
+
+function registerAll(server: McpServer, tools: ToolDef[]): void {
+  for (const tool of tools) {
+    server.registerTool(
+      tool.name,
+      {
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+      },
+      async (args: unknown) => {
+        try {
+          const parsed = tool.inputSchema.parse(args ?? {});
+          const result = await tool.handler(parsed as Record<string, unknown>);
+          return {
+            content: [{ type: "text" as const, text: resultToText(result) }],
+            isError: result.exit_code !== 0,
+          };
+        } catch (err) {
+          const msg = err instanceof Error ? err.message : String(err);
+          const failed: SshResult = {
+            exit_code: 1,
+            stdout: "",
+            stderr: msg,
+            duration_ms: 0,
+            truncated: false,
+          };
+          return {
+            content: [{ type: "text" as const, text: resultToText(failed) }],
+            isError: true,
+          };
+        }
+      }
+    );
+  }
+}
+
+async function main(): Promise<void> {
+  let config;
+  try {
+    config = loadConfig();
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(`[vps-ops] Fatal config error: ${msg}`);
+    process.exit(1);
+  }
+
+  const tools: ToolDef[] = [
+    ...buildReadonlyTools(config),
+    ...buildMutationTools(config),
+  ];
+
+  const server = new McpServer({ name: "vps-ops", version: "0.1.0" });
+  registerAll(server, tools);
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch((err) => {
+  console.error("[vps-ops] Unhandled error:", err);
+  process.exit(1);
+});

package/src/mcp-registry.test.ts

@@ -0,0 +1,58 @@
+import { expect, test } from "bun:test";
+import { resolve } from "node:path";
+
+const root = resolve(import.meta.dir, "..");
+const packagePath = resolve(root, "package.json");
+const serverJsonPath = resolve(root, "server.json");
+const versionPath = resolve(root, "VERSION");
+
+const NPM_NAME = "@koller-nexus/vps-ops-mcp";
+const MCP_NAME = "io.github.koller-nexus/vps-ops-mcp";
+const REPO_URL = "https://github.com/koller-nexus/vps-ops-mcp";
+
+const REQUIRED_ENV = [
+  "VPS_SSH_KEY_PATH",
+  "VPS_HOST",
+  "VPS_USER",
+  "VPS_PORT",
+  "VPS_ALLOW_MUTATIONS",
+] as const;
+
+test("package.json is a public npm package with matching mcpName", async () => {
+  const pkg = await Bun.file(packagePath).json();
+  const version = (await Bun.file(versionPath).text()).trim();
+
+  expect(pkg.private).toBeUndefined();
+  expect(pkg.name).toBe(NPM_NAME);
+  expect(pkg.mcpName).toBe(MCP_NAME);
+  expect(pkg.version).toBe(version);
+  expect(pkg.repository?.url).toContain(REPO_URL);
+  expect(pkg.bin?.["vps-ops-mcp"]).toBe("src/index.ts");
+  expect(pkg.publishConfig?.access).toBe("public");
+});
+
+test("server.json matches package.json and lists required env names", async () => {
+  const pkg = await Bun.file(packagePath).json();
+  const server = await Bun.file(serverJsonPath).json();
+
+  expect(await Bun.file(serverJsonPath).exists()).toBe(true);
+  expect(server.name).toBe(pkg.mcpName);
+  expect(server.version).toBe(pkg.version);
+  expect(server.description.length).toBeLessThanOrEqual(100);
+
+  const npm = server.packages?.[0];
+  expect(npm.registryType).toBe("npm");
+  expect(npm.identifier).toBe(pkg.name);
+  expect(npm.version).toBe(pkg.version);
+  expect(npm.transport?.type).toBe("stdio");
+  expect(npm.runtimeHint).toBe("bunx");
+
+  const envNames = (npm.environmentVariables ?? []).map((e: { name: string }) => e.name);
+  for (const name of REQUIRED_ENV) {
+    expect(envNames).toContain(name);
+  }
+
+  const keyPath = npm.environmentVariables.find((e: { name: string }) => e.name === "VPS_SSH_KEY_PATH");
+  expect(keyPath.isRequired).toBe(true);
+  expect(keyPath.isSecret).toBe(true);
+});

package/src/opensource-governance.test.ts

@@ -0,0 +1,113 @@
+import { expect, test } from "bun:test";
+import { resolve } from "node:path";
+
+const root = resolve(import.meta.dir, "..");
+const contributingPath = resolve(root, "CONTRIBUTING.md");
+const issuePath = resolve(root, "ISSUE.md");
+const licensePath = resolve(root, "LICENSE");
+const workflowPath = resolve(root, ".github", "workflows", "pull_request.yml");
+const envExamplePath = resolve(root, ".env.example");
+const readmePath = resolve(root, "README.md");
+
+const CONTRIBUTING_HEADINGS = [
+  "# Contributing",
+  "## Branch names",
+  "## Pull requests",
+  "## Verification",
+  "## Issues",
+] as const;
+
+const CONTRIBUTING_TOKENS = [
+  "feature/",
+  "fix/",
+  "refactor/",
+  "main",
+  "pull request",
+  "ISSUE.md",
+  "bun test",
+  "bun run build",
+  "Conventional Commits",
+] as const;
+
+const ISSUE_HEADINGS = [
+  "# Filing an issue",
+  "## Summary",
+  "## Type",
+  "## Expected versus actual",
+  "## Reproduction or acceptance",
+  "## Environment",
+] as const;
+
+const ISSUE_TOKENS = ["bug", "feature", "CONTRIBUTING.md"] as const;
+
+const LICENSE_TOKENS = [
+  "MIT License",
+  "Permission is hereby granted, free of charge",
+  "2026",
+  'THE SOFTWARE IS PROVIDED "AS IS"',
+] as const;
+
+const LIVE_HOST = "64.181.163.182";
+
+async function loadRequired(path: string, label: string): Promise<string> {
+  const file = Bun.file(path);
+  if (!(await file.exists())) {
+    throw new Error(`${label} is missing`);
+  }
+  return file.text();
+}
+
+function expectHeadings(text: string, headings: readonly string[]): void {
+  let cursor = -1;
+  for (const heading of headings) {
+    const at = text.indexOf(heading);
+    expect(at, heading).toBeGreaterThan(cursor);
+    cursor = at;
+  }
+}
+
+function expectTokens(text: string, tokens: readonly string[]): void {
+  for (const token of tokens) {
+    expect(text.includes(token), token).toBe(true);
+  }
+}
+
+test("root contribution files exist", async () => {
+  expect(await Bun.file(contributingPath).exists()).toBe(true);
+  expect(await Bun.file(issuePath).exists()).toBe(true);
+  expect(await Bun.file(licensePath).exists()).toBe(true);
+});
+
+test("pull request workflow runs test then build", async () => {
+  const workflow = await loadRequired(workflowPath, "pull_request.yml");
+  expect(workflow).toContain("pull_request");
+  expect(workflow).toContain("Test and build");
+  const testAt = workflow.indexOf("bun test");
+  const buildAt = workflow.indexOf("bun run build");
+  expect(testAt).toBeGreaterThan(-1);
+  expect(buildAt).toBeGreaterThan(testAt);
+});
+
+test("CONTRIBUTING.md matches the contribution contract", async () => {
+  const text = await loadRequired(contributingPath, "CONTRIBUTING.md");
+  expectHeadings(text, CONTRIBUTING_HEADINGS);
+  expectTokens(text, CONTRIBUTING_TOKENS);
+});
+
+test("ISSUE.md matches the issue-filing contract", async () => {
+  const text = await loadRequired(issuePath, "ISSUE.md");
+  expectHeadings(text, ISSUE_HEADINGS);
+  expectTokens(text, ISSUE_TOKENS);
+});
+
+test("LICENSE is MIT", async () => {
+  const text = await loadRequired(licensePath, "LICENSE");
+  expectTokens(text, LICENSE_TOKENS);
+});
+
+test("example env and README omit the live host address", async () => {
+  const envExample = await loadRequired(envExamplePath, ".env.example");
+  const readme = await loadRequired(readmePath, "README.md");
+  expect(envExample.includes(LIVE_HOST)).toBe(false);
+  expect(readme.includes(LIVE_HOST)).toBe(false);
+});

package/src/ssh.test.ts

@@ -0,0 +1,10 @@
+import { test, expect } from "bun:test";
+import { shellQuote } from "./ssh.js";
+
+test("quotes a simple token", () => {
+  expect(shellQuote("nginx")).toBe("'nginx'");
+});
+
+test("escapes single quotes for POSIX shells", () => {
+  expect(shellQuote("it's")).toBe(`'it'\\''s'`);
+});

package/src/ssh.ts

@@ -0,0 +1,108 @@
+import { spawn } from "node:child_process";
+import type { VpsConfig } from "./config.js";
+
+export interface SshResult {
+  exit_code: number;
+  stdout: string;
+  stderr: string;
+  duration_ms: number;
+  truncated: boolean;
+}
+
+function truncate(text: string, maxBytes: number): { text: string; truncated: boolean } {
+  const buf = Buffer.from(text, "utf8");
+  if (buf.length <= maxBytes) return { text, truncated: false };
+  const sliced = buf.subarray(0, maxBytes).toString("utf8");
+  return {
+    text: sliced + `\n…[truncated ${buf.length - maxBytes} bytes]`,
+    truncated: true,
+  };
+}
+
+export function runSsh(
+  config: VpsConfig,
+  remoteCommand: string,
+  timeoutMs?: number
+): Promise<SshResult> {
+  const timeout = timeoutMs ?? config.commandTimeoutMs;
+  const started = Date.now();
+
+  const args = [
+    "-i",
+    config.sshKeyPath,
+    "-o",
+    "BatchMode=yes",
+    "-o",
+    "IdentitiesOnly=yes",
+    "-o",
+    "StrictHostKeyChecking=accept-new",
+    "-p",
+    String(config.port),
+    `${config.user}@${config.host}`,
+    "--",
+    remoteCommand,
+  ];
+
+  return new Promise((resolve) => {
+    const child = spawn("ssh", args, {
+      env: process.env,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+
+    let stdout = "";
+    let stderr = "";
+    let killed = false;
+
+    const timer = setTimeout(() => {
+      killed = true;
+      child.kill("SIGKILL");
+    }, timeout);
+
+    child.stdout.on("data", (chunk: Buffer) => {
+      stdout += chunk.toString("utf8");
+    });
+    child.stderr.on("data", (chunk: Buffer) => {
+      stderr += chunk.toString("utf8");
+    });
+
+    child.on("error", (err) => {
+      clearTimeout(timer);
+      const duration_ms = Date.now() - started;
+      const out = truncate(stdout, config.logMaxBytes);
+      const errT = truncate(
+        stderr + (stderr ? "\n" : "") + String(err),
+        config.logMaxBytes
+      );
+      resolve({
+        exit_code: 127,
+        stdout: out.text,
+        stderr: errT.text,
+        duration_ms,
+        truncated: out.truncated || errT.truncated,
+      });
+    });
+
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      const duration_ms = Date.now() - started;
+      if (killed) {
+        stderr +=
+          (stderr ? "\n" : "") +
+          `Command timed out after ${timeout}ms and was killed.`;
+      }
+      const out = truncate(stdout, config.logMaxBytes);
+      const errT = truncate(stderr, config.logMaxBytes);
+      resolve({
+        exit_code: killed ? 124 : code ?? 1,
+        stdout: out.text,
+        stderr: errT.text,
+        duration_ms,
+        truncated: out.truncated || errT.truncated,
+      });
+    });
+  });
+}
+
+export function shellQuote(s: string): string {
+  return `'${s.replace(/'/g, `'\\''`)}'`;
+}

package/src/tools/mutations.test.ts

@@ -0,0 +1,60 @@
+import { test, expect } from "bun:test";
+import type { VpsConfig } from "../config.js";
+import { buildMutationTools } from "./mutations.js";
+
+const disabled: VpsConfig = {
+  host: "127.0.0.1",
+  user: "ubuntu",
+  port: 22,
+  sshKeyPath: "/tmp/unused-key",
+  commandTimeoutMs: 30_000,
+  logMaxBytes: 200_000,
+  allowMutations: false,
+};
+
+const enabled: VpsConfig = { ...disabled, allowMutations: true };
+
+const mutationNames = [
+  "docker_restart",
+  "docker_stop",
+  "docker_start",
+  "compose_up",
+  "compose_restart",
+  "compose_pull_up",
+  "docker_rm",
+  "disk_cleanup_docker",
+] as const;
+
+test.each([...mutationNames])("exposes mutation tool %s", (name) => {
+  const tool = buildMutationTools(enabled).find((t) => t.name === name);
+  expect(tool).toBeDefined();
+  expect(tool?.mutation).toBe(true);
+});
+
+test("refuses mutations when VPS_ALLOW_MUTATIONS is false", async () => {
+  const tool = buildMutationTools(disabled).find((t) => t.name === "docker_restart");
+  await expect(tool!.handler({ name: "web", confirm: true })).rejects.toThrow(
+    /Mutations disabled/
+  );
+});
+
+test("refuses mutations without confirm:true", async () => {
+  const tool = buildMutationTools(enabled).find((t) => t.name === "docker_stop");
+  await expect(tool!.handler({ name: "web", confirm: false })).rejects.toThrow(
+    /Mutation refused/
+  );
+});
+
+test("docker_rm requires force_name to match name", async () => {
+  const tool = buildMutationTools(enabled).find((t) => t.name === "docker_rm");
+  await expect(
+    tool!.handler({ name: "web", force_name: "other", confirm: true })
+  ).rejects.toThrow(/force_name/);
+});
+
+test("rejects unsafe docker mutation names before SSH", async () => {
+  const tool = buildMutationTools(enabled).find((t) => t.name === "docker_start");
+  await expect(
+    tool!.handler({ name: "web; rm -rf /", confirm: true })
+  ).rejects.toThrow(/Invalid name/);
+});

package/src/tools/mutations.ts

@@ -0,0 +1,209 @@
+import { z } from "zod";
+import type { VpsConfig } from "../config.js";
+import { runSsh, shellQuote, type SshResult } from "../ssh.js";
+import { assertContainerOrServiceName } from "../validate.js";
+import { resolveComposeDir, type ToolDef } from "./readonly.js";
+
+function requireConfirm(args: Record<string, unknown>): void {
+  if (args.confirm !== true) {
+    throw new Error(
+      "Mutation refused: set confirm:true to proceed (and ensure VPS_ALLOW_MUTATIONS is not false)."
+    );
+  }
+}
+
+function requireMutationsAllowed(config: VpsConfig): void {
+  if (!config.allowMutations) {
+    throw new Error(
+      "Mutations disabled: VPS_ALLOW_MUTATIONS=false. Only readonly tools are available."
+    );
+  }
+}
+
+async function gated(
+  config: VpsConfig,
+  args: Record<string, unknown>,
+  fn: () => Promise<SshResult>
+): Promise<SshResult> {
+  requireMutationsAllowed(config);
+  requireConfirm(args);
+  return fn();
+}
+
+const confirmField = z
+  .literal(true)
+  .describe("Must be true to execute this mutation");
+
+export function buildMutationTools(config: VpsConfig): ToolDef[] {
+  return [
+    {
+      name: "docker_restart",
+      description: "docker restart NAME. Requires confirm:true.",
+      mutation: true,
+      inputSchema: z.object({ name: z.string(), confirm: confirmField }),
+      handler: async (args) =>
+        gated(config, args, () => {
+          const name = assertContainerOrServiceName(String(args.name));
+          return runSsh(config, `docker restart ${shellQuote(name)}`);
+        }),
+    },
+    {
+      name: "docker_stop",
+      description: "docker stop NAME. Requires confirm:true.",
+      mutation: true,
+      inputSchema: z.object({ name: z.string(), confirm: confirmField }),
+      handler: async (args) =>
+        gated(config, args, () => {
+          const name = assertContainerOrServiceName(String(args.name));
+          return runSsh(config, `docker stop ${shellQuote(name)}`);
+        }),
+    },
+    {
+      name: "docker_start",
+      description: "docker start NAME. Requires confirm:true.",
+      mutation: true,
+      inputSchema: z.object({ name: z.string(), confirm: confirmField }),
+      handler: async (args) =>
+        gated(config, args, () => {
+          const name = assertContainerOrServiceName(String(args.name));
+          return runSsh(config, `docker start ${shellQuote(name)}`);
+        }),
+    },
+    {
+      name: "compose_up",
+      description:
+        "docker compose up -d [services…]. Requires confirm:true. dir or VPS_COMPOSE_DIR.",
+      mutation: true,
+      inputSchema: z.object({
+        dir: z.string().optional(),
+        services: z.array(z.string()).optional(),
+        confirm: confirmField,
+      }),
+      handler: async (args) =>
+        gated(config, args, () => {
+          const dir = resolveComposeDir(
+            config,
+            args.dir !== undefined ? String(args.dir) : undefined
+          );
+          const services = Array.isArray(args.services)
+            ? (args.services as string[]).map((s) =>
+                assertContainerOrServiceName(s, "service")
+              )
+            : [];
+          const svc =
+            services.length > 0
+              ? " " + services.map(shellQuote).join(" ")
+              : "";
+          return runSsh(
+            config,
+            `cd ${shellQuote(dir)} && docker compose up -d${svc}`
+          );
+        }),
+    },
+    {
+      name: "compose_restart",
+      description:
+        "docker compose restart [services…]. Requires confirm:true.",
+      mutation: true,
+      inputSchema: z.object({
+        dir: z.string().optional(),
+        services: z.array(z.string()).optional(),
+        confirm: confirmField,
+      }),
+      handler: async (args) =>
+        gated(config, args, () => {
+          const dir = resolveComposeDir(
+            config,
+            args.dir !== undefined ? String(args.dir) : undefined
+          );
+          const services = Array.isArray(args.services)
+            ? (args.services as string[]).map((s) =>
+                assertContainerOrServiceName(s, "service")
+              )
+            : [];
+          const svc =
+            services.length > 0
+              ? " " + services.map(shellQuote).join(" ")
+              : "";
+          return runSsh(
+            config,
+            `cd ${shellQuote(dir)} && docker compose restart${svc}`
+          );
+        }),
+    },
+    {
+      name: "compose_pull_up",
+      description:
+        "docker compose pull then up -d [services…]. Requires confirm:true.",
+      mutation: true,
+      inputSchema: z.object({
+        dir: z.string().optional(),
+        services: z.array(z.string()).optional(),
+        confirm: confirmField,
+      }),
+      handler: async (args) =>
+        gated(config, args, () => {
+          const dir = resolveComposeDir(
+            config,
+            args.dir !== undefined ? String(args.dir) : undefined
+          );
+          const services = Array.isArray(args.services)
+            ? (args.services as string[]).map((s) =>
+                assertContainerOrServiceName(s, "service")
+              )
+            : [];
+          const svc =
+            services.length > 0
+              ? " " + services.map(shellQuote).join(" ")
+              : "";
+          return runSsh(
+            config,
+            `cd ${shellQuote(dir)} && docker compose pull${svc} && docker compose up -d${svc}`
+          );
+        }),
+    },
+    {
+      name: "docker_rm",
+      description:
+        "docker rm -f NAME. Requires confirm:true AND force_name === name.",
+      mutation: true,
+      inputSchema: z.object({
+        name: z.string(),
+        force_name: z
+          .string()
+          .describe("Must equal name exactly (double confirmation)"),
+        confirm: confirmField,
+      }),
+      handler: async (args) =>
+        gated(config, args, () => {
+          const name = assertContainerOrServiceName(String(args.name));
+          const forceName = String(args.force_name ?? "");
+          if (forceName !== name) {
+            throw new Error(
+              `docker_rm refused: force_name ("${forceName}") must equal name ("${name}")`
+            );
+          }
+          return runSsh(config, `docker rm -f ${shellQuote(name)}`);
+        }),
+    },
+    {
+      name: "disk_cleanup_docker",
+      description:
+        "docker system prune -f; volumes only if confirm_volumes:true. Requires confirm:true.",
+      mutation: true,
+      inputSchema: z.object({
+        confirm: confirmField,
+        confirm_volumes: z
+          .boolean()
+          .optional()
+          .describe("If true, also prune unused volumes (--volumes)"),
+      }),
+      handler: async (args) =>
+        gated(config, args, () => {
+          const volumes =
+            args.confirm_volumes === true ? " --volumes" : "";
+          return runSsh(config, `docker system prune -f${volumes}`);
+        }),
+    },
+  ];
+}

package/src/tools/readonly.test.ts

@@ -0,0 +1,60 @@
+import { test, expect } from "bun:test";
+import type { VpsConfig } from "../config.js";
+import { buildReadonlyTools, resolveComposeDir } from "./readonly.js";
+
+const config: VpsConfig = {
+  host: "127.0.0.1",
+  user: "ubuntu",
+  port: 22,
+  sshKeyPath: "/tmp/unused-key",
+  commandTimeoutMs: 30_000,
+  logMaxBytes: 200_000,
+  allowMutations: false,
+};
+
+test("exposes docker_service_ls as a readonly swarm service list", () => {
+  const tool = buildReadonlyTools(config).find((t) => t.name === "docker_service_ls");
+  expect(tool).toBeDefined();
+  expect(tool?.mutation).toBeFalsy();
+  expect(tool?.inputSchema.parse({})).toEqual({});
+});
+
+const dailyDebugTools = [
+  "host_listen",
+  "host_failed_units",
+  "host_top",
+  "host_dmesg",
+  "docker_node_ls",
+] as const;
+
+test.each([...dailyDebugTools])("exposes readonly debug tool %s", (name) => {
+  const tool = buildReadonlyTools(config).find((t) => t.name === name);
+  expect(tool).toBeDefined();
+  expect(tool?.mutation).toBeFalsy();
+});
+
+test("host_dmesg accepts optional n", () => {
+  const tool = buildReadonlyTools(config).find((t) => t.name === "host_dmesg");
+  expect(tool?.inputSchema.parse({})).toEqual({});
+  expect(tool?.inputSchema.parse({ n: 50 })).toEqual({ n: 50 });
+});
+
+test("resolveComposeDir uses argument or config and rejects missing dir", () => {
+  expect(resolveComposeDir({ ...config, composeDir: "/opt/stack" })).toBe(
+    "/opt/stack"
+  );
+  expect(resolveComposeDir(config, "/srv/app")).toBe("/srv/app");
+  expect(() => resolveComposeDir(config)).toThrow(/compose dir required/);
+});
+
+test("vps_journal rejects units outside the allowlist before SSH", async () => {
+  const tool = buildReadonlyTools(config).find((t) => t.name === "vps_journal");
+  await expect(tool!.handler({ unit: "nginx" })).rejects.toThrow(/not allowed/);
+});
+
+test("docker_logs rejects unsafe since values before SSH", async () => {
+  const tool = buildReadonlyTools(config).find((t) => t.name === "docker_logs");
+  await expect(
+    tool!.handler({ name: "web", since: "1h; cat /etc/shadow" })
+  ).rejects.toThrow(/Invalid since/);
+});