@havesomecode/kibana-mcp-server 1.3.0 → 1.4.0

package/dist/src/stores/postgres.js

@@ -0,0 +1,65 @@
+import { CatalogConflictError } from "./catalog_store.js";
+import { DEFAULT_TABLE_NAME, describeStoreUrl, importDriver, quoteSqlIdentifier, resolveStoreUrl, } from "./shared.js";
+/**
+ * Catalog store backed by PostgreSQL through the `pg` package: one row per profile.
+ *
+ * Usable directly as `store` in the configuration file; its options come from `storeOptions`.
+ */
+export default async function postgresCatalogStore(options = {}) {
+    const tableName = options.table ?? DEFAULT_TABLE_NAME;
+    const table = quoteSqlIdentifier(tableName);
+    let client = options.client;
+    let label = "postgres:";
+    let close;
+    if (!client) {
+        const url = resolveStoreUrl("PostgreSQL", options.url, ["DATABASE_URL"], ["postgres:", "postgresql:"]);
+        const pg = await importDriver("PostgreSQL", "pg");
+        const Pool = pg.Pool ?? pg.default?.Pool;
+        if (!Pool) {
+            throw new Error("The installed 'pg' package does not expose Pool.");
+        }
+        const pool = new Pool({ connectionString: url.href });
+        // Without a listener, an error on an idle connection would crash the process.
+        pool.on("error", () => { });
+        client = pool;
+        label = describeStoreUrl(url);
+        close = () => pool.end();
+    }
+    const database = client;
+    try {
+        if (options.createTable ?? true) {
+            await database.query(`CREATE TABLE IF NOT EXISTS ${table} (
+          profile_key TEXT PRIMARY KEY,
+          content TEXT NOT NULL,
+          updated_at TIMESTAMPTZ NOT NULL DEFAULT now()
+        )`);
+        }
+    }
+    catch (error) {
+        await close?.().catch(() => { });
+        throw error;
+    }
+    const describe = (profileKey) => `${label}/${tableName}/${profileKey}`;
+    return {
+        describe,
+        async read(profileKey) {
+            const { rows } = await database.query(`SELECT content FROM ${table} WHERE profile_key = $1`, [
+                profileKey,
+            ]);
+            const content = rows[0]?.content;
+            return typeof content === "string" ? content : undefined;
+        },
+        async replace(profileKey, expected, next, signal) {
+            signal?.throwIfAborted();
+            const { rowCount } = expected === undefined
+                ? await database.query(`INSERT INTO ${table} (profile_key, content) VALUES ($1, $2)
+               ON CONFLICT (profile_key) DO NOTHING`, [profileKey, next])
+                : await database.query(`UPDATE ${table} SET content = $3, updated_at = now()
+               WHERE profile_key = $1 AND content = $2`, [profileKey, expected, next]);
+            if (rowCount !== 1) {
+                throw new CatalogConflictError(describe(profileKey));
+            }
+        },
+        close,
+    };
+}

package/dist/src/stores/redis.d.ts

@@ -0,0 +1,24 @@
+import type { CatalogStore } from "./catalog_store.js";
+export interface RedisCatalogStoreOptions {
+    /** `redis://` or `rediss://` URL. Defaults to `KIBANA_STORE_URL`, then `REDIS_URL`. */
+    url?: string;
+    /** Prefix of the catalog keys. Defaults to `kibana-mcp:catalog:`. */
+    keyPrefix?: string;
+    /** A connected `redis` client to use instead of `url`. The store never closes it. */
+    client?: RedisCatalogClient;
+}
+/** The subset of the `redis` client this store relies on. */
+export interface RedisCatalogClient {
+    get(key: string): Promise<string | null>;
+    eval(script: string, options: {
+        keys: string[];
+        arguments: string[];
+    }): Promise<unknown>;
+}
+/**
+ * Catalog store backed by Redis through the `redis` package: one key per profile, without expiry.
+ * Use a Redis with persistence and a `noeviction` policy, catalogs are not a cache.
+ *
+ * Usable directly as `store` in the configuration file; its options come from `storeOptions`.
+ */
+export default function redisCatalogStore(options?: RedisCatalogStoreOptions): Promise<CatalogStore>;

package/dist/src/stores/redis.js

@@ -0,0 +1,31 @@
+import { DEFAULT_KEY_PREFIX, REDIS_COMPARE_AND_SET_SCRIPT, createKeyValueCatalogStore, describeStoreUrl, importDriver, resolveStoreUrl, } from "./shared.js";
+/**
+ * Catalog store backed by Redis through the `redis` package: one key per profile, without expiry.
+ * Use a Redis with persistence and a `noeviction` policy, catalogs are not a cache.
+ *
+ * Usable directly as `store` in the configuration file; its options come from `storeOptions`.
+ */
+export default async function redisCatalogStore(options = {}) {
+    let client = options.client;
+    let label = "redis:";
+    let close;
+    if (!client) {
+        const url = resolveStoreUrl("Redis", options.url, ["REDIS_URL"], ["redis:", "rediss:"]);
+        const redis = await importDriver("Redis", "redis");
+        const owned = redis.createClient({ url: url.href });
+        // Without a listener, a connection error would crash the process instead of failing the call.
+        owned.on("error", () => { });
+        await owned.connect();
+        client = owned;
+        label = describeStoreUrl(url);
+        close = () => owned.close();
+    }
+    const connected = client;
+    return createKeyValueCatalogStore({
+        label,
+        keyPrefix: options.keyPrefix ?? DEFAULT_KEY_PREFIX,
+        get: (key) => connected.get(key),
+        compareAndSet: (key, values) => connected.eval(REDIS_COMPARE_AND_SET_SCRIPT, { keys: [key], arguments: values }),
+        close,
+    });
+}

package/dist/src/stores/shared.d.ts

@@ -0,0 +1,25 @@
+import { type CatalogStore } from "./catalog_store.js";
+export declare const STORE_URL_ENV = "KIBANA_STORE_URL";
+export declare const DEFAULT_KEY_PREFIX = "kibana-mcp:catalog:";
+export declare const DEFAULT_TABLE_NAME = "kibana_mcp_catalogs";
+/**
+ * Resolves the connection URL of a store: the explicit option, then `KIBANA_STORE_URL`, then the
+ * conventional variables of the backend.
+ */
+export declare function resolveStoreUrl(storeName: string, explicitUrl: string | undefined, fallbackEnvNames: string[], protocols: string[]): URL;
+/** Like resolveStoreUrl, but leaves backend-specific URI parsing to its driver. */
+export declare function resolveStoreConnectionString(storeName: string, explicitUrl: string | undefined, fallbackEnvNames: string[], protocols: string[]): string;
+/** Location of a store without its credentials, for tool output. */
+export declare function describeStoreUrl(url: URL): string;
+export declare function importDriver<T>(storeName: string, packageName: string): Promise<T>;
+/** Quotes a possibly schema-qualified SQL identifier, refusing anything but plain names. */
+export declare function quoteSqlIdentifier(name: string): string;
+export declare const REDIS_COMPARE_AND_SET_SCRIPT = "\nlocal current = redis.call('GET', KEYS[1])\nif ARGV[1] == '1' then\n  if current ~= ARGV[2] then return 0 end\nelseif current then\n  return 0\nend\nredis.call('SET', KEYS[1], ARGV[3])\nreturn 1\n";
+export declare function createKeyValueCatalogStore(backend: {
+    label: string;
+    keyPrefix: string;
+    get(key: string): Promise<string | null | undefined>;
+    /** Runs {@link REDIS_COMPARE_AND_SET_SCRIPT} with `[hasExpected, expected, next]`. */
+    compareAndSet(key: string, values: [string, string, string]): Promise<unknown>;
+    close?(): Promise<void>;
+}): CatalogStore;

package/dist/src/stores/shared.js

@@ -0,0 +1,88 @@
+import { CatalogConflictError } from "./catalog_store.js";
+export const STORE_URL_ENV = "KIBANA_STORE_URL";
+export const DEFAULT_KEY_PREFIX = "kibana-mcp:catalog:";
+export const DEFAULT_TABLE_NAME = "kibana_mcp_catalogs";
+/**
+ * Resolves the connection URL of a store: the explicit option, then `KIBANA_STORE_URL`, then the
+ * conventional variables of the backend.
+ */
+export function resolveStoreUrl(storeName, explicitUrl, fallbackEnvNames, protocols) {
+    const url = resolveStoreConnectionString(storeName, explicitUrl, fallbackEnvNames, protocols);
+    try {
+        return new URL(url);
+    }
+    catch {
+        throw new Error(`The ${storeName} catalog store URL is not a valid URL.`);
+    }
+}
+/** Like resolveStoreUrl, but leaves backend-specific URI parsing to its driver. */
+export function resolveStoreConnectionString(storeName, explicitUrl, fallbackEnvNames, protocols) {
+    const envNames = [STORE_URL_ENV, ...fallbackEnvNames];
+    const url = explicitUrl?.trim() ||
+        envNames.map((name) => process.env[name]?.trim()).find((value) => Boolean(value));
+    if (!url) {
+        throw new Error(`The ${storeName} catalog store needs a URL: pass 'url', or set ${envNames.join(" or ")}.`);
+    }
+    const protocol = /^[a-z][a-z0-9+.-]*:/i.exec(url)?.[0].toLowerCase();
+    if (!protocol) {
+        throw new Error(`The ${storeName} catalog store URL is not a valid URL.`);
+    }
+    if (!protocols.includes(protocol)) {
+        throw new Error(`The ${storeName} catalog store URL must use ${protocols.map((protocol) => `${protocol}//`).join(" or ")}.`);
+    }
+    return url;
+}
+/** Location of a store without its credentials, for tool output. */
+export function describeStoreUrl(url) {
+    return `${url.protocol}//${url.host}${url.pathname === "/" ? "" : url.pathname}`;
+}
+export async function importDriver(storeName, packageName) {
+    try {
+        return (await import(packageName));
+    }
+    catch (error) {
+        throw new Error(`The ${storeName} catalog store requires the '${packageName}' package. Install it next to this server.`, { cause: error });
+    }
+}
+/** Quotes a possibly schema-qualified SQL identifier, refusing anything but plain names. */
+export function quoteSqlIdentifier(name) {
+    const parts = name.split(".");
+    if (parts.length > 2 || parts.some((part) => !/^[A-Za-z_][A-Za-z0-9_]*$/.test(part))) {
+        throw new Error(`Invalid table name '${name}': use letters, digits and underscores, optionally prefixed by a schema.`);
+    }
+    return parts.map((part) => `"${part}"`).join(".");
+}
+// Writes only when the key still holds the content the caller read, so that several server
+// processes sharing one Redis never overwrite each other's catalog changes.
+export const REDIS_COMPARE_AND_SET_SCRIPT = `
+local current = redis.call('GET', KEYS[1])
+if ARGV[1] == '1' then
+  if current ~= ARGV[2] then return 0 end
+elseif current then
+  return 0
+end
+redis.call('SET', KEYS[1], ARGV[3])
+return 1
+`;
+export function createKeyValueCatalogStore(backend) {
+    const keyOf = (profileKey) => `${backend.keyPrefix}${profileKey}`;
+    const describe = (profileKey) => `${backend.label}/${keyOf(profileKey)}`;
+    return {
+        describe,
+        async read(profileKey) {
+            return (await backend.get(keyOf(profileKey))) ?? undefined;
+        },
+        async replace(profileKey, expected, next, signal) {
+            signal?.throwIfAborted();
+            const replaced = await backend.compareAndSet(keyOf(profileKey), [
+                expected === undefined ? "0" : "1",
+                expected ?? "",
+                next,
+            ]);
+            if (Number(replaced) !== 1) {
+                throw new CatalogConflictError(describe(profileKey));
+            }
+        },
+        close: backend.close,
+    };
+}

package/dist/src/stores/sqlite.d.ts

@@ -0,0 +1,26 @@
+import { type CatalogStore } from "./catalog_store.js";
+export interface SqliteCatalogStoreOptions {
+    /** Database file, or `:memory:`. Defaults to `KIBANA_STORE_URL`, with or without a `sqlite:` prefix. */
+    path?: string;
+    /** Catalog table. Defaults to `kibana_mcp_catalogs`. */
+    table?: string;
+    /** An open `node:sqlite` database to use instead of `path`. The store never closes it. */
+    database?: SqliteCatalogDatabase;
+}
+/** The subset of a `node:sqlite` `DatabaseSync` this store relies on. */
+export interface SqliteCatalogDatabase {
+    exec(sql: string): void;
+    prepare(sql: string): {
+        get(...parameters: string[]): unknown;
+        run(...parameters: string[]): {
+            changes: number | bigint;
+        };
+    };
+}
+/**
+ * Catalog store backed by a SQLite file through the built-in `node:sqlite` module: one row per
+ * profile. Suited to a single host; several processes may share the file.
+ *
+ * Usable directly as `store` in the configuration file; its options come from `storeOptions`.
+ */
+export default function sqliteCatalogStore(options?: SqliteCatalogStoreOptions): Promise<CatalogStore>;

package/dist/src/stores/sqlite.js

@@ -0,0 +1,63 @@
+import { mkdir } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { CatalogConflictError } from "./catalog_store.js";
+import { DEFAULT_TABLE_NAME, STORE_URL_ENV, importDriver, quoteSqlIdentifier } from "./shared.js";
+/**
+ * Catalog store backed by a SQLite file through the built-in `node:sqlite` module: one row per
+ * profile. Suited to a single host; several processes may share the file.
+ *
+ * Usable directly as `store` in the configuration file; its options come from `storeOptions`.
+ */
+export default async function sqliteCatalogStore(options = {}) {
+    const tableName = options.table ?? DEFAULT_TABLE_NAME;
+    const table = quoteSqlIdentifier(tableName);
+    let database = options.database;
+    let label = "sqlite:";
+    let close;
+    if (!database) {
+        const configuredPath = (options.path?.trim() || process.env[STORE_URL_ENV]?.trim())?.replace(/^sqlite:(\/\/)?/, "");
+        if (!configuredPath) {
+            throw new Error(`The SQLite catalog store needs a database file: pass 'path', or set ${STORE_URL_ENV}.`);
+        }
+        const inMemory = configuredPath === ":memory:";
+        const path = inMemory ? configuredPath : resolve(configuredPath);
+        if (!inMemory) {
+            await mkdir(dirname(path), { recursive: true });
+        }
+        const sqlite = await importDriver("SQLite", "node:sqlite");
+        const opened = new sqlite.DatabaseSync(path);
+        // Let several server processes share the file: readers do not block, writers wait their turn.
+        opened.exec("PRAGMA journal_mode = WAL; PRAGMA busy_timeout = 5000;");
+        database = opened;
+        label = `sqlite:${path}`;
+        close = async () => opened.close();
+    }
+    database.exec(`CREATE TABLE IF NOT EXISTS ${table} (
+      profile_key TEXT PRIMARY KEY,
+      content TEXT NOT NULL,
+      updated_at TEXT NOT NULL
+    )`);
+    const select = database.prepare(`SELECT content FROM ${table} WHERE profile_key = ?`);
+    const insert = database.prepare(`INSERT INTO ${table} (profile_key, content, updated_at) VALUES (?, ?, ?)
+     ON CONFLICT (profile_key) DO NOTHING`);
+    const update = database.prepare(`UPDATE ${table} SET content = ?, updated_at = ? WHERE profile_key = ? AND content = ?`);
+    const describe = (profileKey) => `${label}/${tableName}/${profileKey}`;
+    return {
+        describe,
+        async read(profileKey) {
+            const row = select.get(profileKey);
+            return typeof row?.content === "string" ? row.content : undefined;
+        },
+        async replace(profileKey, expected, next, signal) {
+            signal?.throwIfAborted();
+            const now = new Date().toISOString();
+            const { changes } = expected === undefined
+                ? insert.run(profileKey, next, now)
+                : update.run(next, now, profileKey, expected);
+            if (Number(changes) !== 1) {
+                throw new CatalogConflictError(describe(profileKey));
+            }
+        },
+        close,
+    };
+}

package/dist/src/tools/configure.d.ts

@@ -0,0 +1,59 @@
+import type { CallToolResult } from "@modelcontextprotocol/server";
+import { z } from "zod";
+import type { AppConfig } from "../types.js";
+export declare const configureInputSchema: z.ZodObject<{
+    kibana: z.ZodObject<{
+        baseUrl: z.ZodURL;
+        username: z.ZodString;
+        password: z.ZodString;
+        timeoutMs: z.ZodDefault<z.ZodNumber>;
+    }, 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 const configureOutputSchema: z.ZodObject<{
+    configured: z.ZodLiteral<true>;
+    persisted: z.ZodLiteral<true>;
+    source_catalog_path: z.ZodString;
+    source_count: z.ZodNumber;
+    source_ids: z.ZodArray<z.ZodString>;
+    base_url: z.ZodString;
+}, z.core.$strip>;
+export declare function executeConfigure(input: z.infer<typeof configureInputSchema>, options?: {
+    envInput?: NodeJS.ProcessEnv;
+    sourceCatalogPath?: string;
+}): Promise<{
+    nextConfig: AppConfig;
+    result: z.infer<typeof configureOutputSchema>;
+}>;
+export declare function createConfigureCallToolResult(result: z.infer<typeof configureOutputSchema>): CallToolResult;

package/dist/src/tools/configure.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { persistSourceCatalog, sourceDefinitionSchema } from "../config.js";
+import { persistSourceCatalog, sourceDefinitionSchema } from "../config/environment.js";
 export const configureInputSchema = z.object({
     kibana: z.object({
         baseUrl: z.url(),

package/dist/src/tools/configure_index.d.ts

@@ -0,0 +1,35 @@
+import type { CallToolResult } from "@modelcontextprotocol/server";
+import { z } from "zod";
+import type { KibanaClient } from "../kibana/client.js";
+import type { ResolvedAppConfig, SourceDefinition } from "../types.js";
+export declare const configureIndexInputSchema: z.ZodObject<{
+    index: z.ZodString;
+    source_name: z.ZodOptional<z.ZodString>;
+    source_id: z.ZodOptional<z.ZodString>;
+    time_field: z.ZodOptional<z.ZodString>;
+    replace: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strict>;
+export declare const configureIndexOutputSchema: z.ZodObject<{
+    configured: z.ZodLiteral<true>;
+    persisted: z.ZodLiteral<true>;
+    source_catalog_path: z.ZodString;
+    source_count: z.ZodNumber;
+    source_id: z.ZodString;
+    index: z.ZodString;
+    time_field: z.ZodString;
+}, z.core.$strip>;
+type ConfigureIndexInput = z.input<typeof configureIndexInputSchema>;
+type ConfigureIndexClient = Pick<KibanaClient, "describeFields" | "execute">;
+export declare function executeConfigureIndex(inputValue: ConfigureIndexInput, options: {
+    config: ResolvedAppConfig;
+    kibanaClient: ConfigureIndexClient;
+    stateRoot?: string;
+    callerSignal?: AbortSignal;
+}): Promise<{
+    sources: SourceDefinition[];
+    result: z.infer<typeof configureIndexOutputSchema>;
+    /** The serialized catalog that was written. */
+    catalogContent?: string;
+}>;
+export declare function createConfigureIndexCallToolResult(result: z.infer<typeof configureIndexOutputSchema>): CallToolResult;
+export {};

package/dist/src/tools/configure_index.js

@@ -1,9 +1,7 @@
-import { readFile } from "node:fs/promises";
 import { z } from "zod";
-import { buildGeneratedSource, chooseGeneratedSourceFields, createGeneratedCatalog, parseGeneratedCatalog, } from "../bootstrap.js";
-import { persistSourceCatalog } from "../config.js";
-import { resolveProfilePaths } from "../profile_paths.js";
-import { acquireStateLock } from "../state_lock.js";
+import { buildGeneratedSource, chooseGeneratedSourceFields, createGeneratedCatalog, parseGeneratedCatalog, } from "../setup/bootstrap.js";
+import { bindCatalogStore } from "../stores/catalog_store.js";
+import { createFileCatalogStore } from "../stores/file.js";
 export const configureIndexInputSchema = z
     .object({
     index: z.string().trim().min(1),
@@ -24,72 +22,83 @@ export const configureIndexOutputSchema = z.object({
 });
 export async function executeConfigureIndex(inputValue, options) {
     const input = configureIndexInputSchema.parse(inputValue);
-    const sourceCatalogPath = options.config.sourceCatalogPath;
+    options.callerSignal?.throwIfAborted();
+    // A catalog kept at a plain path goes through the same store contract as any other: the write
+    // only happens if the catalog is still the one that was read, so Kibana is never called under a lock.
+    const catalog = options.config.catalog ?? fileCatalogOf(options.config, options.stateRoot);
+    const existingContent = await catalog.read();
+    // Sources without a catalog at the persisted location were loaded from somewhere else, such as
+    // the static fallback catalog: starting from an empty catalog would silently drop them.
+    if (existingContent === undefined && options.config.sources.length > 0) {
+        throw new Error(`Source catalog '${catalog.location}' does not exist although sources are configured. Refusing to replace them with a new managed catalog.`);
+    }
+    const next = await buildNextCatalog(input, existingContent, options);
+    const catalogContent = `${JSON.stringify(next.catalog, null, 2)}\n`;
+    options.callerSignal?.throwIfAborted();
+    await catalog.replace(existingContent, catalogContent, options.callerSignal);
+    return {
+        sources: next.sources,
+        catalogContent,
+        result: {
+            configured: true,
+            persisted: true,
+            source_catalog_path: catalog.location,
+            source_count: next.sources.length,
+            source_id: next.source.id,
+            index: input.index,
+            time_field: next.source.timeField,
+        },
+    };
+}
+function fileCatalogOf(config, stateRoot) {
+    const sourceCatalogPath = config.sourceCatalogPath;
     if (!sourceCatalogPath) {
         throw new Error("configure_index requires a persisted source catalog. Run connection bootstrap first.");
     }
-    const stateRoot = options.stateRoot ?? resolveProfilePaths().stateRoot;
-    const releaseLock = await acquireStateLock(stateRoot);
-    try {
-        const existingContent = await readFile(sourceCatalogPath, "utf8");
-        const existingCatalog = parseGeneratedCatalog(existingContent);
-        if (!existingCatalog) {
-            throw new Error("configure_index can update only a managed generated catalog. Refusing to overwrite a hand-authored or modified catalog.");
-        }
-        const proposedSource = buildGeneratedSource([input.index], input.source_name, input.source_id);
-        const existingSource = existingCatalog.sources.find((source) => source.id === proposedSource.id);
-        if (existingSource &&
-            !input.replace &&
-            JSON.stringify(existingSource.backend.index) !== JSON.stringify(proposedSource.backend.index)) {
-            throw new Error(`Source id '${proposedSource.id}' already refers to a different index. Re-run with replace=true only after the user explicitly approves replacement.`);
-        }
-        const discoveredFields = await options.kibanaClient.describeFields(proposedSource, options.callerSignal);
-        if (discoveredFields.length === 0) {
-            throw new Error(`Explicit index pattern '${input.index}' resolved to no fields. Check the index and Kibana permissions.`);
-        }
-        const generatedFields = chooseGeneratedSourceFields(discoveredFields, input.time_field);
-        const verifiedSource = {
-            ...proposedSource,
-            ...generatedFields,
-        };
-        await options.kibanaClient.execute({
-            source: verifiedSource,
-            request: {
-                body: {
-                    size: 1,
-                    track_total_hits: false,
-                    query: { match_all: {} },
-                },
-            },
-            resolvedFilters: [],
-            resolvedNestedFilters: [],
-            resolvedSortBy: verifiedSource.timeField,
-            advisories: [],
-        }, options.callerSignal);
-        const sources = existingSource
-            ? existingCatalog.sources.map((source) => source.id === verifiedSource.id ? verifiedSource : source)
-            : [...existingCatalog.sources, verifiedSource];
-        const generatedCatalog = createGeneratedCatalog(sources);
-        await persistSourceCatalog(sources, {
-            sourceCatalogPath,
-            catalog: generatedCatalog,
-        });
-        return {
-            sources,
-            result: {
-                configured: true,
-                persisted: true,
-                source_catalog_path: sourceCatalogPath,
-                source_count: sources.length,
-                source_id: verifiedSource.id,
-                index: input.index,
-                time_field: verifiedSource.timeField,
-            },
-        };
+    return bindCatalogStore(createFileCatalogStore(() => sourceCatalogPath, stateRoot), config.profileName ?? "default");
+}
+async function buildNextCatalog(input, existingContent, options) {
+    // A profile that has no catalog yet starts from an empty managed one.
+    const existingCatalog = existingContent === undefined
+        ? createGeneratedCatalog([])
+        : parseGeneratedCatalog(existingContent);
+    if (!existingCatalog) {
+        throw new Error("configure_index can update only a managed generated catalog. Refusing to overwrite a hand-authored or modified catalog.");
+    }
+    const proposedSource = buildGeneratedSource([input.index], input.source_name, input.source_id);
+    const existingSource = existingCatalog.sources.find((source) => source.id === proposedSource.id);
+    if (existingSource &&
+        !input.replace &&
+        JSON.stringify(existingSource.backend.index) !== JSON.stringify(proposedSource.backend.index)) {
+        throw new Error(`Source id '${proposedSource.id}' already refers to a different index. Re-run with replace=true only after the user explicitly approves replacement.`);
     }
-    finally {
-        await releaseLock();
+    const discoveredFields = await options.kibanaClient.describeFields(proposedSource, options.callerSignal);
+    if (discoveredFields.length === 0) {
+        throw new Error(`Explicit index pattern '${input.index}' resolved to no fields. Check the index and Kibana permissions.`);
     }
+    const generatedFields = chooseGeneratedSourceFields(discoveredFields, input.time_field);
+    const verifiedSource = {
+        ...proposedSource,
+        ...generatedFields,
+    };
+    await options.kibanaClient.execute({
+        source: verifiedSource,
+        request: {
+            body: {
+                size: 1,
+                track_total_hits: false,
+                query: { match_all: {} },
+            },
+        },
+        resolvedFilters: [],
+        resolvedNestedFilters: [],
+        resolvedSortBy: verifiedSource.timeField,
+        advisories: [],
+    }, options.callerSignal);
+    const sources = existingSource
+        ? existingCatalog.sources.map((source) => source.id === verifiedSource.id ? verifiedSource : source)
+        : [...existingCatalog.sources, verifiedSource];
+    return { sources, source: verifiedSource, catalog: createGeneratedCatalog(sources) };
 }
 export function createConfigureIndexCallToolResult(result) {
     return {

package/dist/src/tools/describe_fields.d.ts

@@ -0,0 +1,29 @@
+import type { CallToolResult } from "@modelcontextprotocol/server";
+import { z } from "zod";
+import type { SchemaCatalog } from "../kibana/schema_catalog.js";
+import type { SourceCatalog } from "../kibana/source_catalog.js";
+export declare const describeFieldsInputSchema: z.ZodObject<{
+    source_id: z.ZodString;
+    query: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const describeFieldsOutputSchema: z.ZodObject<{
+    source_id: z.ZodString;
+    total: z.ZodNumber;
+    fields: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        type: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        aliases: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        searchable: z.ZodOptional<z.ZodBoolean>;
+        aggregatable: z.ZodOptional<z.ZodBoolean>;
+        subfields: z.ZodArray<z.ZodString>;
+        nested_path: z.ZodOptional<z.ZodString>;
+        object_array_path: z.ZodOptional<z.ZodString>;
+        multi_field_parent: z.ZodOptional<z.ZodString>;
+        preferred_exact_field: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare function executeDescribeFields(input: z.infer<typeof describeFieldsInputSchema>, sourceCatalog: Pick<SourceCatalog, "getRequiredSources">, schemaCatalog: SchemaCatalog, callerSignal?: AbortSignal): Promise<z.infer<typeof describeFieldsOutputSchema>>;
+export declare function formatDescribeFieldsResult(result: z.infer<typeof describeFieldsOutputSchema>): string;
+export declare function createDescribeFieldsCallToolResult(result: z.infer<typeof describeFieldsOutputSchema>): CallToolResult;

package/dist/src/tools/discover.d.ts

@@ -0,0 +1,27 @@
+import type { CallToolResult } from "@modelcontextprotocol/server";
+import { z } from "zod";
+import type { SourceCatalog } from "../kibana/source_catalog.js";
+export declare const discoverInputSchema: z.ZodObject<{
+    query: z.ZodOptional<z.ZodString>;
+    limit: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const discoverOutputSchema: z.ZodObject<{
+    configured_total: z.ZodNumber;
+    total: z.ZodNumber;
+    sources: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        tags: z.ZodArray<z.ZodString>;
+        time_field: z.ZodString;
+        field_hints: z.ZodArray<z.ZodObject<{
+            name: z.ZodString;
+            type: z.ZodOptional<z.ZodString>;
+            description: z.ZodOptional<z.ZodString>;
+            aliases: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare function executeDiscover(input: z.infer<typeof discoverInputSchema>, sourceCatalog: SourceCatalog): z.infer<typeof discoverOutputSchema>;
+export declare function formatDiscoverResult(result: z.infer<typeof discoverOutputSchema>): string;
+export declare function createDiscoverCallToolResult(result: z.infer<typeof discoverOutputSchema>): CallToolResult;