Architecture
Source layout
| Folder | Content |
|---|---|
src/bin/ | The executable and CLI wiring |
src/commands/ | One Commander command per file: serve, setup, bootstrap |
src/config/ | Environment parsing, configuration file loading, startup resolution |
src/kibana/ | Kibana client, schema and source catalogs |
src/profiles/ | Profile runtimes, saved profiles, secrets, state lock |
src/query/ | Query compilation, cursors, result normalization |
src/setup/ | Bootstrap, guided setup, client registration |
src/stores/ | The catalog store contract and its implementations |
src/tools/ | One MCP tool per file |
src/transports/ | stdio and HTTP transports |
src/server.ts | Builds the MCP server and registers the tools |
A tool call
- The transport receives the request. Over HTTP it validates the shared secret and reads the profile header.
createApplicationbuilds an MCP server. Over HTTP there is one per request; state lives outside it.- The tool handler asks the profile registry for the runtime of the profile. A runtime holds the configuration, the source catalog, the Kibana client and the schema cache.
- The runtime is bound to the call through
AsyncLocalStorage, so deeper code reads it without receiving it as an argument. - The tool runs against that runtime only.
Profile registry
- Runtimes are created on demand and cached, with a least-recently-used limit.
- Profiles sharing a Kibana connection share one client, hence one concurrency budget.
- A store-backed catalog is read again on every call. The parsed catalog and the schema cache are kept while its content is unchanged.
Catalog stores
Every catalog write goes through one contract: read the content, compute the next one, replace it only if it is unchanged. Files, Redis, PostgreSQL, MongoDB and SQLite all implement it. See Custom store.
Startup modes
| Configuration | Result |
|---|---|
Connection plus a store, or {profile} in the catalog path | One connection, one catalog per profile |
| Connection plus a plain catalog path | One connection, one catalog |
| Saved profiles | One connection and one catalog per saved profile |
| Connection without a catalog path or store | Startup fails; an explicit catalog is required |
| Nothing | Startup fails: No saved Kibana connection is available. Run connection bootstrap first. |