@havesomecode/kibana-mcp-server 1.4.0 → 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,6 +7,18 @@ 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, 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.