@havesomecode/kibana-mcp-server 1.3.1 → 1.4.1

package/plugins/kibana-log-investigation/dist/mcp_entry.mjs.LEGAL.txt

@@ -0,0 +1,8 @@
+Bundled license information:
+
+@modelcontextprotocol/server/dist/src-CX2iR2pK.mjs:
+  /*!
+  * content-type
+  * Copyright(c) 2015 Douglas Christopher Wilson
+  * MIT Licensed
+  */

package/plugins/kibana-log-investigation/mcp-launcher.mjs

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+
+import { existsSync } from "node:fs";
+
+const bundle = new URL("./dist/mcp_entry.mjs", import.meta.url);
+
+if (Number(process.versions.node.split(".")[0]) < 22) {
+  console.error("Kibana MCP requires Node.js 22 or newer. Update Node.js before restarting Codex.");
+  process.exitCode = 1;
+} else if (!existsSync(bundle)) {
+  console.error(
+    "Kibana MCP plugin runtime is missing. Run npm ci and npm run build in the source checkout, " +
+      "then reinstall the built plugin into Codex. Opening another discussion cannot repair this installation.",
+  );
+  process.exitCode = 1;
+} else {
+  try {
+    await import(bundle.href);
+  } catch (error) {
+    const code = typeof error?.code === "string" ? error.code : "STARTUP_ERROR";
+    console.error(
+      `Kibana MCP plugin could not load (${code}). Rebuild and reinstall the plugin; inspect sanitized startup stderr if the failure persists. Do not share credentials.`,
+    );
+    process.exitCode = 1;
+  }
+}

package/plugins/kibana-log-investigation/skills/ensure-node-runtime/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: ensure-node-runtime
+description: Ensure Node.js 22+ is available for this repo using a user-level install path on Windows, macOS, or Linux.
+---
+
+# Ensure Node Runtime
+
+Use this skill when the repository has been cloned locally and Codex needs to make sure Node.js is available before building or running the Kibana MCP server.
+
+This skill prefers user-level installation paths and avoids system-wide package installs.
+
+## Goals
+
+- detect whether `node` and `npm` are already usable
+- install Node.js 22+ at user scope when missing
+- choose commands based on the current operating system and shell
+- verify the runtime before continuing with repo setup
+
+## Detection
+
+1. Check whether `node` and `npm` are already present:
+   - `node --version`
+   - `npm --version`
+2. If `node` is present and major version is `22` or newer, stop here.
+3. Otherwise install a user-level Node version manager, then install Node.js `22`.
+
+## Preferred cross-platform strategy
+
+Use `fnm` as the default version manager because it works on Windows, macOS, and Linux and supports shell auto-configuration.
+
+The repo pins the desired major in `.node-version`, so after `fnm` is installed you can use either:
+
+- `fnm install 22 && fnm default 22`
+- or `fnm use --install-if-missing`
+
+## Windows
+
+Prefer a PowerShell-first install path.
+
+Use `winget` when it is available. If it is blocked or unavailable, fall back to the official `fnm` release binary extracted into the user's home directory.
+
+Reference basis:
+
+- `fnm` officially documents Windows installation via `winget`
+- `fnm` also supports installation from a release binary on Windows
+- PowerShell profile setup is the standard way to enable `fnm` in Windows shells
+
+### Recommended flow
+
+1. If `fnm` already exists, skip to Node installation.
+2. If `winget` is available:
+   - `winget install Schniz.fnm`
+3. If `winget` is not available or is blocked:
+   - download the latest Windows `fnm` release binary from the official GitHub releases page
+   - extract it into a user-level directory such as `%USERPROFILE%\\.local\\bin\\fnm` or `%USERPROFILE%\\.fnm\\bin`
+   - add that directory to the user PATH in PowerShell
+4. Configure the current PowerShell session:
+   - `fnm env --use-on-cd --shell powershell | Out-String | Invoke-Expression`
+5. Persist shell integration for future PowerShell sessions:
+   - create `$PROFILE` if needed
+   - append `fnm env --use-on-cd --shell powershell | Out-String | Invoke-Expression` to `$PROFILE` if it is not already present
+6. Install and select Node.js 22:
+   - `fnm install 22`
+   - `fnm default 22`
+
+## macOS
+
+Prefer a user-level `fnm` install using the official install script.
+
+### Recommended flow
+
+1. If `fnm` is missing:
+   - `curl -fsSL https://fnm.vercel.app/install | bash`
+2. Configure the current shell:
+   - bash/zsh: `eval "$(fnm env --use-on-cd)"`
+   - fish: `fnm env --use-on-cd | source`
+3. Persist shell integration:
+   - bash: add `eval "$(fnm env --use-on-cd)"` to `~/.bashrc`
+   - zsh: add `eval "$(fnm env --use-on-cd)"` to `~/.zshrc`
+   - fish: add `fnm env --use-on-cd | source` to `~/.config/fish/config.fish`
+4. Install and select Node.js 22:
+   - `fnm install 22`
+   - `fnm default 22`
+
+## Linux
+
+Use the same user-level `fnm` flow as macOS.
+
+### Recommended flow
+
+1. If `fnm` is missing:
+   - `curl -fsSL https://fnm.vercel.app/install | bash`
+2. Configure and persist shell integration for the active shell:
+   - bash: `eval "$(fnm env --use-on-cd)"` plus `~/.bashrc`
+   - zsh: `eval "$(fnm env --use-on-cd)"` plus `~/.zshrc`
+   - fish: `fnm env --use-on-cd | source` plus `~/.config/fish/config.fish`
+3. Install and select Node.js 22:
+   - `fnm install 22`
+   - `fnm default 22`
+
+## Verification
+
+After installation, verify all of:
+
+- `fnm --version`
+- `node --version`
+- `npm --version`
+
+The resulting `node --version` must report major `22` or higher.
+
+## Notes
+
+- Prefer user-level installs over admin installs.
+- On Windows, prefer PowerShell-native flows and avoid assuming Scoop is available.
+- If the current shell cannot pick up the new PATH cleanly, restart the terminal or restart Codex after installation.
+- Once Node is available, continue with:
+  - `npm install`
+  - `npm run build`

package/plugins/kibana-log-investigation/skills/install-and-configure/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: install-and-configure
+description: Install the repo plugin with connection-only bootstrap.
+---
+
+# Install and Configure
+
+Use this skill only when the repository has been cloned locally and Codex needs the repo-scoped plugin. For public installs, use the canonical `skills/kibana-log-investigation` skill and the published npm package instead.
+
+## Version-matched README handoff
+
+Resolve the selected branch or tag to the full installation commit SHA before following installation instructions. Read the README at this immutable URL:
+
+```text
+https://raw.githubusercontent.com/Havesomecode/kibana-mcp-server/<resolved-commit>/README.md
+```
+
+Branch and tag names are resolution inputs, not final handoff URLs. Use `INSTALL.md` and skills from the same resolved installation commit. Do not infer a Git tag from an npm version or silently fall back to master. Detached installs use `git rev-parse HEAD`'s full commit SHA.
+
+From a maintained repository root containing the helper, run `node scripts/readme-handoff.mjs <resolved-installation-ref>`. Include its verified `url` and `commit` in agent handoffs. The helper resolves local refs and verifies the downloaded README against the selected Git object. Unknown refs, missing READMEs, or retrieval/content verification failures must be reported instead of presenting another version's instructions. The helper is repository-only; historical installations without it require explicit ref resolution and README retrieval verification.
+
+## Workflow
+
+1. Ensure Node.js 22+ is available. Use `ensure-node-runtime` when needed.
+2. From the repository root:
+
+```bash
+npm install
+npm run build
+```
+
+3. Confirm the build produced `plugins/kibana-log-investigation/dist/mcp_entry.mjs`. Install `Kibana Log Investigation` from the repo-local Codex marketplace only after building. The built plugin includes runtime dependencies and launches from its installed directory, not the checkout.
+4. Restart Codex if the plugin directory does not refresh automatically.
+5. Resolve the Kibana connection through `KIBANA_BASE_URL`, `KIBANA_USERNAME`, and `KIBANA_PASSWORD`, or safe CLI alternatives.
+6. Bootstrap only the connection, without registering a duplicate global MCP:
+
+```bash
+node dist/src/bin/kibana-mcp-server.js bootstrap --client none
+```
+
+7. Confirm bootstrap reports an empty source catalog. It must not inspect or configure indexes.
+8. In a fresh Codex session, call `discover`. When it reports no sources, ask the operator which exact index or index pattern to configure.
+9. Only after the operator answers, call `configure_index` with exactly that value. Then run `discover` again.
+
+## Rules
+
+- Do not edit client configuration files.
+- Separate saved configuration, process startup, tools in the current discussion, and real backend access. If startup fails, inspect sanitized stderr and repair/reinstall the plugin before requesting another discussion. Run `npm run verify:entrypoint` for the isolated packaged-plugin handshake; it is not a native Codex or real-backend check.
+- Do not use the bundled example catalog unless the operator explicitly requests example data.
+- Do not put passwords in command arguments or summaries.
+- Do not guess, enumerate, scan, or auto-select Kibana indexes.
+- Do not call `configure_index` until the operator explicitly names the index or pattern.
+- Use `--profile NAME` for additional environments.
+- Use `serve --profile NAME` when invoking a non-default profile outside the repo plugin.
+- `KIBANA_BASE_URL` is a base prefix. Do not append `/internal/search/es`.

package/skills/kibana-log-investigation/SKILL.md

@@ -7,34 +7,75 @@ description: Bootstrap and use the Kibana log investigation MCP safely.
 
 Use this skill when an operator wants to install, configure, or use the read-only Kibana MCP server from `@havesomecode/kibana-mcp-server`.
 
+## Version-matched installation instructions
+
+Before installing or generating a handoff, resolve the selected branch, tag, or package metadata to the full installation commit SHA. Read `README.md` at this immutable URL:
+
+```text
+https://raw.githubusercontent.com/Havesomecode/kibana-mcp-server/<resolved-commit>/README.md
+```
+
+Branch and tag names are resolution inputs, not final handoff URLs. Read `INSTALL.md` and skills from the same resolved installation commit. Do not infer a Git tag from an npm version. Resolve the exact npm package's `gitHead` instead, or report missing metadata; pin the package installation to the same exact version. Never silently fall back to master if the ref or README is missing or retrieval fails.
+
+In a maintained clone with the repository-only helper, run `node scripts/readme-handoff.mjs <resolved-installation-ref>` and use its verified `url` and `commit` in the handoff. The helper checks the retrieved README against that Git commit before output. It is not an npm command and need not exist in historical tags. If unavailable, resolve the selected ref and validate its raw README explicitly; do not invent successful retrieval. See `INSTALL.md`'s version-matched handoff section.
+
 ## 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 +127,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);
-}