Kastell

Instructions

Implementation Reference

• src/mcp/tools/serverGuard.ts:17-86 (handler)

  Main handler function for the 'server_guard' tool, executing actions 'start', 'stop', and 'status'.

  export async function handleServerGuard(params: {
    server?: string;
    action: "start" | "stop" | "status";
  }): Promise<McpResponse> {
    try {
      const servers = getServers();
      if (servers.length === 0) {
        return mcpError("No servers found", undefined, [
          { command: "kastell add", reason: "Add a server first" },
        ]);
      }
  
      const server = resolveServerForMcp(params, servers);
      if (!server) {
        if (params.server) {
          return mcpError(
            `Server not found: ${params.server}`,
            `Available servers: ${servers.map((s) => s.name).join(", ")}`,
          );
        }
        return mcpError(
          "Multiple servers found. Specify which server to use.",
          `Available: ${servers.map((s) => s.name).join(", ")}`,
        );
      }
  
      switch (params.action) {
        case "start": {
          const result = await startGuard(server.ip, server.name);
          if (!result.success) {
            return mcpError(result.error ?? "Failed to start guard", result.hint);
          }
          return mcpSuccess({
            success: true,
            message: `Guard installed on ${server.name}. Runs every 5 minutes via cron.`,
          });
        }
  
        case "stop": {
          const result = await stopGuard(server.ip, server.name);
          if (!result.success) {
            return mcpError(result.error ?? "Failed to stop guard", result.hint);
          }
          return mcpSuccess({
            success: true,
            message: `Guard removed from ${server.name}.`,
          });
        }
  
        case "status": {
          const result = await guardStatus(server.ip, server.name);
          if (!result.success) {
            return mcpError(result.error ?? "Failed to check guard status");
          }
          return mcpSuccess({
            isActive: result.isActive,
            lastRunAt: result.lastRunAt,
            breaches: result.breaches,
            logTail: result.logTail,
            installedAt: result.installedAt,
          });
        }
  
        default:
          return mcpError(`Invalid action: ${String(params.action)}`, "Valid actions: start, stop, status");
      }
    } catch (error: unknown) {
      return mcpError(getErrorMessage(error));
    }
  }

• src/mcp/tools/serverGuard.ts:12-15 (schema)

  Input validation schema for the 'server_guard' tool parameters.

  export const serverGuardSchema = {
    server: z.string().optional().describe("Server name or IP. Auto-selected if only one server exists."),
    action: z.enum(["start", "stop", "status"]).describe("Guard action: 'start' installs guard cron, 'stop' removes it, 'status' shows current state and recent breaches."),
  };

• src/mcp/server.ts:191-204 (registration)

  Tool registration for 'server_guard' in the MCP server setup.

  server.registerTool("server_guard", {
    description:
      "Manage autonomous security monitoring daemon on a server. Actions: 'start' installs guard as remote cron (checks disk/RAM/CPU/audit every 5 min), 'stop' removes guard cron entry, 'status' shows whether guard is active with last check time and any threshold breaches. Requires SSH access to target server.",
    inputSchema: serverGuardSchema,
    annotations: {
      title: "Guard Daemon",
      readOnlyHint: false,
      destructiveHint: false,
      idempotentHint: true,
      openWorldHint: true,
    },
  }, async (params) => {
    return handleServerGuard(params);
  });