@havesomecode/kibana-mcp-server 0.1.0

package/dist/src/secret_store.js

@@ -0,0 +1,261 @@
+import { spawn } from "node:child_process";
+const DEFAULT_SERVICE_NAME = "com.zacaria.kibana-mcp-server";
+export class SecretStoreError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = "SecretStoreError";
+    }
+}
+export function createSecretStore(platform = process.platform, runner = runCommand, serviceName = DEFAULT_SERVICE_NAME) {
+    switch (platform) {
+        case "darwin":
+            return new MacOsSecretStore(runner, serviceName);
+        case "win32":
+            return new WindowsSecretStore(runner, serviceName);
+        default:
+            return new LinuxSecretStore(runner, serviceName);
+    }
+}
+class MacOsSecretStore {
+    runner;
+    serviceName;
+    constructor(runner, serviceName) {
+        this.runner = runner;
+        this.serviceName = serviceName;
+    }
+    async load(profileId) {
+        const result = await this.execute("find-generic-password", [
+            "-s",
+            this.serviceName,
+            "-a",
+            profileId,
+            "-w",
+        ]);
+        return parseStoredSecret(result.stdout);
+    }
+    async save(profileId, secret) {
+        await this.execute("add-generic-password", [
+            "-U",
+            "-s",
+            this.serviceName,
+            "-a",
+            profileId,
+            "-w",
+            serializeSecret(secret),
+        ]);
+    }
+    async delete(profileId) {
+        try {
+            await this.execute("delete-generic-password", ["-s", this.serviceName, "-a", profileId]);
+        }
+        catch (error) {
+            if (error instanceof SecretStoreError && error.code === "NOT_FOUND") {
+                return;
+            }
+            throw error;
+        }
+    }
+    async execute(subcommand, args) {
+        try {
+            const result = await this.runner("security", [subcommand, ...args]);
+            if (result.exitCode === 44) {
+                throw new SecretStoreError(`No saved credentials found for profile '${args.at(-1)}'.`, "NOT_FOUND");
+            }
+            if (result.exitCode !== 0) {
+                throw new SecretStoreError(result.stderr.trim() || "macOS Keychain command failed.", "OPERATION_FAILED");
+            }
+            return result;
+        }
+        catch (error) {
+            throw normalizeRunnerError(error, "macOS Keychain is unavailable.");
+        }
+    }
+}
+class LinuxSecretStore {
+    runner;
+    serviceName;
+    constructor(runner, serviceName) {
+        this.runner = runner;
+        this.serviceName = serviceName;
+    }
+    async load(profileId) {
+        const result = await this.execute("lookup", this.attributes(profileId));
+        const value = result.stdout.trim();
+        if (!value) {
+            throw new SecretStoreError(`No saved credentials found for profile '${profileId}'.`, "NOT_FOUND");
+        }
+        return parseStoredSecret(value);
+    }
+    async save(profileId, secret) {
+        await this.execute("store", ["--label", `Kibana MCP (${profileId})`, ...this.attributes(profileId)], serializeSecret(secret));
+    }
+    async delete(profileId) {
+        try {
+            await this.execute("clear", this.attributes(profileId));
+        }
+        catch (error) {
+            if (error instanceof SecretStoreError && error.code === "NOT_FOUND") {
+                return;
+            }
+            throw error;
+        }
+    }
+    attributes(profileId) {
+        return ["service", this.serviceName, "profile", profileId];
+    }
+    async execute(command, args, stdin) {
+        try {
+            const result = await this.runner("secret-tool", [command, ...args], { stdin });
+            if (result.exitCode !== 0) {
+                const stderr = result.stderr.trim().toLowerCase();
+                if (stderr.includes("not found")) {
+                    throw new SecretStoreError(`No saved credentials found for profile '${args.at(-1) ?? "unknown"}'.`, "NOT_FOUND");
+                }
+                throw new SecretStoreError(result.stderr.trim() || "Secret Service command failed.", "OPERATION_FAILED");
+            }
+            return result;
+        }
+        catch (error) {
+            throw normalizeRunnerError(error, "Linux Secret Service is unavailable. Install and unlock a Secret Service-compatible keyring first.");
+        }
+    }
+}
+class WindowsSecretStore {
+    runner;
+    serviceName;
+    constructor(runner, serviceName) {
+        this.runner = runner;
+        this.serviceName = serviceName;
+    }
+    async load(profileId) {
+        const result = await this.execute(`
+[void][Windows.Security.Credentials.PasswordVault,Windows.Security.Credentials,ContentType=WindowsRuntime]
+$vault = New-Object Windows.Security.Credentials.PasswordVault
+try {
+  $credential = $vault.Retrieve($args[0], $args[1])
+  $credential.RetrievePassword()
+  [Console]::Out.Write($credential.Password)
+  exit 0
+} catch {
+  exit 3
+}
+      `, [this.serviceName, profileId]);
+        return parseStoredSecret(result.stdout);
+    }
+    async save(profileId, secret) {
+        await this.execute(`
+[void][Windows.Security.Credentials.PasswordVault,Windows.Security.Credentials,ContentType=WindowsRuntime]
+$vault = New-Object Windows.Security.Credentials.PasswordVault
+try {
+  $existing = $vault.Retrieve($args[0], $args[1])
+  $vault.Remove($existing)
+} catch {}
+$credential = New-Object Windows.Security.Credentials.PasswordCredential($args[0], $args[1], $args[2])
+$vault.Add($credential)
+      `, [this.serviceName, profileId, serializeSecret(secret)]);
+    }
+    async delete(profileId) {
+        try {
+            await this.execute(`
+[void][Windows.Security.Credentials.PasswordVault,Windows.Security.Credentials,ContentType=WindowsRuntime]
+$vault = New-Object Windows.Security.Credentials.PasswordVault
+try {
+  $credential = $vault.Retrieve($args[0], $args[1])
+  $vault.Remove($credential)
+  exit 0
+} catch {
+  exit 3
+}
+        `, [this.serviceName, profileId]);
+        }
+        catch (error) {
+            if (error instanceof SecretStoreError && error.code === "NOT_FOUND") {
+                return;
+            }
+            throw error;
+        }
+    }
+    async execute(script, args) {
+        try {
+            const result = await this.runner("powershell.exe", [
+                "-NoProfile",
+                "-NonInteractive",
+                "-Command",
+                script.trim(),
+                ...args,
+            ]);
+            if (result.exitCode === 3) {
+                throw new SecretStoreError(`No saved credentials found for profile '${args[1]}'.`, "NOT_FOUND");
+            }
+            if (result.exitCode !== 0) {
+                throw new SecretStoreError(result.stderr.trim() || "Windows Credential Manager command failed.", "OPERATION_FAILED");
+            }
+            return result;
+        }
+        catch (error) {
+            throw normalizeRunnerError(error, "Windows Credential Manager is unavailable.");
+        }
+    }
+}
+function serializeSecret(secret) {
+    return JSON.stringify(secret);
+}
+function parseStoredSecret(serializedSecret) {
+    const parsed = JSON.parse(serializedSecret);
+    if (!parsed ||
+        typeof parsed !== "object" ||
+        !("username" in parsed) ||
+        !("password" in parsed) ||
+        typeof parsed.username !== "string" ||
+        typeof parsed.password !== "string") {
+        throw new SecretStoreError("Stored credentials are invalid.", "OPERATION_FAILED");
+    }
+    return {
+        username: parsed.username,
+        password: parsed.password,
+    };
+}
+function normalizeRunnerError(error, unavailableMessage) {
+    if (error instanceof SecretStoreError) {
+        return error;
+    }
+    if (error &&
+        typeof error === "object" &&
+        "code" in error &&
+        typeof error.code === "string" &&
+        error.code === "ENOENT") {
+        return new SecretStoreError(unavailableMessage, "UNAVAILABLE");
+    }
+    return new SecretStoreError(error instanceof Error ? error.message : "Credential-store command failed.", "OPERATION_FAILED");
+}
+async function runCommand(command, args, options = {}) {
+    return await new Promise((resolve, reject) => {
+        const child = spawn(command, args, {
+            stdio: "pipe",
+        });
+        let stdout = "";
+        let stderr = "";
+        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", reject);
+        child.on("close", (exitCode) => {
+            resolve({
+                stdout,
+                stderr,
+                exitCode: exitCode ?? 1,
+            });
+        });
+        if (options.stdin) {
+            child.stdin.write(options.stdin);
+        }
+        child.stdin.end();
+    });
+}

package/dist/src/server.js

@@ -0,0 +1,87 @@
+import { McpServer } from "@modelcontextprotocol/server";
+import { KibanaClient } from "./kibana_client.js";
+import { SchemaCatalog } from "./schema_catalog.js";
+import { SourceCatalog } from "./source_catalog.js";
+import { configureInputSchema, configureOutputSchema, createConfigureCallToolResult, executeConfigure, } from "./tools/configure.js";
+import { createDescribeFieldsCallToolResult, describeFieldsInputSchema, describeFieldsOutputSchema, executeDescribeFields, } from "./tools/describe_fields.js";
+import { createDiscoverCallToolResult, discoverInputSchema, discoverOutputSchema, executeDiscover, } from "./tools/discover.js";
+import { createFilterCallToolResult, executeFilter, filterInputSchema, filterOutputSchema, } from "./tools/filter.js";
+import { createQueryCallToolResult, executeQuery, queryInputSchema, queryOutputSchema, } from "./tools/query.js";
+export function createApplication(initialConfig, dependencies) {
+    const server = new McpServer({
+        name: "kibana-log-investigation",
+        version: "0.1.0",
+    });
+    const kibanaClientFactory = dependencies?.kibanaClientFactory ??
+        ((config) => new KibanaClient(config));
+    let activeConfig = initialConfig;
+    let sourceCatalog = activeConfig ? new SourceCatalog(activeConfig.sources) : null;
+    let kibanaClient = activeConfig
+        ? (dependencies?.kibanaClient ?? kibanaClientFactory(activeConfig.kibana))
+        : null;
+    let schemaCatalog = kibanaClient ? new SchemaCatalog(kibanaClient) : null;
+    function requireConfigured() {
+        if (!sourceCatalog || !kibanaClient || !schemaCatalog) {
+            throw new Error("Server is not configured. Call the 'configure' tool first.");
+        }
+        return { sourceCatalog, kibanaClient, schemaCatalog };
+    }
+    const configureHandler = async (input) => {
+        const { nextConfig, result } = await executeConfigure(configureInputSchema.parse(input), {
+            sourceCatalogPath: activeConfig?.sourceCatalogPath,
+        });
+        activeConfig = {
+            ...nextConfig,
+            sourceCatalogPath: result.source_catalog_path,
+            profileName: activeConfig?.profileName,
+            sourceCatalogOrigin: activeConfig?.sourceCatalogOrigin,
+        };
+        sourceCatalog = new SourceCatalog(nextConfig.sources);
+        kibanaClient = kibanaClientFactory(nextConfig.kibana);
+        schemaCatalog = new SchemaCatalog(kibanaClient);
+        return result;
+    };
+    const describeFieldsHandler = (input) => executeDescribeFields(describeFieldsInputSchema.parse(input), requireConfigured().sourceCatalog, requireConfigured().schemaCatalog);
+    const discoverHandler = (input) => executeDiscover(discoverInputSchema.parse(input), requireConfigured().sourceCatalog);
+    const filterHandler = (input) => executeFilter(filterInputSchema.parse(input), requireConfigured().sourceCatalog, requireConfigured().kibanaClient, {
+        schemaCatalog: requireConfigured().schemaCatalog,
+    });
+    const queryHandler = (input) => executeQuery(queryInputSchema.parse(input), requireConfigured().sourceCatalog, requireConfigured().kibanaClient, {
+        schemaCatalog: requireConfigured().schemaCatalog,
+    });
+    server.registerTool("configure", {
+        description: "Configure the Kibana connection and logical source catalog for this server session.",
+        inputSchema: configureInputSchema,
+        outputSchema: configureOutputSchema,
+    }, async (input) => createConfigureCallToolResult(await configureHandler(input)));
+    server.registerTool("describe_fields", {
+        description: "Describe the effective field capabilities for a configured logical source.",
+        inputSchema: describeFieldsInputSchema,
+        outputSchema: describeFieldsOutputSchema,
+    }, async (input) => createDescribeFieldsCallToolResult(await describeFieldsHandler(input)));
+    server.registerTool("discover", {
+        description: "List configured logical log sources and field hints for investigation work.",
+        inputSchema: discoverInputSchema,
+        outputSchema: discoverOutputSchema,
+    }, async (input) => createDiscoverCallToolResult(discoverHandler(input)));
+    server.registerTool("filter", {
+        description: "Run an exact-field filter when the field name is already known, bypassing alias resolution.",
+        inputSchema: filterInputSchema,
+        outputSchema: filterOutputSchema,
+    }, async (input) => createFilterCallToolResult(await filterHandler(input)));
+    server.registerTool("query", {
+        description: "Query one or more logical log sources over an absolute time window with text, filters, and aggregate modes.",
+        inputSchema: queryInputSchema,
+        outputSchema: queryOutputSchema,
+    }, async (input) => createQueryCallToolResult(await queryHandler(input)));
+    return {
+        server,
+        handlers: {
+            configure: configureHandler,
+            describe_fields: describeFieldsHandler,
+            discover: discoverHandler,
+            filter: filterHandler,
+            query: queryHandler,
+        },
+    };
+}

package/dist/src/setup_flow.js

@@ -0,0 +1,160 @@
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { sourceCatalogSchema } from "./config.js";
+import { resolveProfilePaths } from "./profile_paths.js";
+import { ProfileStore, deriveProfileId } from "./profile_store.js";
+import { SecretStoreError, createSecretStore } from "./secret_store.js";
+const DEFAULT_TIMEOUT_MS = 10000;
+const KNOWN_ENDPOINT_PATHS = [
+    "/internal/search/es",
+    "/api/data_views/fields_for_wildcard",
+    "/api/index_patterns/_fields_for_wildcard",
+];
+export async function runSetupFlow(prompter, dependencies = {}) {
+    const paths = dependencies.paths ?? resolveProfilePaths();
+    const profileStore = dependencies.profileStore ?? new ProfileStore(paths);
+    const secretStore = dependencies.secretStore ?? createSecretStore();
+    const readFileImpl = dependencies.readFile ?? readFile;
+    const writeFileImpl = dependencies.writeFile ?? writeFile;
+    const mkdirImpl = dependencies.mkdir ?? mkdir;
+    const cwd = dependencies.cwd ?? process.cwd();
+    const savedProfileNames = [];
+    const savedCatalogPaths = [];
+    await prompter.info("Guided setup will save one machine-level Kibana profile and reuse it in later threads.");
+    let continueAddingProfiles = true;
+    while (continueAddingProfiles) {
+        const existingProfiles = await profileStore.listProfiles();
+        const profileName = await promptForProfileName(prompter, existingProfiles.map((profile) => profile.name));
+        const existingProfile = existingProfiles.find((profile) => profile.name.toLowerCase() === profileName.toLowerCase());
+        const profileId = existingProfile?.id ??
+            deriveProfileId(profileName, existingProfiles.map((profile) => profile.id));
+        const baseUrl = await promptForBaseUrl(prompter);
+        const username = await promptForRequiredValue(prompter, "Kibana username");
+        const password = await promptForRequiredValue(prompter, "Kibana password", { secret: true });
+        const importPath = await promptForSourceCatalogPath(prompter, cwd);
+        const importedCatalogPath = join(paths.sourceCatalogsDir, `${profileId}.json`);
+        await copyValidatedSourceCatalog(importPath, importedCatalogPath, {
+            readFile: readFileImpl,
+            writeFile: writeFileImpl,
+            mkdir: mkdirImpl,
+        });
+        try {
+            await secretStore.save(profileId, { username, password });
+        }
+        catch (error) {
+            if (error instanceof SecretStoreError) {
+                throw new Error(`Could not save Kibana credentials securely: ${error.message}`);
+            }
+            throw error;
+        }
+        const profile = await profileStore.upsertProfile({
+            id: profileId,
+            name: profileName,
+            baseUrl,
+            timeoutMs: DEFAULT_TIMEOUT_MS,
+            sourceCatalogPath: importedCatalogPath,
+        }, {
+            makeDefault: existingProfiles.length === 0,
+        });
+        if (existingProfiles.length > 0) {
+            const makeDefault = await prompter.confirm(`Make '${profile.name}' the default environment for new threads?`, false);
+            if (makeDefault) {
+                await profileStore.setDefaultProfile(profile.id);
+            }
+        }
+        savedProfileNames.push(profile.name);
+        savedCatalogPaths.push(importedCatalogPath);
+        continueAddingProfiles = await prompter.confirm("Add another environment now?", false);
+    }
+    const defaultProfile = await profileStore.getDefaultProfile();
+    if (!defaultProfile) {
+        throw new Error("Setup completed without a saved default profile.");
+    }
+    return {
+        defaultProfileName: defaultProfile.name,
+        profiles: savedProfileNames,
+        sourceCatalogPaths: savedCatalogPaths,
+    };
+}
+async function promptForProfileName(prompter, existingNames) {
+    while (true) {
+        const value = (await prompter.prompt("Environment name", { defaultValue: "default" })).trim();
+        if (!value) {
+            continue;
+        }
+        if (!/^[A-Za-z0-9][A-Za-z0-9 _-]*$/.test(value)) {
+            await prompter.info("Use letters, numbers, spaces, dashes, or underscores for the environment name.");
+            continue;
+        }
+        if (existingNames.some((candidate) => candidate.toLowerCase() === value.toLowerCase())) {
+            const overwrite = await prompter.confirm(`An environment named '${value}' already exists. Update it with new credentials and sources?`, true);
+            if (!overwrite) {
+                continue;
+            }
+        }
+        return value;
+    }
+}
+async function promptForBaseUrl(prompter) {
+    while (true) {
+        const rawValue = (await prompter.prompt("Kibana base URL")).trim();
+        try {
+            const parsed = new URL(rawValue);
+            const normalizedBaseUrl = parsed.toString().replace(/\/+$/, "");
+            if (KNOWN_ENDPOINT_PATHS.some((path) => parsed.pathname.includes(path))) {
+                await prompter.info("Enter the Kibana base URL only. Do not include endpoint paths such as /internal/search/es.");
+                continue;
+            }
+            return normalizedBaseUrl;
+        }
+        catch {
+            await prompter.info("Enter a valid URL such as https://kibana.example.com or https://gateway.example.com/logs.");
+        }
+    }
+}
+async function promptForRequiredValue(prompter, label, options = {}) {
+    while (true) {
+        const value = (await prompter.prompt(label, options)).trim();
+        if (value) {
+            return value;
+        }
+        await prompter.info(`${label} is required.`);
+    }
+}
+async function promptForSourceCatalogPath(prompter, cwd) {
+    const bundledCatalogPath = await resolveBundledSourceCatalogPath();
+    while (true) {
+        const rawValue = (await prompter.prompt("Source catalog path to import", {
+            defaultValue: bundledCatalogPath,
+        })).trim();
+        const importPath = rawValue ? resolve(cwd, rawValue) : bundledCatalogPath;
+        try {
+            await access(importPath);
+            return importPath;
+        }
+        catch {
+            await prompter.info(`Source catalog not found at ${importPath}. Use a JSON file or accept the bundled example.`);
+        }
+    }
+}
+async function copyValidatedSourceCatalog(importPath, destinationPath, io) {
+    const rawCatalog = await io.readFile(importPath, "utf8");
+    const parsedCatalog = sourceCatalogSchema.parse(JSON.parse(rawCatalog));
+    await io.mkdir(dirname(destinationPath), { recursive: true });
+    await io.writeFile(destinationPath, `${JSON.stringify(parsedCatalog, null, 2)}\n`, "utf8");
+}
+async function resolveBundledSourceCatalogPath() {
+    const candidates = [
+        new URL("../config/sources.example.json", import.meta.url),
+        new URL("../../config/sources.example.json", import.meta.url),
+    ].map((candidate) => fileURLToPath(candidate));
+    for (const candidate of candidates) {
+        try {
+            await access(candidate);
+            return candidate;
+        }
+        catch { }
+    }
+    throw new Error("Bundled source catalog config/sources.example.json could not be found.");
+}

package/dist/src/source_catalog.js

@@ -0,0 +1,47 @@
+export class SourceCatalog {
+    sources;
+    sourceMap;
+    constructor(sources) {
+        this.sources = sources;
+        this.sourceMap = new Map(sources.map((source) => [source.id, source]));
+    }
+    list(query, limit = 20) {
+        const normalizedQuery = query?.trim().toLowerCase();
+        const filtered = normalizedQuery
+            ? this.sources.filter((source) => this.matchesQuery(source, normalizedQuery))
+            : this.sources;
+        return filtered.slice(0, limit).map((source) => ({
+            id: source.id,
+            name: source.name,
+            description: source.description,
+            tags: source.tags,
+            time_field: source.timeField,
+            field_hints: source.fieldHints.map((fieldHint) => ({
+                ...fieldHint,
+                aliases: fieldHint.aliases ?? [],
+            })),
+        }));
+    }
+    getRequiredSources(sourceIds) {
+        const resolved = sourceIds.map((sourceId) => this.sourceMap.get(sourceId));
+        const missing = sourceIds.filter((sourceId, index) => !resolved[index]);
+        if (missing.length > 0) {
+            throw new Error(`Unknown source ids: ${missing.join(", ")}`);
+        }
+        return resolved;
+    }
+    matchesQuery(source, query) {
+        const haystacks = [
+            source.id,
+            source.name,
+            source.description ?? "",
+            ...source.tags,
+            ...source.fieldHints.flatMap((fieldHint) => [
+                fieldHint.name,
+                fieldHint.description ?? "",
+                ...(fieldHint.aliases ?? []),
+            ]),
+        ];
+        return haystacks.some((value) => value.toLowerCase().includes(query));
+    }
+}

package/dist/src/tools/configure.js

@@ -0,0 +1,53 @@
+import { z } from "zod";
+import { persistSourceCatalog, sourceDefinitionSchema } from "../config.js";
+export const configureInputSchema = z.object({
+    kibana: z.object({
+        baseUrl: z.url(),
+        username: z.string().min(1),
+        password: z.string().min(1),
+        timeoutMs: z.number().int().positive().max(120000).default(10000),
+    }),
+    sources: z.array(sourceDefinitionSchema).min(1),
+});
+export const configureOutputSchema = z.object({
+    configured: z.literal(true),
+    persisted: z.literal(true),
+    source_catalog_path: z.string(),
+    source_count: z.number().int().positive(),
+    source_ids: z.array(z.string()),
+    base_url: z.string(),
+});
+export async function executeConfigure(input, options = {}) {
+    const nextConfig = {
+        kibana: {
+            baseUrl: input.kibana.baseUrl.replace(/\/+$/, ""),
+            username: input.kibana.username,
+            password: input.kibana.password,
+            timeoutMs: input.kibana.timeoutMs,
+        },
+        sources: input.sources,
+    };
+    const sourceCatalogPath = await persistSourceCatalog(input.sources, options);
+    return {
+        nextConfig,
+        result: {
+            configured: true,
+            persisted: true,
+            source_catalog_path: sourceCatalogPath,
+            source_count: input.sources.length,
+            source_ids: input.sources.map((source) => source.id),
+            base_url: nextConfig.kibana.baseUrl,
+        },
+    };
+}
+export function createConfigureCallToolResult(result) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: `Configured Kibana connection for ${result.base_url} with ${result.source_count} sources. Source catalog persisted to ${result.source_catalog_path}.`,
+            },
+        ],
+        structuredContent: result,
+    };
+}

package/dist/src/tools/describe_fields.js

@@ -0,0 +1,55 @@
+import { z } from "zod";
+export const describeFieldsInputSchema = z.object({
+    source_id: z.string().min(1),
+    query: z.string().trim().min(1).optional(),
+    limit: z.number().int().positive().max(500).default(100),
+});
+export const describeFieldsOutputSchema = z.object({
+    source_id: z.string(),
+    total: z.number().int().nonnegative(),
+    fields: z.array(z.object({
+        name: z.string(),
+        type: z.string().optional(),
+        description: z.string().optional(),
+        aliases: z.array(z.string()).optional(),
+        searchable: z.boolean().optional(),
+        aggregatable: z.boolean().optional(),
+        subfields: z.array(z.string()),
+        nested_path: z.string().optional(),
+        object_array_path: z.string().optional(),
+        multi_field_parent: z.string().optional(),
+        preferred_exact_field: z.string().optional(),
+    })),
+});
+export async function executeDescribeFields(input, sourceCatalog, schemaCatalog) {
+    const [source] = sourceCatalog.getRequiredSources([input.source_id]);
+    const fields = await schemaCatalog.getFields(source);
+    const filteredFields = schemaCatalog.filterFields(fields, input.query, input.limit);
+    return {
+        source_id: source.id,
+        total: filteredFields.length,
+        fields: filteredFields,
+    };
+}
+export function formatDescribeFieldsResult(result) {
+    const preview = result.fields
+        .slice(0, 10)
+        .map((field) => {
+        const traits = [
+            field.type,
+            field.searchable === true ? "searchable" : undefined,
+            field.aggregatable === true ? "aggregatable" : undefined,
+            field.object_array_path ? `object_array=${field.object_array_path}` : undefined,
+            field.preferred_exact_field ? `exact=${field.preferred_exact_field}` : undefined,
+        ].filter(Boolean);
+        return `${field.name}${traits.length > 0 ? ` (${traits.join(", ")})` : ""}`;
+    })
+        .join("\n");
+    return `Described ${result.total} fields for ${result.source_id}.\n${preview}`;
+}
+export function createDescribeFieldsCallToolResult(result) {
+    return {
+        content: [{ type: "text", text: formatDescribeFieldsResult(result) }],
+        structuredContent: result,
+    };
+}