@havesomecode/kibana-mcp-server 1.3.1 → 1.4.0

package/dist/src/commands/serve.js

@@ -1,15 +1,39 @@
-import { PROFILE_NAME_ENV } from "../config.js";
-import { startMcpServer } from "../mcp_runtime.js";
+import { CONFIG_FILE_ENV } from "../config/config_file.js";
+import { PROFILE_NAME_ENV } from "../config/environment.js";
+import { parsePort, startHttpMcpServer } from "../transports/http.js";
+import { startMcpServer } from "../transports/stdio.js";
 export default (program, context) => {
     program
         .command("serve")
-        .description("Start the stdio MCP server")
+        .description("Start the MCP server over stdio, or over Streamable HTTP with --http")
         .option("--profile <name>", "Saved profile name")
+        .option("--config <path>", "Configuration file, e.g. kibana.mcp.config.ts")
+        .option("--http", "Serve over Streamable HTTP instead of stdio")
+        .option("--host <host>", "HTTP listen host (default 127.0.0.1)")
+        .option("--port <port>", "HTTP listen port (default 3000)")
+        .option("--path <path>", "HTTP endpoint path (default /mcp)")
+        .option("--profile-header <name>", "HTTP header carrying the caller's profile")
         .action(async (options) => {
         try {
-            await (context.dependencies.startMcpServerFn ?? startMcpServer)(options.profile
-                ? { ...context.io.env, [PROFILE_NAME_ENV]: options.profile }
-                : context.io.env);
+            const env = {
+                ...context.io.env,
+                ...(options.profile ? { [PROFILE_NAME_ENV]: options.profile } : {}),
+                ...(options.config ? { [CONFIG_FILE_ENV]: options.config } : {}),
+            };
+            if (!options.http) {
+                if (options.host || options.port || options.path || options.profileHeader) {
+                    throw new Error("--host, --port, --path and --profile-header require --http.");
+                }
+                await (context.dependencies.startMcpServerFn ?? startMcpServer)(env);
+                return;
+            }
+            const { url } = await (context.dependencies.startHttpMcpServerFn ?? startHttpMcpServer)(env, {
+                host: options.host,
+                port: parsePort(options.port),
+                path: options.path,
+                profileHeader: options.profileHeader,
+            });
+            context.ui.success(`MCP server listening on ${url}`);
         }
         catch (error) {
             context.ui.error(error instanceof Error ? error.message : String(error));

package/dist/src/commands/setup.d.ts

@@ -0,0 +1,3 @@
+import { type Command } from "commander";
+import type { CliCommandContext } from "./context.js";
+export default function registerSetup(program: Command, context: CliCommandContext): void;

package/dist/src/commands/setup.js

@@ -1,6 +1,6 @@
 import { InvalidArgumentError, Option } from "commander";
-import { runBootstrap as runBootstrapFlow } from "../bootstrap.js";
-import { runSetupFlow } from "../setup_flow.js";
+import { runBootstrap as runBootstrapFlow } from "../setup/bootstrap.js";
+import { runSetupFlow } from "../setup/setup_flow.js";
 import { PromptCancelledError, createPromptIo } from "../utils/cli_prompts.js";
 export default function registerSetup(program, context) {
     const setupCommand = addOptions(program

package/dist/src/config/config_file.d.ts

@@ -0,0 +1,59 @@
+import type { CatalogStore } from "../stores/catalog_store.js";
+export { CatalogConflictError } from "../stores/catalog_store.js";
+export type { CatalogStore } from "../stores/catalog_store.js";
+export declare const CONFIG_FILE_ENV = "KIBANA_MCP_CONFIG";
+export declare const HTTP_HOST_ENV = "KIBANA_HTTP_HOST";
+export declare const HTTP_PORT_ENV = "KIBANA_HTTP_PORT";
+export declare const HTTP_PATH_ENV = "KIBANA_HTTP_PATH";
+export declare const HTTP_PROFILE_HEADER_ENV = "KIBANA_HTTP_PROFILE_HEADER";
+export declare const HTTP_AUTH_TOKEN_ENV = "KIBANA_HTTP_AUTH_TOKEN";
+export type CatalogStoreFactory<TStoreOptions> = (options?: TStoreOptions) => CatalogStore | Promise<CatalogStore>;
+export interface KibanaMcpConfig<TStoreOptions = Record<string, unknown>> {
+    /** Kibana base URL. Overridden by `KIBANA_BASE_URL`. */
+    url?: string;
+    /** Kibana user. Overridden by `KIBANA_USERNAME`. */
+    user?: string;
+    /** Kibana password. Overridden by `KIBANA_PASSWORD`. */
+    password?: string;
+    /** Backend deadline in milliseconds. Overridden by `KIBANA_TIMEOUT_MS`. */
+    timeoutMs?: number;
+    /** Profile served when the transport names none. Overridden by `KIBANA_PROFILE`. */
+    profile?: string;
+    /**
+     * Where the source catalogs are kept, one per profile: a store, or a store factory such as the
+     * default export of `stores/redis`, called with `storeOptions`. Without it, catalogs are files.
+     */
+    store?: CatalogStore | CatalogStoreFactory<TStoreOptions>;
+    /** Options handed to the `store` factory: connection, key prefix, anything the store defines. */
+    storeOptions?: TStoreOptions;
+    /** Streamable HTTP transport, used by `serve --http`. Flags and environment variables win. */
+    http?: {
+        host?: string;
+        port?: number;
+        path?: string;
+        /** Header carrying the profile of the caller. */
+        profileHeader?: string;
+        /** Shared secret expected as `Authorization: Bearer <token>`. */
+        authToken?: string;
+    };
+}
+type KibanaMcpConfigExport<TStoreOptions> = KibanaMcpConfig<TStoreOptions> | (() => KibanaMcpConfig<TStoreOptions> | Promise<KibanaMcpConfig<TStoreOptions>>);
+/**
+ * Types the default export of a `kibana.mcp.config.ts` file.
+ */
+export declare function defineKibanaMcpConfig<TStoreOptions = Record<string, unknown>>(config: KibanaMcpConfigExport<TStoreOptions>): KibanaMcpConfigExport<TStoreOptions>;
+export interface LoadedConfigFile {
+    path: string;
+    config: KibanaMcpConfig;
+    store?: CatalogStore;
+}
+/**
+ * Loads the configuration file named explicitly by the operator. The file is executed as code,
+ * so it is never discovered implicitly from the working directory.
+ */
+export declare function loadConfigFile(configPath: string | undefined, cwd?: string): Promise<LoadedConfigFile | undefined>;
+/**
+ * Returns the environment completed with the values of the configuration file. Variables that are
+ * already set win, so a deployment can override the file without editing it.
+ */
+export declare function applyConfigFile(envInput: NodeJS.ProcessEnv, { config }: LoadedConfigFile): NodeJS.ProcessEnv;

package/dist/src/config/config_file.js

@@ -0,0 +1,76 @@
+import { access } from "node:fs/promises";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { PROFILE_NAME_ENV } from "./environment.js";
+export { CatalogConflictError } from "../stores/catalog_store.js";
+export const CONFIG_FILE_ENV = "KIBANA_MCP_CONFIG";
+export const HTTP_HOST_ENV = "KIBANA_HTTP_HOST";
+export const HTTP_PORT_ENV = "KIBANA_HTTP_PORT";
+export const HTTP_PATH_ENV = "KIBANA_HTTP_PATH";
+export const HTTP_PROFILE_HEADER_ENV = "KIBANA_HTTP_PROFILE_HEADER";
+export const HTTP_AUTH_TOKEN_ENV = "KIBANA_HTTP_AUTH_TOKEN";
+/**
+ * Types the default export of a `kibana.mcp.config.ts` file.
+ */
+export function defineKibanaMcpConfig(config) {
+    return config;
+}
+/**
+ * Loads the configuration file named explicitly by the operator. The file is executed as code,
+ * so it is never discovered implicitly from the working directory.
+ */
+export async function loadConfigFile(configPath, cwd = process.cwd()) {
+    const requested = configPath?.trim();
+    if (!requested) {
+        return undefined;
+    }
+    const path = resolve(cwd, requested);
+    await access(path).catch(() => {
+        throw new Error(`Configuration file '${path}' was not found.`);
+    });
+    let exported;
+    try {
+        exported = (await import(pathToFileURL(path).href)).default;
+    }
+    catch (error) {
+        const hint = /\.[cm]?ts$/.test(path)
+            ? " A TypeScript configuration needs a runtime that strips types (Node.js 22.18 or later); otherwise use a .mjs file."
+            : "";
+        throw new Error(`Configuration file '${path}' could not be loaded: ${error instanceof Error ? error.message : String(error)}.${hint}`, { cause: error });
+    }
+    const config = (typeof exported === "function" ? await exported() : exported);
+    if (!config || typeof config !== "object" || Array.isArray(config)) {
+        throw new Error(`Configuration file '${path}' must default-export a configuration object.`);
+    }
+    const store = typeof config.store === "function" ? await config.store(config.storeOptions) : config.store;
+    if (store !== undefined &&
+        (typeof store?.read !== "function" || typeof store?.replace !== "function")) {
+        throw new Error(`Configuration file '${path}': store must implement read() and replace().`);
+    }
+    return { path, config, store };
+}
+/**
+ * Returns the environment completed with the values of the configuration file. Variables that are
+ * already set win, so a deployment can override the file without editing it.
+ */
+export function applyConfigFile(envInput, { config }) {
+    const defaults = {
+        KIBANA_BASE_URL: config.url,
+        KIBANA_USERNAME: config.user,
+        KIBANA_PASSWORD: config.password,
+        KIBANA_TIMEOUT_MS: config.timeoutMs,
+        [PROFILE_NAME_ENV]: config.profile,
+        [HTTP_HOST_ENV]: config.http?.host,
+        [HTTP_PORT_ENV]: config.http?.port,
+        [HTTP_PATH_ENV]: config.http?.path,
+        [HTTP_PROFILE_HEADER_ENV]: config.http?.profileHeader,
+        [HTTP_AUTH_TOKEN_ENV]: config.http?.authToken,
+    };
+    const env = { ...envInput };
+    for (const [name, value] of Object.entries(defaults)) {
+        if (value !== undefined && value !== "" && !env[name]?.trim()) {
+            env[name] = String(value);
+        }
+    }
+    return env;
+}

package/dist/src/config/environment.d.ts

@@ -0,0 +1,100 @@
+import { readFile } from "node:fs/promises";
+import { z } from "zod";
+import { type SecretStore } from "../profiles/secret_store.js";
+import { ProfileStore } from "../profiles/store.js";
+import type { AppConfig, ResolvedAppConfig } from "../types.js";
+export declare const DEFAULT_RUNTIME_SOURCE_CATALOG_PATH = "config/sources.runtime.json";
+export declare const DEFAULT_STATIC_SOURCE_CATALOG_PATH = "config/sources.json";
+export declare const PROFILE_NAME_ENV = "KIBANA_PROFILE";
+export declare const PROFILE_PLACEHOLDER = "{profile}";
+export declare class NoSavedProfileError extends Error {
+    constructor(message: string);
+}
+export declare const sourceDefinitionSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    tags: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    timeField: z.ZodString;
+    backend: z.ZodObject<{
+        kind: z.ZodEnum<{
+            elasticsearch_search: "elasticsearch_search";
+            kibana_internal_search_es: "kibana_internal_search_es";
+        }>;
+        path: z.ZodString;
+        index: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+    }, z.core.$strip>;
+    schema: z.ZodOptional<z.ZodObject<{
+        kind: z.ZodEnum<{
+            elasticsearch_field_caps: "elasticsearch_field_caps";
+            kibana_data_views_fields: "kibana_data_views_fields";
+            kibana_index_patterns_fields: "kibana_index_patterns_fields";
+        }>;
+        path: z.ZodOptional<z.ZodString>;
+        index: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+    }, z.core.$strip>>;
+    fieldHints: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        type: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        aliases: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>>;
+    defaultTextFields: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    evidenceFields: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export declare const sourceCatalogSchema: z.ZodObject<{
+    generatedBy: z.ZodOptional<z.ZodObject<{
+        tool: z.ZodLiteral<"@havesomecode/kibana-mcp-server">;
+        formatVersion: z.ZodLiteral<1>;
+        sourceHash: z.ZodString;
+    }, z.core.$strip>>;
+    sources: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        tags: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        timeField: z.ZodString;
+        backend: z.ZodObject<{
+            kind: z.ZodEnum<{
+                elasticsearch_search: "elasticsearch_search";
+                kibana_internal_search_es: "kibana_internal_search_es";
+            }>;
+            path: z.ZodString;
+            index: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+        }, z.core.$strip>;
+        schema: z.ZodOptional<z.ZodObject<{
+            kind: z.ZodEnum<{
+                elasticsearch_field_caps: "elasticsearch_field_caps";
+                kibana_data_views_fields: "kibana_data_views_fields";
+                kibana_index_patterns_fields: "kibana_index_patterns_fields";
+            }>;
+            path: z.ZodOptional<z.ZodString>;
+            index: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodArray<z.ZodString>]>>;
+        }, z.core.$strip>>;
+        fieldHints: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            type: z.ZodOptional<z.ZodString>;
+            description: z.ZodOptional<z.ZodString>;
+            aliases: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        }, z.core.$strip>>>;
+        defaultTextFields: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        evidenceFields: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare function resolveSourceCatalogPath(envInput?: NodeJS.ProcessEnv): string;
+export declare function parseAppConfig(envInput: unknown, sourceCatalogInput: unknown): AppConfig;
+export declare function loadConfigFromEnvironment(envInput?: NodeJS.ProcessEnv, dependencies?: {
+    profileStore?: Pick<ProfileStore, "findProfile" | "getDefaultProfile">;
+    exactProfileName?: boolean;
+    secretStore?: Pick<SecretStore, "load">;
+    readFile?: typeof readFile;
+}): Promise<ResolvedAppConfig>;
+/**
+ * Reads the connection supplied through the bootstrap environment variables, if any.
+ */
+export declare function readBootstrapConnection(envInput?: NodeJS.ProcessEnv): AppConfig["kibana"] | undefined;
+export declare function persistSourceCatalog(sources: AppConfig["sources"], options?: {
+    envInput?: NodeJS.ProcessEnv;
+    sourceCatalogPath?: string;
+    catalog?: unknown;
+}): Promise<string>;

package/dist/src/{config.js → config/environment.js}

@@ -1,12 +1,13 @@
-import { createHash, randomUUID } from "node:crypto";
-import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
-import { dirname } from "node:path";
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
 import { z } from "zod";
-import { ProfileStore } from "./profile_store.js";
-import { SecretStoreError, createSecretStore } from "./secret_store.js";
+import { SecretStoreError, createSecretStore } from "../profiles/secret_store.js";
+import { ProfileStore } from "../profiles/store.js";
+import { writeTextAtomically } from "../utils/fs.js";
 export const DEFAULT_RUNTIME_SOURCE_CATALOG_PATH = "config/sources.runtime.json";
 export const DEFAULT_STATIC_SOURCE_CATALOG_PATH = "config/sources.json";
 export const PROFILE_NAME_ENV = "KIBANA_PROFILE";
+export const PROFILE_PLACEHOLDER = "{profile}";
 export class NoSavedProfileError extends Error {
     constructor(message) {
         super(message);
@@ -129,17 +130,15 @@ export function parseAppConfig(envInput, sourceCatalogInput) {
 export async function loadConfigFromEnvironment(envInput = process.env, dependencies = {}) {
     const overrides = startupOverrideSchema.parse(envInput);
     const readFileImpl = dependencies.readFile ?? readFile;
-    if (hasPartialBootstrapConfig(overrides)) {
-        throw new Error("Incomplete Kibana bootstrap environment. Provide KIBANA_BASE_URL, KIBANA_USERNAME, and KIBANA_PASSWORD together.");
-    }
-    if (hasBootstrapConfig(overrides)) {
+    const kibana = readBootstrapConnection(envInput);
+    if (kibana) {
         const preferredPath = resolveSourceCatalogPath(envInput);
         const sourceCatalog = await loadSourceCatalog(preferredPath === DEFAULT_RUNTIME_SOURCE_CATALOG_PATH
             ? [preferredPath, DEFAULT_STATIC_SOURCE_CATALOG_PATH]
             : [preferredPath], readFileImpl);
-        const config = parseAppConfig(overrides, sourceCatalog.value);
         return {
-            ...config,
+            kibana,
+            sources: sourceCatalogSchema.parse(sourceCatalog.value).sources,
             sourceCatalogPath: preferredPath,
             sourceCatalogOrigin: sourceCatalog.loadedFrom === DEFAULT_STATIC_SOURCE_CATALOG_PATH
                 ? "static_default"
@@ -152,7 +151,9 @@ export async function loadConfigFromEnvironment(envInput = process.env, dependen
     const secretStore = dependencies.secretStore ?? createSecretStore();
     const requestedProfileName = overrides[PROFILE_NAME_ENV]?.trim();
     const profile = requestedProfileName
-        ? await profileStore.findProfile(requestedProfileName)
+        ? await profileStore.findProfile(requestedProfileName, {
+            exactName: dependencies.exactProfileName,
+        })
         : await profileStore.getDefaultProfile();
     if (!profile) {
         if (!requestedProfileName) {
@@ -183,20 +184,21 @@ export async function loadConfigFromEnvironment(envInput = process.env, dependen
         sourceCatalogOrigin: overrides.KIBANA_SOURCE_CATALOG_PATH?.trim() ? "environment" : "profile",
     };
 }
+/**
+ * Reads the connection supplied through the bootstrap environment variables, if any.
+ */
+export function readBootstrapConnection(envInput = process.env) {
+    const overrides = startupOverrideSchema.parse(envInput);
+    if (hasPartialBootstrapConfig(overrides)) {
+        throw new Error("Incomplete Kibana bootstrap environment. Provide KIBANA_BASE_URL, KIBANA_USERNAME, and KIBANA_PASSWORD together.");
+    }
+    return hasBootstrapConfig(overrides)
+        ? buildKibanaConfig(bootstrapEnvSchema.parse(overrides))
+        : undefined;
+}
 export async function persistSourceCatalog(sources, options = {}) {
     const sourceCatalogPath = options.sourceCatalogPath ?? resolveSourceCatalogPath(options.envInput);
-    await mkdir(dirname(sourceCatalogPath), { recursive: true });
-    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(() => { });
-    }
+    await writeTextAtomically(sourceCatalogPath, `${JSON.stringify(options.catalog ?? { sources }, null, 2)}\n`);
     return sourceCatalogPath;
 }
 function hasBootstrapConfig(envInput) {

package/dist/src/config/startup.d.ts

@@ -0,0 +1,31 @@
+import type { ProfileConfigLoader } from "../profiles/runtime.js";
+import type { ResolvedAppConfig } from "../types.js";
+import { type LoadedConfigFile } from "./config_file.js";
+import { loadConfigFromEnvironment } from "./environment.js";
+/** Profile served over stdio when per-profile catalogs are configured and none is named. */
+export declare const DEFAULT_PROFILE_NAME = "default";
+export interface StartupConfiguration {
+    defaultConfig?: ResolvedAppConfig;
+    loadProfileConfig?: ProfileConfigLoader;
+    /** Releases what the configuration opened, such as the catalog store. */
+    close: () => Promise<void>;
+}
+/**
+ * Loads the configuration file named by `KIBANA_MCP_CONFIG`, if any, and resolves the startup
+ * configuration from the environment completed with its values.
+ */
+export declare function loadStartupConfiguration(envInput?: NodeJS.ProcessEnv): Promise<{
+    env: NodeJS.ProcessEnv;
+    startupConfiguration: StartupConfiguration;
+}>;
+/**
+ * Resolves what the server serves by default and, when the configuration allows it, how to load
+ * the configuration of a named profile on demand.
+ *
+ * Named profiles come from either the saved profile store, or from one connection shared by every
+ * profile whose catalogs live in a catalog store: the `store` of the configuration file, or files
+ * when `KIBANA_SOURCE_CATALOG_PATH` carries the `{profile}` placeholder.
+ */
+export declare function resolveStartupConfiguration(envInput?: NodeJS.ProcessEnv, dependencies?: Parameters<typeof loadConfigFromEnvironment>[1] & {
+    configFile?: LoadedConfigFile;
+}): Promise<StartupConfiguration>;

package/dist/src/config/startup.js

@@ -0,0 +1,86 @@
+import { bindCatalogStore } from "../stores/catalog_store.js";
+import { createFileCatalogStore } from "../stores/file.js";
+import { CONFIG_FILE_ENV, applyConfigFile, loadConfigFile, } from "./config_file.js";
+import { NoSavedProfileError, PROFILE_NAME_ENV, PROFILE_PLACEHOLDER, loadConfigFromEnvironment, readBootstrapConnection, } from "./environment.js";
+/** Profile served over stdio when per-profile catalogs are configured and none is named. */
+export const DEFAULT_PROFILE_NAME = "default";
+/**
+ * Loads the configuration file named by `KIBANA_MCP_CONFIG`, if any, and resolves the startup
+ * configuration from the environment completed with its values.
+ */
+export async function loadStartupConfiguration(envInput = process.env) {
+    const configFile = await loadConfigFile(envInput[CONFIG_FILE_ENV]);
+    const env = configFile ? applyConfigFile(envInput, configFile) : envInput;
+    return { env, startupConfiguration: await resolveStartupConfiguration(env, { configFile }) };
+}
+/**
+ * Resolves what the server serves by default and, when the configuration allows it, how to load
+ * the configuration of a named profile on demand.
+ *
+ * Named profiles come from either the saved profile store, or from one connection shared by every
+ * profile whose catalogs live in a catalog store: the `store` of the configuration file, or files
+ * when `KIBANA_SOURCE_CATALOG_PATH` carries the `{profile}` placeholder.
+ */
+export async function resolveStartupConfiguration(envInput = process.env, dependencies = {}) {
+    const customStore = dependencies.configFile?.store;
+    const close = async () => {
+        await customStore?.close?.();
+    };
+    try {
+        return { ...(await resolveConfiguration(envInput, dependencies, customStore)), close };
+    }
+    catch (error) {
+        await close().catch(() => { });
+        throw error;
+    }
+}
+async function resolveConfiguration(envInput, dependencies, customStore) {
+    const kibana = readBootstrapConnection(envInput);
+    const requestedProfileName = envInput[PROFILE_NAME_ENV]?.trim();
+    const catalogPath = envInput.KIBANA_SOURCE_CATALOG_PATH?.trim();
+    const catalogPathTemplate = catalogPath?.includes(PROFILE_PLACEHOLDER) ? catalogPath : undefined;
+    if (customStore && catalogPath) {
+        throw new Error("KIBANA_SOURCE_CATALOG_PATH cannot be combined with the store of the configuration file.");
+    }
+    if (kibana) {
+        const store = customStore ??
+            (catalogPathTemplate
+                ? createFileCatalogStore((profileKey) => catalogPathTemplate.replaceAll(PROFILE_PLACEHOLDER, profileKey))
+                : undefined);
+        if (!store) {
+            return { defaultConfig: await loadConfigFromEnvironment(envInput, dependencies) };
+        }
+        // Sources are read from the store when the profile is resolved, not here.
+        const loadProfileConfig = async (profileName) => ({
+            kibana,
+            sources: [],
+            profileName,
+            catalog: bindCatalogStore(store, profileName),
+        });
+        // No profile is assumed here: a transport serving several callers must not fall back to a
+        // catalog shared by all of them unless the operator named it.
+        return {
+            defaultConfig: requestedProfileName
+                ? await loadProfileConfig(requestedProfileName)
+                : undefined,
+            loadProfileConfig,
+        };
+    }
+    if (customStore || catalogPathTemplate) {
+        throw new Error("Per-profile catalogs (a store, or {profile} in KIBANA_SOURCE_CATALOG_PATH) require a Kibana url, user and password.");
+    }
+    // Named saved profiles carry their own catalog: the global catalog override is not applied.
+    const loadProfileConfig = (profileName) => loadConfigFromEnvironment({ KIBANA_TIMEOUT_MS: envInput.KIBANA_TIMEOUT_MS, [PROFILE_NAME_ENV]: profileName }, { ...dependencies, exactProfileName: true });
+    try {
+        return {
+            defaultConfig: await loadConfigFromEnvironment(envInput, dependencies),
+            loadProfileConfig,
+        };
+    }
+    catch (error) {
+        if (error instanceof NoSavedProfileError) {
+            return {};
+        }
+        throw error;
+    }
+}

package/dist/src/kibana/client.d.ts

@@ -0,0 +1,28 @@
+import type { AppConfig, CompiledSourceQuery, KibanaSearchExecutionResult, SourceDefinition, SourceFieldDescriptor } from "../types.js";
+export type KibanaRequestErrorCode = "KIBANA_AUTHENTICATION" | "KIBANA_CANCELLED" | "KIBANA_CONNECTION" | "KIBANA_DNS" | "KIBANA_HTTP" | "KIBANA_NETWORK" | "KIBANA_OVERLOADED" | "KIBANA_RESPONSE" | "KIBANA_TIMEOUT" | "KIBANA_TLS";
+export type KibanaRequestPhase = "queue" | "request" | "response";
+export declare class KibanaRequestError extends Error {
+    readonly code: KibanaRequestErrorCode;
+    readonly phase: KibanaRequestPhase;
+    readonly sourceId: string | undefined;
+    readonly timeoutMs: number;
+    readonly status?: number | undefined;
+    readonly causeCode?: string | undefined;
+    constructor(code: KibanaRequestErrorCode, phase: KibanaRequestPhase, sourceId: string | undefined, timeoutMs: number, message: string, cause?: unknown, status?: number | undefined, causeCode?: string | undefined);
+}
+export declare class KibanaClient {
+    private readonly config;
+    private readonly requestGate;
+    private readonly queueTimeoutMs;
+    constructor(config: AppConfig["kibana"], options?: {
+        maxConcurrency?: number;
+        maxQueueDepth?: number;
+        queueTimeoutMs?: number;
+    });
+    private requestJson;
+    verifyConnection(): Promise<void>;
+    execute(compiledQuery: CompiledSourceQuery, callerSignal?: AbortSignal): Promise<KibanaSearchExecutionResult>;
+    executeMany(sourceQueries: CompiledSourceQuery[], callerSignal?: AbortSignal): Promise<KibanaSearchExecutionResult[]>;
+    private describeFieldsViaSearchBackend;
+    describeFields(source: SourceDefinition, callerSignal?: AbortSignal): Promise<SourceFieldDescriptor[]>;
+}

package/dist/src/kibana/schema_catalog.d.ts

@@ -0,0 +1,11 @@
+import type { SourceDefinition, SourceFieldDescriptor } from "../types.js";
+export declare class SchemaCatalog {
+    private readonly client;
+    private readonly cache;
+    private readonly inFlight;
+    constructor(client: {
+        describeFields: (source: SourceDefinition, callerSignal?: AbortSignal) => Promise<SourceFieldDescriptor[]>;
+    });
+    getFields(source: SourceDefinition, callerSignal?: AbortSignal): Promise<SourceFieldDescriptor[]>;
+    filterFields(fields: SourceFieldDescriptor[], query?: string, limit?: number): SourceFieldDescriptor[];
+}

package/dist/src/{schema_catalog.js → kibana/schema_catalog.js}

@@ -1,3 +1,4 @@
+import { KibanaRequestError } from "./client.js";
 function normalizeFieldName(value) {
     return value.trim().toLowerCase();
 }
@@ -59,26 +60,47 @@ export class SchemaCatalog {
         this.client = client;
     }
     async getFields(source, callerSignal) {
+        const cancelled = () => new KibanaRequestError("KIBANA_CANCELLED", "request", source.id, 0, `[KIBANA_CANCELLED] Schema discovery for source '${source.id}' was cancelled.`, callerSignal?.reason);
+        if (callerSignal?.aborted) {
+            throw cancelled();
+        }
         const existing = this.cache.get(source.id);
         if (existing) {
             return existing;
         }
-        const pending = this.inFlight.get(source.id);
-        if (pending) {
-            return pending;
+        let pending = this.inFlight.get(source.id);
+        if (!pending) {
+            const controller = new AbortController();
+            const promise = this.client.describeFields(source, controller.signal).then((fields) => {
+                const resolved = linkFieldRelationships(mergeFieldHints(source, fields));
+                if (!controller.signal.aborted) {
+                    this.cache.set(source.id, resolved);
+                }
+                return resolved;
+            });
+            pending = { promise, controller, callers: 0 };
+            this.inFlight.set(source.id, pending);
         }
-        const discovery = this.client.describeFields(source, callerSignal).then((fields) => {
-            const resolved = linkFieldRelationships(mergeFieldHints(source, fields));
-            this.cache.set(source.id, resolved);
-            return resolved;
-        });
-        this.inFlight.set(source.id, discovery);
+        const discovery = pending;
+        discovery.callers += 1;
+        let onAbort;
         try {
-            return await discovery;
+            return await new Promise((resolve, reject) => {
+                onAbort = () => reject(cancelled());
+                callerSignal?.addEventListener("abort", onAbort, { once: true });
+                discovery.promise.then(resolve, reject);
+                if (callerSignal?.aborted)
+                    onAbort();
+            });
         }
         finally {
-            if (this.inFlight.get(source.id) === discovery) {
+            if (onAbort)
+                callerSignal?.removeEventListener("abort", onAbort);
+            discovery.callers -= 1;
+            if (discovery.callers === 0 && this.inFlight.get(source.id) === discovery) {
                 this.inFlight.delete(source.id);
+                if (callerSignal?.aborted)
+                    discovery.controller.abort();
             }
         }
     }

package/dist/src/kibana/source_catalog.d.ts

@@ -0,0 +1,10 @@
+import type { DiscoverSourceResult, SourceDefinition } from "../types.js";
+export declare class SourceCatalog {
+    private readonly sources;
+    private readonly sourceMap;
+    constructor(sources: SourceDefinition[]);
+    count(): number;
+    list(query?: string, limit?: number): DiscoverSourceResult[];
+    getRequiredSources(sourceIds: string[]): SourceDefinition[];
+    private matchesQuery;
+}

package/dist/src/mcp_entry.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/src/mcp_entry.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { startMcpServer } from "./mcp_runtime.js";
+import { startMcpServer } from "./transports/stdio.js";
 startMcpServer().catch((error) => {
     console.error(error);
     process.exitCode = 1;

package/dist/src/profiles/context.d.ts

@@ -0,0 +1,4 @@
+import type { ProfileRuntime } from "./runtime.js";
+export declare function runWithProfileRuntime<T>(runtime: ProfileRuntime, operation: () => T): T;
+export declare function getProfileRuntime(): ProfileRuntime | undefined;
+export declare function requireProfileRuntime(): ProfileRuntime;

package/dist/src/profiles/context.js

@@ -0,0 +1,15 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+const profileRuntimeStorage = new AsyncLocalStorage();
+export function runWithProfileRuntime(runtime, operation) {
+    return profileRuntimeStorage.run(runtime, operation);
+}
+export function getProfileRuntime() {
+    return profileRuntimeStorage.getStore();
+}
+export function requireProfileRuntime() {
+    const runtime = profileRuntimeStorage.getStore();
+    if (!runtime) {
+        throw new Error("No profile is bound to the current tool call.");
+    }
+    return runtime;
+}