@havesomecode/kibana-mcp-server 1.1.2 → 1.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (23) hide show
  1. package/README.md +72 -18
  2. package/dist/src/bootstrap.js +426 -0
  3. package/dist/src/cli.js +172 -9
  4. package/dist/src/client_registration.js +197 -0
  5. package/dist/src/config.js +43 -4
  6. package/dist/src/kibana_client.js +280 -92
  7. package/dist/src/profile_store.js +20 -2
  8. package/dist/src/schema_catalog.js +20 -6
  9. package/dist/src/secret_store.js +42 -31
  10. package/dist/src/server.js +86 -14
  11. package/dist/src/setup_flow.js +48 -36
  12. package/dist/src/source_catalog.js +3 -0
  13. package/dist/src/state_lock.js +370 -0
  14. package/dist/src/tools/configure_index.js +104 -0
  15. package/dist/src/tools/describe_fields.js +2 -2
  16. package/dist/src/tools/discover.js +5 -0
  17. package/dist/src/tools/filter.js +1 -0
  18. package/dist/src/tools/query.js +5 -2
  19. package/docs/project/compatibility-matrix.md +2 -1
  20. package/docs/project/distribution-strategy.md +17 -4
  21. package/package.json +2 -1
  22. package/plugins/kibana-log-investigation/.codex-plugin/plugin.json +3 -3
  23. package/skills/kibana-log-investigation/SKILL.md +99 -0
package/skills/kibana-log-investigation/SKILL.md ADDED
@@ -0,0 +1,99 @@
1
+ ---
2
+ name: kibana-log-investigation
3
+ description: Bootstrap and use the Kibana log investigation MCP safely.
4
+ ---
5
+
6
+ # Kibana Log Investigation
7
+
8
+ Use this skill when an operator wants to install, configure, or use the read-only Kibana MCP server from `@havesomecode/kibana-mcp-server`.
9
+
10
+ ## Connection-only installation
11
+
12
+ 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.
13
+
14
+ 1. Verify Node.js 22 or newer is available.
15
+ 2. Resolve connection values from `KIBANA_BASE_URL`, `KIBANA_USERNAME`, and `KIBANA_PASSWORD`, unless the operator supplied safe alternatives.
16
+ 3. Run the prompt-free bootstrap:
17
+
18
+ ```bash
19
+ npx -y @havesomecode/kibana-mcp-server bootstrap \
20
+ --client codex
21
+ ```
22
+
23
+ Bootstrap must:
24
+
25
+ - validate the Kibana base URL and verify the connection through Kibana status only
26
+ - write an empty managed catalog on first install
27
+ - preserve previously and explicitly configured generated sources on idempotent reruns
28
+ - save credentials in the operating-system credential store
29
+ - register the exact, version-pinned stdio command under a transport-hashed Codex name
30
+ - read the Codex registration back and reject conflicting entries
31
+ - restore prior profile state if registration fails
32
+
33
+ A successful command verifies installation, not an index. Do not claim an index is usable until the explicit configuration flow below succeeds.
34
+
35
+ ## Supplying secrets safely
36
+
37
+ 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:
38
+
39
+ ```bash
40
+ printf '%s\n' "$SECRET_VALUE" | npx -y @havesomecode/kibana-mcp-server bootstrap \
41
+ --password-stdin \
42
+ --client codex
43
+ ```
44
+
45
+ If the password is stored under another environment variable, reference its name without exposing its value:
46
+
47
+ ```bash
48
+ npx -y @havesomecode/kibana-mcp-server bootstrap \
49
+ --password-env KIBANA_PROD_PASSWORD \
50
+ --client codex
51
+ ```
52
+
53
+ ## Explicit index configuration
54
+
55
+ After bootstrap:
56
+
57
+ 1. Call `discover`.
58
+ 2. If no source is configured, ask the user which exact Kibana index or index pattern they want to use.
59
+ 3. Wait for the user's answer. Never guess, enumerate, scan, or auto-select an index.
60
+ 4. Call `configure_index` exactly once with the user's value in `index`.
61
+ 5. Report the configured `source_id` and time field. If validation fails, preserve the empty catalog and report the error.
62
+ 6. Call `discover` again before beginning an investigation.
63
+
64
+ `configure_index` contains no credential fields. It may inspect fields and perform one bounded validation search only for the exact user-approved index or pattern.
65
+
66
+ ## Profiles and overrides
67
+
68
+ | Value | Flag | Environment fallback |
69
+ |---|---|---|
70
+ | Profile | `--profile prod` | `KIBANA_PROFILE`, then `default` |
71
+ | Base URL | `--url https://kibana.example.com` | `KIBANA_BASE_URL` |
72
+ | Username | `--username elastic` | `KIBANA_USERNAME` |
73
+ | Password | `--password-stdin` or `--password-env NAME` | `KIBANA_PASSWORD` |
74
+ | Client | `--client codex` or `--client none` | `codex` |
75
+
76
+ To select an existing non-default profile:
77
+
78
+ ```bash
79
+ npx -y @havesomecode/kibana-mcp-server serve --profile prod
80
+ ```
81
+
82
+ ## Failure rules
83
+
84
+ - Never silently import the bundled example catalog.
85
+ - Never pass an index to bootstrap; bootstrap is connection-only.
86
+ - Never call `configure_index` until the user explicitly names the index or pattern.
87
+ - Never add `--replace` merely to make a failed install pass. It intentionally replaces an existing catalog with an empty managed catalog.
88
+ - Never overwrite a conflicting MCP client registration.
89
+ - Never expose a password in logs, summaries, shell history, generated catalogs, or MCP client configuration.
90
+ - If URL, username, or password is unavailable, report the exact missing prerequisite rather than inventing it.
91
+
92
+ ## Using the MCP
93
+
94
+ After a source is explicitly configured:
95
+
96
+ 1. Use `discover` to obtain the source id.
97
+ 2. Use field description before constructing unfamiliar filters or aggregations.
98
+ 3. Start with a bounded time range and a small result limit.
99
+ 4. Keep investigations read-only and cite returned evidence rather than inferring unseen log content.