@kealthas-dev/opencode-mcp-loki 1.0.9 → 1.0.11

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 (3) hide show
  1. package/README.md +23 -7
  2. package/dist/server.js +34 -17
  3. package/package.json +2 -2
package/README.md CHANGED
@@ -12,13 +12,13 @@ A minimal MCP server exposing three read-only tools — `loki_query_range`, `lok
12
12
 
13
13
  ## Configuration
14
14
 
15
- Config is file-based, not env-var-based — same two-file split as `mcp-servers/oracle/` (see its README's Configuration section for the fullest writeup of the pattern), except unlike `mcp-servers/oracle/`, the Loki config file has a default location too:
15
+ Config is file-based, not env-var-based — same two-file split as `mcp-servers/oracle/` (see its README's Configuration section for the fullest writeup of the pattern). Unlike `mcp-servers/oracle/`'s older scheme, the *location* a config file is read from is never user-supplied here — only a short environment name is, which selects a fixed file. This is deliberate: an arbitrary-path env var invites a caller's shell not expanding `~`, a quoted value suppressing that expansion, or a typo'd relative path resolving against whatever `cwd` happens to be — all silently pointing at the wrong file. A bare name has none of that surface.
16
16
 
17
17
  - **`$HOME/.config/kealthas-dev/opencode-mcp-loki/server.json`** — the port to listen on, at this one fixed path always. Optional: if missing, defaults to `8091`; if present, must be valid JSON or the server refuses to start. Shape (see `server.example.json`):
18
18
  ```json
19
19
  { "LOKI_MCP_PORT": 8091 }
20
20
  ```
21
- - **A Loki config file, normally at `$HOME/.config/kealthas-dev/opencode-mcp-loki/config.json`** — that fixed path is the default (covers the common single-Loki-instance setup with nothing to set), but `LOKI_CONFIG_FILE` overrides it with any other path when set, for multiple environments — e.g. `configs/dev.json`, `configs/prod.json`, `configs/uat.json` alongside it, switched between with `LOKI_CONFIG_FILE=.../configs/prod.json`. The server prints a sample and exits if neither the default file nor an env-var-pointed file exists, or if `LOKI_BASE_URL` is missing from whichever one is read. Shape (see `config.example.json`):
21
+ - **A Loki config file.** With no `LOKI_CONFIG_ENV` set, it's read from `$HOME/.config/kealthas-dev/opencode-mcp-loki/config.json` — covers the common single-Loki-instance setup with nothing to configure. For multiple environments, set `LOKI_CONFIG_ENV` to a plain name (letters/digits/`-`/`_` only) and it reads `$HOME/.config/kealthas-dev/opencode-mcp-loki/configs/<name>.json` instead — e.g. `LOKI_CONFIG_ENV=prod` reads `configs/prod.json`. The server prints a sample and exits if the resolved file doesn't exist, if `LOKI_CONFIG_ENV` isn't a plain name, or if `LOKI_BASE_URL` is missing from whichever file is read. Shape (see `config.example.json`):
22
22
  ```json
23
23
  {
24
24
  "LOKI_BASE_URL": "http://192.168.1.100:3100",
@@ -30,21 +30,35 @@ Config is file-based, not env-var-based — same two-file split as `mcp-servers/
30
30
  ```
31
31
  Only `LOKI_BASE_URL` (no trailing path, e.g. `http://192.168.1.100:3100`) is required — Loki is commonly reachable unauthenticated on an internal LAN, unlike `mcp-servers/oracle/`. `LOKI_USERNAME`/`LOKI_PASSWORD` are HTTP basic auth; `LOKI_ORG_ID` sets `X-Scope-OrgID` for multi-tenant Loki / Grafana Cloud-style setups; `LOKI_DEFAULT_TZ_OFFSET` defaults to `+08:00` if omitted.
32
32
 
33
+ **When Loki has no directly reachable port of its own** — a common setup where Grafana is the only thing exposed and Loki sits behind it — set `LOKI_VIA_GRAFANA: true` and `LOKI_BASE_URL` becomes Grafana's own URL instead of Loki's. Every request routes through Grafana's datasource-proxy endpoint (`/api/datasources/proxy/<id>/loki/api/v1/...`) rather than hitting a Loki API root directly. `LOKI_USERNAME`/`LOKI_PASSWORD` still work unchanged in this mode — Basic Auth against a real Grafana user account, not Loki itself (Grafana's own default is `admin`/`admin` until changed). `LOKI_GRAFANA_DATASOURCE_ID` is the Loki datasource's ID as assigned inside that Grafana instance (visible in its Data Sources page URL) — optional, defaults to `"1"`, which is what a single-datasource Grafana instance almost always has:
34
+ ```json
35
+ {
36
+ "LOKI_BASE_URL": "http://192.168.1.100:3100",
37
+ "LOKI_USERNAME": "admin",
38
+ "LOKI_PASSWORD": "admin",
39
+ "LOKI_VIA_GRAFANA": true,
40
+ "LOKI_GRAFANA_DATASOURCE_ID": "1"
41
+ }
42
+ ```
43
+ A telltale sign you need this mode: querying with `LOKI_VIA_GRAFANA` unset returns an HTML page (often a 404) instead of a JSON error — real Loki's own error responses are always plain text/JSON, never HTML, so an HTML response means the request landed on Grafana's own web UI instead of Loki's API.
44
+
33
45
  ## Run
34
46
 
35
47
  Published as `@kealthas-dev/opencode-mcp-loki` — on a real deployment, install it globally and run the resulting binary (see SETUP.md step 7):
36
48
 
37
49
  ```bash
38
50
  npm install -g @kealthas-dev/opencode-mcp-loki
39
- LOKI_CONFIG_FILE=~/.config/kealthas-dev/opencode-mcp-loki/configs/prod.json opencode-mcp-loki
51
+ mkdir -p ~/.config/kealthas-dev/opencode-mcp-loki/configs
52
+ # real config at ~/.config/kealthas-dev/opencode-mcp-loki/configs/prod.json (see config.example.json for the shape)
53
+ LOKI_CONFIG_ENV=prod opencode-mcp-loki
40
54
  ```
41
55
 
42
- For local dev/testing against this repo's own checkout (this directory, not the published package), point `LOKI_CONFIG_FILE` at a real config file (see `config.example.json` for the shape — the sandbox's docker-entrypoint.sh generates one automatically, see Testing below):
56
+ For local dev/testing against this repo's own checkout (this directory, not the published package), same idea — drop a real config file at the default location, or a named one under `configs/` (see `config.example.json` for the shape — the sandbox's docker-entrypoint.sh generates the default one automatically, see Testing below):
43
57
 
44
58
  ```bash
45
59
  npm install
46
60
  npm run build
47
- LOKI_CONFIG_FILE=/path/to/a/real/config.json npm start
61
+ npm start # reads ~/.config/kealthas-dev/opencode-mcp-loki/config.json
48
62
  ```
49
63
 
50
64
  `npm run dev` runs `src/server.ts` directly via `tsx watch` instead, for a compile-on-save loop.
@@ -60,10 +74,12 @@ docker compose -f docker/docker-compose.loki.yml up -d
60
74
  docker/dev.sh run --rm opencode-dev bash
61
75
  ```
62
76
 
63
- `LOKI_CONFIG_FILE` is already set inside that shell — `docker-entrypoint.sh` generates a config file from the sandbox's `LOKI_BASE_URL` compose env var and points `LOKI_CONFIG_FILE` at it. `cd mcp-servers/loki && npm install && npm run build && npm start`, then hit `http://localhost:8091/mcp` from an MCP client or `curl`.
77
+ The default config file is already in place inside that shell — `docker-entrypoint.sh` generates `~/.config/kealthas-dev/opencode-mcp-loki/config.json` from the sandbox's `LOKI_BASE_URL` compose env var. `cd mcp-servers/loki && npm install && npm run build && npm start`, then hit `http://localhost:8091/mcp` from an MCP client or `curl`.
64
78
 
65
79
  `loki.test.ts` (see `tests/README.md`) doesn't need this manual dance — it builds its own config files into a fake `$HOME` per spawned server (same pattern as `mcp-servers/oracle/oracle.test.ts`) and starts/stops its own `dist/server.js` process on its own port as part of the test run, seeding its own test log lines by pushing directly to Loki's push API (not through this MCP server, which is read-only by design).
66
80
 
67
81
  ## Status
68
82
 
69
- **Verified end-to-end and automated.** `loki.test.ts` covers tool listing, `loki_labels`/`loki_label_values` finding pushed test data, `loki_query_range` finding a pushed log line by content, an empty-result query returning cleanly (not an error), and a malformed LogQL query returning a clean error — driven over the real Streamable HTTP transport against the sandbox's `loki` service. Wired into `deploy/opencode.json.example` (`mcp.loki`, `type: "remote"`, `enabled: true`).
83
+ **Direct-to-Loki path verified end-to-end and automated.** `loki.test.ts` covers tool listing, `loki_labels`/`loki_label_values` finding pushed test data, `loki_query_range` finding a pushed log line by content, an empty-result query returning cleanly (not an error), and a malformed LogQL query returning a clean error — driven over the real Streamable HTTP transport against the sandbox's `loki` service. Wired into `deploy/opencode.json.example` (`mcp.loki`, `type: "remote"`, `enabled: true`).
84
+
85
+ **`LOKI_VIA_GRAFANA` verified only against a fake stand-in HTTP server** (confirms the request lands on `/api/datasources/proxy/<id>/...` with the right Basic Auth header) — not against a real Grafana instance, and not covered by `loki.test.ts`. See `mcp-servers/TODO.md` for adding a real Grafana fixture to the sandbox.
package/dist/server.js CHANGED
@@ -2,7 +2,7 @@
2
2
  import http from "node:http";
3
3
  import { existsSync, readFileSync } from "node:fs";
4
4
  import { homedir } from "node:os";
5
- import { join, resolve } from "node:path";
5
+ import { join } from "node:path";
6
6
  import { Server } from "@modelcontextprotocol/sdk/server/index.js";
7
7
  import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
8
8
  import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
@@ -16,6 +16,8 @@ const SAMPLE_LOKI_CONFIG = {
16
16
  LOKI_PASSWORD: "password (optional)",
17
17
  LOKI_ORG_ID: "tenant-id (optional, multi-tenant Loki / Grafana Cloud-style setups)",
18
18
  LOKI_DEFAULT_TZ_OFFSET: "+08:00 (optional, defaults to +08:00)",
19
+ LOKI_VIA_GRAFANA: "true (optional - set when Loki is only reachable through Grafana's own datasource proxy, not directly; LOKI_BASE_URL becomes Grafana's URL in that case)",
20
+ LOKI_GRAFANA_DATASOURCE_ID: "1 (optional, only used when LOKI_VIA_GRAFANA is true - defaults to 1)",
19
21
  };
20
22
  function printSampleConfig(label, path, sample) {
21
23
  console.error(`\nExpected ${label} at: ${path}\n`);
@@ -45,27 +47,37 @@ function loadServerConfig() {
45
47
  process.exit(1);
46
48
  }
47
49
  }
48
- // Loki connection details are per-environment and read from whatever path
49
- // LOKI_CONFIG_FILE points at - unrestricted filename/location, so the same
50
- // install can be pointed at a different Loki instance just by changing this
51
- // one env var. LOKI_CONFIG_FILE itself is optional: if unset, this falls
52
- // back to config.json next to server.json in CONFIG_DIR, covering the
53
- // common single-environment case without requiring the env var on every
54
- // start - multi-environment setups still override it per deployment. Only
55
- // LOKI_BASE_URL is required - Loki is commonly reachable unauthenticated on
56
- // an internal LAN, unlike mcp-servers/oracle.
50
+ // Loki connection details are per-environment, but the *location* they're
51
+ // read from is never user-supplied - only a short env name is (e.g. "prod"),
52
+ // which selects a fixed file under CONFIG_DIR/configs/. This avoids the
53
+ // class of bug an arbitrary-path env var invites: a caller's shell not
54
+ // expanding "~", a quoted value suppressing that expansion, a typo'd
55
+ // relative path resolving against whatever cwd happens to be - all of
56
+ // which point path.resolve() somewhere unintended, silently. A bare name
57
+ // has none of that surface. No env var set falls back to config.json
58
+ // directly in CONFIG_DIR (not configs/) for the common single-environment
59
+ // case. Only LOKI_BASE_URL is required in the file itself - Loki is
60
+ // commonly reachable unauthenticated on an internal LAN, unlike
61
+ // mcp-servers/oracle.
57
62
  const DEFAULT_LOKI_CONFIG_PATH = join(CONFIG_DIR, "config.json");
63
+ const LOKI_CONFIGS_DIR = join(CONFIG_DIR, "configs");
64
+ const CONFIG_ENV_NAME_RE = /^[a-zA-Z0-9_-]+$/;
58
65
  function loadLokiConfig() {
59
- const envPath = process.env.LOKI_CONFIG_FILE;
60
- const resolvedPath = resolve(envPath ?? DEFAULT_LOKI_CONFIG_PATH);
66
+ const envName = process.env.LOKI_CONFIG_ENV;
67
+ if (envName !== undefined && !CONFIG_ENV_NAME_RE.test(envName)) {
68
+ console.error(`LOKI_CONFIG_ENV must be a plain name (letters, digits, "-", "_"), got: ${JSON.stringify(envName)}`);
69
+ process.exit(1);
70
+ }
71
+ const resolvedPath = envName ? join(LOKI_CONFIGS_DIR, `${envName}.json`) : DEFAULT_LOKI_CONFIG_PATH;
61
72
  if (!existsSync(resolvedPath)) {
62
- if (envPath) {
73
+ if (envName) {
63
74
  console.error(`Loki config file not found: ${resolvedPath}`);
75
+ console.error(`(LOKI_CONFIG_ENV=${envName} looks for "${envName}.json" under ${LOKI_CONFIGS_DIR})`);
64
76
  }
65
77
  else {
66
- console.error(`No LOKI_CONFIG_FILE set and no default config file at: ${resolvedPath}`);
67
- console.error("Either create that file, or point LOKI_CONFIG_FILE at one, e.g.:");
68
- console.error(" LOKI_CONFIG_FILE=~/.config/kealthas-dev/opencode-mcp-loki/configs/prod.json opencode-mcp-loki");
78
+ console.error(`No LOKI_CONFIG_ENV set and no default config file at: ${resolvedPath}`);
79
+ console.error(`Either create that file, or set LOKI_CONFIG_ENV to the name of a file under ${LOKI_CONFIGS_DIR}/, e.g.:`);
80
+ console.error(" LOKI_CONFIG_ENV=prod opencode-mcp-loki");
69
81
  }
70
82
  printSampleConfig("Loki config file", resolvedPath, SAMPLE_LOKI_CONFIG);
71
83
  process.exit(1);
@@ -81,6 +93,8 @@ function loadLokiConfig() {
81
93
  LOKI_PASSWORD: raw.LOKI_PASSWORD,
82
94
  LOKI_ORG_ID: raw.LOKI_ORG_ID,
83
95
  LOKI_DEFAULT_TZ_OFFSET: raw.LOKI_DEFAULT_TZ_OFFSET,
96
+ LOKI_VIA_GRAFANA: raw.LOKI_VIA_GRAFANA === true,
97
+ LOKI_GRAFANA_DATASOURCE_ID: raw.LOKI_GRAFANA_DATASOURCE_ID !== undefined ? String(raw.LOKI_GRAFANA_DATASOURCE_ID) : "1",
84
98
  };
85
99
  }
86
100
  catch (err) {
@@ -139,7 +153,10 @@ function resolveTimeParam(value) {
139
153
  // executeQuery() returns in mcp-servers/oracle/src/server.ts, for the same reason:
140
154
  // tool results should never surface as a raw MCP protocol error.
141
155
  async function lokiFetch(path, params) {
142
- const url = new URL(path, lokiConfig.LOKI_BASE_URL);
156
+ const effectivePath = lokiConfig.LOKI_VIA_GRAFANA
157
+ ? `/api/datasources/proxy/${lokiConfig.LOKI_GRAFANA_DATASOURCE_ID}${path}`
158
+ : path;
159
+ const url = new URL(effectivePath, lokiConfig.LOKI_BASE_URL);
143
160
  for (const [key, value] of Object.entries(params ?? {})) {
144
161
  if (value !== undefined && value !== null)
145
162
  url.searchParams.set(key, String(value));
package/package.json CHANGED
@@ -1,8 +1,8 @@
1
1
  {
2
2
  "name": "@kealthas-dev/opencode-mcp-loki",
3
- "version": "1.0.9",
3
+ "version": "1.0.11",
4
4
  "type": "module",
5
- "description": "MCP server exposing read-only Loki query/label tools - see README.md for design and the LOKI_CONFIG_FILE-driven config",
5
+ "description": "MCP server exposing read-only Loki query/label tools - see README.md for design and the config.json-driven config",
6
6
  "main": "dist/server.js",
7
7
  "bin": {
8
8
  "opencode-mcp-loki": "dist/server.js"