@havesomecode/kibana-mcp-server 1.3.1 → 1.4.1

package/dist/src/transports/stdio.js

@@ -0,0 +1,46 @@
+import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
+import { DEFAULT_PROFILE_NAME, loadStartupConfiguration } from "../config/startup.js";
+import { createApplication } from "../server.js";
+export async function startMcpServer(envInput = process.env) {
+    // stdio serves one global configuration: the default profile, or the legacy 'configure' flow.
+    // It has a single caller, so per-profile catalogs fall back to one well-known profile.
+    const { startupConfiguration } = await loadStartupConfiguration(envInput);
+    let server;
+    let closing;
+    const close = () => {
+        closing ??= Promise.resolve().then(async () => {
+            process.stdin.off("end", onClose);
+            process.stdin.off("close", onClose);
+            try {
+                await server?.close();
+            }
+            finally {
+                await startupConfiguration.close();
+            }
+        });
+        return closing;
+    };
+    const onClose = () => {
+        void close().catch(() => {
+            process.stderr.write("Failed to close the MCP server or its catalog store.\n");
+            process.exitCode = 1;
+        });
+    };
+    try {
+        const defaultConfig = startupConfiguration.defaultConfig ??
+            (await startupConfiguration.loadProfileConfig?.(DEFAULT_PROFILE_NAME));
+        ({ server } = createApplication(defaultConfig));
+        const transport = new StdioServerTransport();
+        transport.onclose = onClose;
+        // The SDK transport handles data/errors, but does not close itself on stdin EOF.
+        process.stdin.once("end", onClose);
+        process.stdin.once("close", onClose);
+        await server.connect(transport);
+        if (process.stdin.readableEnded || process.stdin.destroyed)
+            await close();
+    }
+    catch (error) {
+        await close().catch(() => { });
+        throw error;
+    }
+}

package/dist/src/types.d.ts

@@ -0,0 +1,254 @@
+import type { CatalogHandle } from "./stores/catalog_store.js";
+export type BackendKind = "elasticsearch_search" | "kibana_internal_search_es";
+export type SchemaBackendKind = "elasticsearch_field_caps" | "kibana_data_views_fields" | "kibana_index_patterns_fields";
+export interface FieldHint {
+    name: string;
+    type?: string;
+    description?: string;
+    aliases?: string[];
+}
+export interface NormalizedFieldHint extends FieldHint {
+    aliases: string[];
+}
+export interface SourceFieldDescriptor {
+    name: string;
+    type?: string;
+    description?: string;
+    aliases?: string[];
+    searchable?: boolean;
+    aggregatable?: boolean;
+    subfields: string[];
+    nested_path?: string;
+    object_array_path?: string;
+    multi_field_parent?: string;
+    preferred_exact_field?: string;
+}
+export interface SourceBackendConfig {
+    kind: BackendKind;
+    path: string;
+    index?: string | string[];
+}
+export interface SourceSchemaBackendConfig {
+    kind: SchemaBackendKind;
+    path?: string;
+    index?: string | string[];
+}
+export interface SourceDefinition {
+    id: string;
+    name: string;
+    description?: string;
+    tags: string[];
+    timeField: string;
+    backend: SourceBackendConfig;
+    schema?: SourceSchemaBackendConfig;
+    fieldHints: FieldHint[];
+    defaultTextFields: string[];
+    evidenceFields: string[];
+}
+export interface KibanaConnectionConfig {
+    baseUrl: string;
+    username: string;
+    password: string;
+    timeoutMs: number;
+}
+export interface AppConfig {
+    kibana: KibanaConnectionConfig;
+    sources: SourceDefinition[];
+}
+export interface ResolvedAppConfig extends AppConfig {
+    profileName?: string;
+    /** Set when the catalog of the profile lives in a catalog store rather than at a plain path. */
+    catalog?: CatalogHandle;
+    sourceCatalogPath?: string;
+    sourceCatalogOrigin?: "environment" | "profile" | "runtime_default" | "static_default";
+}
+export interface SavedProfile {
+    id: string;
+    name: string;
+    baseUrl: string;
+    timeoutMs: number;
+    sourceCatalogPath: string;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface SavedProfileStoreState {
+    version: 1;
+    defaultProfileId: string | null;
+    profiles: SavedProfile[];
+}
+export interface SavedSecret {
+    username: string;
+    password: string;
+}
+export interface DiscoverSourceResult {
+    id: string;
+    name: string;
+    description?: string;
+    tags: string[];
+    time_field: string;
+    field_hints: NormalizedFieldHint[];
+}
+export interface QueryFilter {
+    field: string;
+    value: string | number | boolean;
+}
+export interface NestedQueryFilter extends QueryFilter {
+    path: string;
+}
+export type QueryMode = "hits" | "count" | "histogram" | "terms" | "stats" | "grouped_top_hits";
+export type QuerySort = "asc" | "desc";
+export interface QueryRequest {
+    source_ids: string[];
+    start_time: string;
+    end_time: string;
+    text?: string;
+    filters?: QueryFilter[];
+    nested_filters?: NestedQueryFilter[];
+    cursor?: string;
+    mode?: QueryMode;
+    sort?: QuerySort;
+    sort_by?: string;
+    limit?: number;
+    extract_nested?: boolean;
+    stats_field?: string;
+    top_hits_size?: number;
+    histogram_interval?: string;
+    group_by?: string;
+}
+export interface ResolvedQueryFilter extends QueryFilter {
+    resolved_field: string;
+}
+export interface ResolvedNestedQueryFilter extends NestedQueryFilter {
+    resolved_field: string;
+    query_strategy?: "nested" | "flat_object_path";
+}
+export interface FieldResolutionAdvisory {
+    kind: "preferred_exact_field" | "schema_unavailable" | "non_nested_object_array";
+    source_id: string;
+    purpose: "filter" | "sort" | "group_by";
+    requested_field: string;
+    resolved_field: string;
+    reason: string;
+}
+export interface CompiledSourceQuery {
+    source: SourceDefinition;
+    request: {
+        body: Record<string, unknown>;
+    };
+    resolvedFilters: ResolvedQueryFilter[];
+    resolvedNestedFilters: ResolvedNestedQueryFilter[];
+    resolvedSortBy: string;
+    advisories: FieldResolutionAdvisory[];
+}
+export interface QueryPlan {
+    mode: QueryMode;
+    startTime: string;
+    endTime: string;
+    sort: QuerySort;
+    sortBy?: string;
+    cursor?: string;
+    limit: number;
+    text?: string;
+    nestedFilters?: ResolvedNestedQueryFilter[];
+    statsField?: string;
+    topHitsSize?: number;
+    histogramInterval?: string;
+    groupBy?: string;
+    sourceIds: string[];
+    sourceQueries: CompiledSourceQuery[];
+}
+export interface KibanaSearchExecutionResult {
+    source: SourceDefinition;
+    rawResponse: Record<string, unknown>;
+}
+export interface NormalizedHit {
+    source_id: string;
+    timestamp: string | null;
+    summary: string;
+    document_id: string | null;
+    index: string | null;
+    selected_fields: Record<string, unknown>;
+    nested_matches?: Array<{
+        path: string;
+        documents: Record<string, unknown>[];
+    }>;
+    raw_document: Record<string, unknown>;
+}
+export interface HistogramBucket {
+    key: number | string;
+    key_as_string?: string;
+    count: number;
+}
+export interface TermsBucket {
+    key: string;
+    count: number;
+}
+export interface QueryStructuredResponse {
+    query_echo: {
+        source_ids: string[];
+        start_time: string;
+        end_time: string;
+        text?: string;
+        filters: ResolvedQueryFilter[];
+        nested_filters?: ResolvedNestedQueryFilter[];
+        cursor?: string;
+        mode: QueryMode;
+        sort: QuerySort;
+        sort_by?: string;
+        resolved_sort_by_by_source?: Array<{
+            source_id: string;
+            resolved_sort_by: string;
+        }>;
+        advisories?: FieldResolutionAdvisory[];
+        limit: number;
+        stats_field?: string;
+        top_hits_size?: number;
+        histogram_interval?: string;
+        group_by?: string;
+        truncated: boolean;
+    };
+    total: number;
+    next_cursor?: string;
+    hits?: NormalizedHit[];
+    counts_by_source?: Array<{
+        source_id: string;
+        count: number;
+    }>;
+    histograms?: Array<{
+        source_id: string;
+        buckets: HistogramBucket[];
+    }>;
+    groups?: Array<{
+        source_id: string;
+        field: string;
+        buckets: TermsBucket[];
+    }>;
+    stats?: Array<{
+        source_id: string;
+        field: string;
+        summary: {
+            count: number;
+            min: number | null;
+            max: number | null;
+            avg: number | null;
+            sum: number;
+            p50: number | null;
+            p95: number | null;
+            p99: number | null;
+        };
+    }>;
+    grouped_hits?: Array<{
+        source_id: string;
+        group_by: string;
+        buckets: Array<{
+            key: string;
+            count: number;
+            hits: NormalizedHit[];
+        }>;
+    }>;
+}
+export interface DescribeFieldsResult {
+    source_id: string;
+    total: number;
+    fields: SourceFieldDescriptor[];
+}

package/dist/src/utils/cli_io.d.ts

@@ -0,0 +1,11 @@
+import type { Readable } from "node:stream";
+export interface CliIo {
+    stdout: (text: string) => void;
+    stderr: (text: string) => void;
+    stdin: Readable;
+    stdoutStream: NodeJS.WriteStream;
+    stdinIsTTY?: boolean;
+    env: NodeJS.ProcessEnv;
+    isStdoutOverridden: boolean;
+}
+export declare function createCliIo(overrides?: Partial<CliIo>): CliIo;

package/dist/src/utils/cli_prompts.d.ts

@@ -0,0 +1,9 @@
+import type { SetupPrompter } from "../setup/setup_flow.js";
+import type { CliIo } from "./cli_io.js";
+export interface PromptIo extends SetupPrompter {
+    close(): Promise<void>;
+}
+export declare class PromptCancelledError extends Error {
+    constructor();
+}
+export declare function createPromptIo(io: CliIo): Promise<PromptIo>;

package/dist/src/utils/cli_ui.d.ts

@@ -0,0 +1,6 @@
+import type { CliIo } from "./cli_io.js";
+export interface CliUi {
+    success: (message: string) => void;
+    error: (message: string) => void;
+}
+export declare function createCliUi(io: CliIo): CliUi;

package/dist/src/utils/fs.d.ts

@@ -0,0 +1,3 @@
+export declare function isMissingFileError(error: unknown): error is NodeJS.ErrnoException;
+export declare function readOptionalFile(path: string): Promise<string | undefined>;
+export declare function writeTextAtomically(path: string, content: string): Promise<void>;

package/dist/src/utils/fs.js

@@ -0,0 +1,30 @@
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+export function isMissingFileError(error) {
+    return Boolean(error && typeof error === "object" && "code" in error && error.code === "ENOENT");
+}
+export async function readOptionalFile(path) {
+    try {
+        return await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (isMissingFileError(error))
+            return undefined;
+        throw error;
+    }
+}
+export async function writeTextAtomically(path, content) {
+    const temporaryPath = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    await mkdir(dirname(path), { recursive: true });
+    try {
+        await writeFile(temporaryPath, content, {
+            encoding: "utf8",
+            mode: 0o600,
+        });
+        await rename(temporaryPath, path);
+    }
+    finally {
+        await rm(temporaryPath, { force: true }).catch(() => { });
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@havesomecode/kibana-mcp-server",
-  "version": "1.3.1",
+  "version": "1.4.1",
   "license": "MIT",
   "description": "Read-only MCP server for Kibana-backed log investigation and schema-aware querying",
   "homepage": "https://havesomecode.github.io/kibana-mcp-server/",
@@ -10,6 +10,34 @@
   },
   "type": "module",
   "main": "dist/src/mcp_entry.js",
+  "exports": {
+    ".": "./dist/src/mcp_entry.js",
+    "./config": {
+      "types": "./dist/src/config/config_file.d.ts",
+      "default": "./dist/src/config/config_file.js"
+    },
+    "./stores/ioredis": {
+      "types": "./dist/src/stores/ioredis.d.ts",
+      "default": "./dist/src/stores/ioredis.js"
+    },
+    "./stores/mongodb": {
+      "types": "./dist/src/stores/mongodb.d.ts",
+      "default": "./dist/src/stores/mongodb.js"
+    },
+    "./stores/postgres": {
+      "types": "./dist/src/stores/postgres.d.ts",
+      "default": "./dist/src/stores/postgres.js"
+    },
+    "./stores/redis": {
+      "types": "./dist/src/stores/redis.d.ts",
+      "default": "./dist/src/stores/redis.js"
+    },
+    "./stores/sqlite": {
+      "types": "./dist/src/stores/sqlite.d.ts",
+      "default": "./dist/src/stores/sqlite.js"
+    },
+    "./package.json": "./package.json"
+  },
   "bin": {
     "kibana-mcp-server": "dist/src/bin/kibana-mcp-server.js"
   },
@@ -21,6 +49,9 @@
     "dist/**",
     "plugins/kibana-log-investigation/.mcp.json",
     "plugins/kibana-log-investigation/.codex-plugin/plugin.json",
+    "plugins/kibana-log-investigation/mcp-launcher.mjs",
+    "plugins/kibana-log-investigation/dist/**",
+    "plugins/kibana-log-investigation/skills/**",
     "skills/kibana-log-investigation/**",
     "README.md",
     "LICENSE",
@@ -31,13 +62,16 @@
     "node": ">=22.0.0"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
+    "build": "tsc -p tsconfig.build.json && node scripts/build-plugin.mjs",
     "check:types": "tsc --noEmit -p tsconfig.json",
     "lint": "biome lint .",
     "format": "biome format . --write",
     "format:check": "biome check . --linter-enabled=false",
     "check": "npm run check:types && npm run lint && npm run format:check",
     "dev": "tsx src/mcp_entry.ts",
+    "docs:dev": "vitepress dev website",
+    "docs:build": "vitepress build website",
+    "docs:preview": "vitepress preview website",
     "release": "semantic-release",
     "release:dry-run": "semantic-release --dry-run",
     "setup": "node dist/src/bin/kibana-mcp-server.js setup",
@@ -55,14 +89,41 @@
     "commander": "^14.0.3",
     "zod": "^4.0.0"
   },
+  "peerDependencies": {
+    "ioredis": ">=5.0.0",
+    "mongodb": "^6.0.0 || ^7.0.0",
+    "pg": "^8.0.0",
+    "redis": "^6.0.0"
+  },
+  "peerDependenciesMeta": {
+    "ioredis": {
+      "optional": true
+    },
+    "mongodb": {
+      "optional": true
+    },
+    "pg": {
+      "optional": true
+    },
+    "redis": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@biomejs/biome": "^1.8.3",
     "@commitlint/cli": "^20.1.0",
     "@commitlint/config-conventional": "^20.0.0",
     "@types/node": "^25.5.2",
+    "esbuild": "^0.28.2",
+    "ioredis": "^6.0.0",
+    "mongodb": "^7.6.0",
+    "pg": "^8.23.0",
+    "redis": "^6.2.1",
     "semantic-release": "^25.0.1",
     "tsx": "^4.0.0",
     "typescript": "^7.0.2",
+    "vitepress": "^1.6.4",
+    "vitepress-plugin-llms": "^1.14.0",
     "vitest": "^4.1.3"
   }
 }

package/plugins/kibana-log-investigation/.mcp.json

@@ -3,8 +3,9 @@
     "kibana-log-investigation": {
       "type": "stdio",
       "command": "node",
-      "args": ["./dist/src/mcp_entry.js"],
-      "note": "Local stdio MCP server for this repo. Requires Node.js 22+ and a built dist/ directory. If dependencies or dist are missing, run npm install and npm run build from the repository root first."
+      "args": ["./mcp-launcher.mjs"],
+      "cwd": ".",
+      "note": "Requires Node.js 22+. The built plugin includes its runtime dependencies. Build the checkout before installing the plugin. If runtime files are missing, rebuild and reinstall; opening new discussions does not repair startup failures."
     }
   }
 }

package/plugins/kibana-log-investigation/dist/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zacaria
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.