@havesomecode/kibana-mcp-server 1.3.0 → 1.4.0

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.0",
+  "version": "1.4.0",
   "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"
   },
@@ -38,6 +66,9 @@
     "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 +86,40 @@
     "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",
+    "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/skills/kibana-log-investigation/SKILL.md

@@ -9,32 +9,61 @@ Use this skill when an operator wants to install, configure, or use the read-onl
 
 ## Connection-only installation
 
-Do not edit Codex or MCP configuration files by hand. Bootstrap establishes only the Kibana connection and an empty managed source catalog. It must not list, scan, infer, or configure indexes.
+Do not edit Codex, Claude Code, or other MCP configuration files by hand. Bootstrap establishes only the Kibana connection and an empty managed source catalog. It must not list, scan, infer, or configure indexes.
 
 1. Verify Node.js 22 or newer is available.
 2. Resolve connection values from `KIBANA_BASE_URL`, `KIBANA_USERNAME`, and `KIBANA_PASSWORD`, unless the operator supplied safe alternatives.
-3. Run the prompt-free bootstrap:
+3. Choose the client mode for the agent you are running in (see below).
+4. Run the prompt-free bootstrap with that mode.
+
+### Choosing the client mode
+
+Bootstrap can register the MCP server itself only in Codex. Everywhere else the server is registered by a plugin or by the operator, and bootstrap must only save the connection.
+
+| You are running in | The MCP server is registered by | Client mode |
+|---|---|---|
+| Codex | bootstrap | `--client codex` |
+| Claude Code | the `kibana-log-investigation` plugin | `--client none` |
+| Any other agent | the operator's MCP configuration | `--client none` |
+
+Codex:
 
 ```bash
 npx -y @havesomecode/kibana-mcp-server bootstrap \
   --client codex
 ```
 
+Claude Code and other agents:
+
+```bash
+npx -y @havesomecode/kibana-mcp-server bootstrap \
+  --client none
+```
+
+If you are not running in Codex and the tools of this server (`discover`, `configure_index`) are not available in the session, the server is not registered. Do not write MCP configuration yourself. Ask the operator to register it:
+
+- in Claude Code, by installing the plugin: `/plugin marketplace add Havesomecode/kibana-mcp-server`, then `/plugin install kibana-log-investigation@kibana-mcp-server`;
+- in any other agent, by declaring the stdio command `npx -y @havesomecode/kibana-mcp-server serve` in its MCP configuration.
+
+With `--client none`, a server that was already running when bootstrap completed still has no connection. Ask the operator to reconnect the MCP server or start a new session before calling its tools.
+
+### What bootstrap does
+
 Bootstrap must:
 
 - validate the Kibana base URL and verify the connection through Kibana status only
 - write an empty managed catalog on first install
 - preserve previously and explicitly configured generated sources on idempotent reruns
 - save credentials in the operating-system credential store
-- register the exact, version-pinned stdio command under a transport-hashed Codex name
-- read the Codex registration back and reject conflicting entries
+- with `--client codex`, register the exact, version-pinned stdio command under a transport-hashed Codex name, read the registration back, and reject conflicting entries
+- with `--client none`, leave every MCP client configuration untouched
 - restore prior profile state if registration fails
 
 A successful command verifies installation, not an index. Do not claim an index is usable until the explicit configuration flow below succeeds.
 
 ## Supplying secrets safely
 
-Never put a password directly in a command argument. Prefer a pre-provisioned `KIBANA_PASSWORD` environment variable. When a secret is available on stdin, use:
+Never put a password directly in a command argument. Prefer a pre-provisioned `KIBANA_PASSWORD` environment variable. The examples below use `--client codex`; substitute the client mode chosen above. When a secret is available on stdin, use:
 
 ```bash
 printf '%s\n' "$SECRET_VALUE" | npx -y @havesomecode/kibana-mcp-server bootstrap \
@@ -86,6 +115,8 @@ npx -y @havesomecode/kibana-mcp-server serve --profile prod
 - Never call `configure_index` until the user explicitly names the index or pattern.
 - Never add `--replace` merely to make a failed install pass. It intentionally replaces an existing catalog with an empty managed catalog.
 - Never overwrite a conflicting MCP client registration.
+- Never write or edit an MCP client configuration file to register the server; only bootstrap in Codex, a plugin, or the operator does that.
+- Never use the legacy `configure` tool to supply credentials. If it is the only setup tool offered, the server has no saved connection: run bootstrap, then have the server reconnected.
 - Never expose a password in logs, summaries, shell history, generated catalogs, or MCP client configuration.
 - If URL, username, or password is unavailable, report the exact missing prerequisite rather than inventing it.
 

package/dist/src/mcp_runtime.js

@@ -1,23 +0,0 @@
-import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
-import { NoSavedProfileError, PROFILE_NAME_ENV, loadConfigFromEnvironment } from "./config.js";
-import { createApplication } from "./server.js";
-function hasBootstrapConfig(env) {
-    return Boolean(env.KIBANA_BASE_URL && env.KIBANA_USERNAME && env.KIBANA_PASSWORD);
-}
-export async function startMcpServer(envInput = process.env) {
-    let config = undefined;
-    try {
-        config = await loadConfigFromEnvironment(envInput);
-    }
-    catch (error) {
-        if (hasBootstrapConfig(envInput) || envInput[PROFILE_NAME_ENV]?.trim()) {
-            throw error;
-        }
-        if (!(error instanceof NoSavedProfileError)) {
-            throw error;
-        }
-    }
-    const { server } = createApplication(config);
-    const transport = new StdioServerTransport();
-    await server.connect(transport);
-}