@havesomecode/kibana-mcp-server 1.1.2 → 1.2.1

package/dist/src/cli.js

@@ -1,5 +1,8 @@
 import { createInterface } from "node:readline/promises";
 import { Writable } from "node:stream";
+import { parseArgs } from "node:util";
+import { runBootstrap } from "./bootstrap.js";
+import { PROFILE_NAME_ENV } from "./config.js";
 import { startMcpServer } from "./mcp_runtime.js";
 import { runSetupFlow } from "./setup_flow.js";
 function renderHelp() {
@@ -10,9 +13,35 @@ function renderHelp() {
         "  kibana-mcp-server [command]",
         "",
         "Commands:",
-        "  setup    Run guided machine setup",
-        "  serve    Start the stdio MCP server",
-        "  help     Show this help output",
+        "  setup      Run guided machine setup",
+        "  bootstrap  Verify, save, and register a profile without prompts",
+        "  serve      Start the stdio MCP server",
+        "  help       Show this help output",
+    ].join("\n");
+}
+function renderBootstrapHelp() {
+    return [
+        "Usage:",
+        "  kibana-mcp-server bootstrap [options]",
+        "  kibana-mcp-server setup [options]  # compatible non-interactive alias",
+        "",
+        "Bootstrap verifies and saves only the Kibana connection; it does not inspect or configure indexes.",
+        "After installation, ask the agent to configure a specific index or index pattern.",
+        "",
+        "Connection options use KIBANA_BASE_URL, KIBANA_USERNAME, and KIBANA_PASSWORD as fallbacks.",
+        "Passwords are accepted only through --password-stdin, --password-env <NAME>, or KIBANA_PASSWORD.",
+        "",
+        "Options:",
+        "  --profile <name>        Saved profile name (default: KIBANA_PROFILE or default)",
+        "  --url <url>             Kibana base URL",
+        "  --username <name>       Kibana basic-auth username",
+        "  --password-stdin        Read the password from stdin",
+        "  --password-env <name>   Read the password from a named environment variable",
+        "  --client <codex|none>   Register Codex or skip client registration (default: codex)",
+        "  --package <specifier>   Exact package specifier used by the Codex registration",
+        "  --mcp-name <name>       Base name for the transport-hashed Codex registration",
+        "  --replace               Explicitly replace an existing catalog with an empty managed catalog",
+        "  --no-default            Do not make this profile the default",
     ].join("\n");
 }
 export async function runCli(argv = process.argv.slice(2), io = {}, dependencies = {}) {
@@ -20,13 +49,35 @@ export async function runCli(argv = process.argv.slice(2), io = {}, dependencies
     const stderr = io.stderr ?? ((text) => process.stderr.write(`${text}\n`));
     const stdin = io.stdin ?? process.stdin;
     const stdoutStream = io.stdoutStream ?? process.stdout;
+    const env = io.env ?? process.env;
     const [command, ...rest] = argv;
     switch (command) {
-        case undefined:
+        case undefined: {
+            try {
+                await (dependencies.startMcpServerFn ?? startMcpServer)(env);
+                return 0;
+            }
+            catch (error) {
+                stderr(error instanceof Error ? error.message : String(error));
+                return 1;
+            }
+        }
         case "setup": {
             if (rest.length > 0) {
-                stderr(`Unknown arguments for setup: ${rest.join(" ")}`);
-                return 1;
+                if (rest.includes("--help") || rest.includes("-h")) {
+                    stdout(renderBootstrapHelp());
+                    return 0;
+                }
+                try {
+                    const options = await parseBootstrapOptions(rest, stdin, env);
+                    const result = await (dependencies.runBootstrapFn ?? runBootstrap)(options);
+                    stdout(renderBootstrapResult(result));
+                    return 0;
+                }
+                catch (error) {
+                    stderr(error instanceof Error ? error.message : String(error));
+                    return 1;
+                }
             }
             const promptIo = await createPromptIo(stdout, {
                 stdin,
@@ -48,12 +99,39 @@ export async function runCli(argv = process.argv.slice(2), io = {}, dependencies
             stdout(renderHelp());
             return 0;
         }
+        case "bootstrap": {
+            if (rest.includes("--help") || rest.includes("-h")) {
+                stdout(renderBootstrapHelp());
+                return 0;
+            }
+            try {
+                const options = await parseBootstrapOptions(rest, stdin, env);
+                const result = await (dependencies.runBootstrapFn ?? runBootstrap)(options);
+                stdout(renderBootstrapResult(result));
+                return 0;
+            }
+            catch (error) {
+                stderr(error instanceof Error ? error.message : String(error));
+                return 1;
+            }
+        }
         case "serve": {
-            if (rest.length > 0) {
-                stderr(`Unknown arguments for serve: ${rest.join(" ")}`);
+            try {
+                const { values } = parseArgs({
+                    args: rest,
+                    allowPositionals: false,
+                    strict: true,
+                    options: {
+                        profile: { type: "string" },
+                    },
+                });
+                const serveEnv = values.profile ? { ...env, [PROFILE_NAME_ENV]: values.profile } : env;
+                await (dependencies.startMcpServerFn ?? startMcpServer)(serveEnv);
+            }
+            catch (error) {
+                stderr(error instanceof Error ? error.message : String(error));
                 return 1;
             }
-            await (dependencies.startMcpServerFn ?? startMcpServer)();
             return 0;
         }
         default: {
@@ -63,6 +141,91 @@ export async function runCli(argv = process.argv.slice(2), io = {}, dependencies
         }
     }
 }
+async function parseBootstrapOptions(args, stdin, env) {
+    const { values } = parseArgs({
+        args,
+        allowPositionals: false,
+        strict: true,
+        options: {
+            profile: { type: "string" },
+            url: { type: "string" },
+            username: { type: "string" },
+            "password-stdin": { type: "boolean" },
+            "password-env": { type: "string" },
+            timeout: { type: "string" },
+            client: { type: "string" },
+            package: { type: "string" },
+            "mcp-name": { type: "string" },
+            replace: { type: "boolean" },
+            "no-default": { type: "boolean" },
+        },
+    });
+    const baseUrl = values.url?.trim() || env.KIBANA_BASE_URL?.trim();
+    if (!baseUrl) {
+        throw new Error("Kibana base URL is required via --url or KIBANA_BASE_URL.");
+    }
+    const username = values.username?.trim() || env.KIBANA_USERNAME?.trim();
+    if (!username) {
+        throw new Error("Kibana username is required via --username or KIBANA_USERNAME.");
+    }
+    if (values["password-stdin"] && values["password-env"]) {
+        throw new Error("Use only one of --password-stdin or --password-env.");
+    }
+    let password;
+    if (values["password-stdin"]) {
+        password = (await readAllInput(stdin)).replace(/\r?\n$/, "");
+    }
+    else if (values["password-env"]) {
+        password = env[values["password-env"]];
+        if (password === undefined) {
+            throw new Error(`Password environment variable '${values["password-env"]}' is not set.`);
+        }
+    }
+    else {
+        password = env.KIBANA_PASSWORD;
+    }
+    if (!password) {
+        throw new Error("Kibana password is required via --password-stdin, --password-env, or KIBANA_PASSWORD.");
+    }
+    const client = values.client ?? "codex";
+    if (client !== "codex" && client !== "none") {
+        throw new Error("--client must be either 'codex' or 'none'.");
+    }
+    const timeoutMs = values.timeout === undefined ? undefined : Number(values.timeout);
+    if (timeoutMs !== undefined && !Number.isFinite(timeoutMs)) {
+        throw new Error("--timeout must be a number of milliseconds.");
+    }
+    return {
+        profileName: values.profile?.trim() || env[PROFILE_NAME_ENV]?.trim() || "default",
+        baseUrl,
+        username,
+        password,
+        client,
+        packageSpecifier: values.package,
+        mcpName: values["mcp-name"],
+        makeDefault: !values["no-default"],
+        replaceExisting: values.replace ?? false,
+        timeoutMs,
+    };
+}
+function renderBootstrapResult(result) {
+    return [
+        `Bootstrap verified for profile '${result.profileName}'.`,
+        result.sourceCount === 0
+            ? "Source catalog is empty. No Kibana indexes were inspected or configured. Ask the user which index or index pattern to configure before querying logs."
+            : `Preserved ${result.sourceCount} explicitly configured source${result.sourceCount === 1 ? "" : "s"}; bootstrap did not inspect them.`,
+        result.registered
+            ? `Codex MCP registration is installed and verified for profile '${result.profileName}'.`
+            : "Client registration was skipped by request.",
+    ].join("\n");
+}
+async function readAllInput(stdin) {
+    let rawInput = "";
+    for await (const chunk of stdin) {
+        rawInput += typeof chunk === "string" ? chunk : chunk.toString("utf8");
+    }
+    return rawInput;
+}
 export async function createPromptIo(stdout, options = {}) {
     const stdin = options.stdin ?? process.stdin;
     const stdoutStream = options.stdoutStream ?? process.stdout;

package/dist/src/client_registration.js

@@ -0,0 +1,197 @@
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+export function deriveCodexRegistrationName(options) {
+    const transport = [
+        "npx",
+        "-y",
+        options.packageSpecifier,
+        "serve",
+        "--profile",
+        options.profileName,
+    ];
+    const suffix = createHash("sha256").update(JSON.stringify(transport)).digest("hex").slice(0, 12);
+    return `${options.mcpName}-${suffix}`;
+}
+export class CodexClientRegistrar {
+    options;
+    runner;
+    preflightResult;
+    rollbackEligible = false;
+    constructor(options, runner = runCommand) {
+        this.options = options;
+        this.runner = runner;
+    }
+    get registrationName() {
+        return deriveCodexRegistrationName(this.options);
+    }
+    async preflight() {
+        const existing = await this.readRegistration();
+        if (!existing) {
+            this.preflightResult = { alreadyRegistered: false };
+            return this.preflightResult;
+        }
+        if (!this.matchesExpectedTransport(existing)) {
+            throw new Error(`Refusing to overwrite existing Codex MCP registration '${this.registrationName}' because its transport differs. Remove or rename it explicitly before retrying.`);
+        }
+        this.preflightResult = { alreadyRegistered: true };
+        return this.preflightResult;
+    }
+    async register() {
+        const preflight = this.preflightResult ?? (await this.preflight());
+        if (preflight.alreadyRegistered) {
+            return { added: false };
+        }
+        let addResult;
+        try {
+            addResult = await this.runner("codex", [
+                "mcp",
+                "add",
+                this.registrationName,
+                "--",
+                ...this.expectedCommand(),
+            ]);
+        }
+        catch (error) {
+            return await this.reconcileAmbiguousAdd(error);
+        }
+        if (addResult.exitCode !== 0) {
+            return await this.reconcileAmbiguousAdd(new Error(`Codex MCP registration failed: ${addResult.stderr.trim() || addResult.stdout.trim() || `exit code ${addResult.exitCode}`}`));
+        }
+        this.rollbackEligible = true;
+        const registered = await this.readRegistration();
+        if (!registered || !this.matchesExpectedTransport(registered)) {
+            // A different registration could have won a race. Never remove a transport
+            // whose exact ownership cannot be proven.
+            this.rollbackEligible = Boolean(registered && this.matchesExpectedTransport(registered));
+            throw new Error(`Codex MCP registration readback did not match the requested transport for '${this.registrationName}'. The mismatched registration was left untouched.`);
+        }
+        return { added: true };
+    }
+    async reconcileAmbiguousAdd(originalError) {
+        const registered = await this.readRegistration();
+        if (registered && this.matchesExpectedTransport(registered)) {
+            // The requested end-state exists, but another process may own it. Treat the
+            // operation as converged and never claim rollback ownership.
+            this.rollbackEligible = false;
+            return { added: true };
+        }
+        this.rollbackEligible = false;
+        if (registered) {
+            throw new Error(`Codex MCP registration '${this.registrationName}' changed concurrently and does not match the requested transport.`, { cause: originalError });
+        }
+        throw originalError;
+    }
+    async rollback() {
+        if (!this.rollbackEligible) {
+            return;
+        }
+        const current = await this.readRegistration();
+        if (!current) {
+            this.rollbackEligible = false;
+            return;
+        }
+        if (!this.matchesExpectedTransport(current)) {
+            this.rollbackEligible = false;
+            throw new Error(`Refusing to roll back Codex MCP registration '${this.registrationName}' because its transport no longer matches this bootstrap.`);
+        }
+        const removeResult = await this.runner("codex", ["mcp", "remove", this.registrationName]);
+        if (removeResult.exitCode !== 0) {
+            throw new Error(`Could not roll back Codex MCP registration '${this.registrationName}': ${removeResult.stderr.trim() || removeResult.stdout.trim() || `exit code ${removeResult.exitCode}`}`);
+        }
+        const remaining = await this.readRegistration();
+        if (!remaining || !this.matchesExpectedTransport(remaining)) {
+            this.rollbackEligible = false;
+            return;
+        }
+        throw new Error(`Could not confirm removal of Codex MCP registration '${this.registrationName}'.`);
+    }
+    expectedCommand() {
+        return [
+            "npx",
+            "-y",
+            this.options.packageSpecifier,
+            "serve",
+            "--profile",
+            this.options.profileName,
+        ];
+    }
+    matchesExpectedTransport(config) {
+        const [command, ...args] = this.expectedCommand();
+        return (config.enabled === true &&
+            config.transport?.type === "stdio" &&
+            config.transport.command === command &&
+            Array.isArray(config.transport.args) &&
+            config.transport.args.every((value) => typeof value === "string") &&
+            JSON.stringify(config.transport.args) === JSON.stringify(args) &&
+            isEmptyValue(config.transport.cwd) &&
+            isEmptyEnvironment(config.transport.env) &&
+            isEmptyStringArray(config.transport.env_vars) &&
+            hasOnlyKeys(config.transport, ["type", "command", "args", "cwd", "env", "env_vars"]));
+    }
+    async readRegistration() {
+        const result = await this.runner("codex", ["mcp", "get", this.registrationName, "--json"]);
+        if (result.exitCode !== 0) {
+            const message = `${result.stderr}\n${result.stdout}`.toLowerCase();
+            if (message.includes("not found") || message.includes("no mcp server")) {
+                return null;
+            }
+            throw new Error(`Could not inspect Codex MCP registration '${this.registrationName}': ${result.stderr.trim() || result.stdout.trim() || `exit code ${result.exitCode}`}`);
+        }
+        try {
+            return JSON.parse(result.stdout);
+        }
+        catch {
+            throw new Error(`Codex MCP registration '${this.registrationName}' returned invalid JSON during readback.`);
+        }
+    }
+}
+function isEmptyValue(value) {
+    return value === undefined || value === null;
+}
+function isEmptyEnvironment(value) {
+    return (isEmptyValue(value) ||
+        (typeof value === "object" && value !== null && Object.keys(value).length === 0));
+}
+function isEmptyStringArray(value) {
+    return isEmptyValue(value) || (Array.isArray(value) && value.length === 0);
+}
+function hasOnlyKeys(value, allowedKeys) {
+    const allowed = new Set(allowedKeys);
+    return Object.keys(value).every((key) => allowed.has(key));
+}
+async function runCommand(command, args) {
+    return await new Promise((resolve, reject) => {
+        const child = spawn(command, args, { stdio: "pipe" });
+        let stdout = "";
+        let stderr = "";
+        let settled = false;
+        const finish = (callback) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timeout);
+            callback();
+        };
+        const timeout = setTimeout(() => {
+            child.kill("SIGTERM");
+            finish(() => reject(new Error(`Command '${command}' timed out after 30000ms.`)));
+        }, 30000);
+        child.stdout.setEncoding("utf8");
+        child.stderr.setEncoding("utf8");
+        child.stdout.on("data", (chunk) => {
+            stdout += chunk;
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr += chunk;
+        });
+        child.on("error", (error) => {
+            finish(() => reject(new Error(error && typeof error === "object" && "code" in error && error.code === "ENOENT"
+                ? `Required command '${command}' is not installed or not available on PATH.`
+                : `Could not run '${command}': ${error.message}`)));
+        });
+        child.on("close", (exitCode) => {
+            finish(() => resolve({ stdout, stderr, exitCode: exitCode ?? 1 }));
+        });
+        child.stdin.end();
+    });
+}

package/dist/src/config.js

@@ -1,4 +1,5 @@
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { dirname } from "node:path";
 import { z } from "zod";
 import { ProfileStore } from "./profile_store.js";
@@ -71,8 +72,36 @@ export const sourceDefinitionSchema = z.object({
     defaultTextFields: z.array(z.string().min(1)).default([]),
     evidenceFields: z.array(z.string().min(1)).default([]),
 });
-export const sourceCatalogSchema = z.object({
-    sources: z.array(sourceDefinitionSchema).min(1),
+export const sourceCatalogSchema = z
+    .object({
+    generatedBy: z
+        .object({
+        tool: z.literal("@havesomecode/kibana-mcp-server"),
+        formatVersion: z.literal(1),
+        sourceHash: z.string().regex(/^[a-f0-9]{64}$/),
+    })
+        .optional(),
+    sources: z.array(sourceDefinitionSchema),
+})
+    .superRefine((catalog, context) => {
+    if (catalog.sources.length !== 0)
+        return;
+    if (!catalog.generatedBy) {
+        context.addIssue({
+            code: "custom",
+            path: ["sources"],
+            message: "Empty source catalogs must be managed by @havesomecode/kibana-mcp-server.",
+        });
+        return;
+    }
+    const expectedHash = createHash("sha256").update(JSON.stringify(catalog.sources)).digest("hex");
+    if (catalog.generatedBy.sourceHash !== expectedHash) {
+        context.addIssue({
+            code: "custom",
+            path: ["generatedBy", "sourceHash"],
+            message: "Empty source catalogs require valid managed provenance.",
+        });
+    }
 });
 function buildKibanaConfig(env) {
     return {
@@ -157,7 +186,17 @@ export async function loadConfigFromEnvironment(envInput = process.env, dependen
 export async function persistSourceCatalog(sources, options = {}) {
     const sourceCatalogPath = options.sourceCatalogPath ?? resolveSourceCatalogPath(options.envInput);
     await mkdir(dirname(sourceCatalogPath), { recursive: true });
-    await writeFile(sourceCatalogPath, `${JSON.stringify({ sources }, null, 2)}\n`, "utf8");
+    const temporaryPath = `${sourceCatalogPath}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporaryPath, `${JSON.stringify(options.catalog ?? { sources }, null, 2)}\n`, {
+            encoding: "utf8",
+            mode: 0o600,
+        });
+        await rename(temporaryPath, sourceCatalogPath);
+    }
+    finally {
+        await rm(temporaryPath, { force: true }).catch(() => { });
+    }
     return sourceCatalogPath;
 }
 function hasBootstrapConfig(envInput) {