@kealthas-dev/opencode-mcp-loki 1.0.10 → 1.0.12

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 +21 -7
  2. package/dist/server.js +38 -49
  3. package/package.json +1 -1
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). 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.
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). The config file's *location* is never user-supplied, only a short name is; see that same section for why.
16
16
 
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`):
17
+ - **`$HOME/.config/kealthas-dev/opencode-mcp-loki/server.json`** — the port to listen on. `LOKI_MCP_PORT` env var overrides it, for running more than one instance. Otherwise 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.** 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`):
21
+ - **A Loki config file, re-read on every tool call (no restart needed after editing it).** With no `LOKI_CONFIG_ENV` set, it's read from `$HOME/.config/kealthas-dev/opencode-mcp-loki/config.json`. For multiple environments, set `LOKI_CONFIG_ENV` to a name and it reads `config-<name>.json` instead — e.g. `LOKI_CONFIG_ENV=prod` reads `config-prod.json`. The server prints a sample and exits if the resolved file doesn't exist or `LOKI_BASE_URL` is missing from it. Shape (see `config.example.json`):
22
22
  ```json
23
23
  {
24
24
  "LOKI_BASE_URL": "http://192.168.1.100:3100",
@@ -30,18 +30,30 @@ 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
- mkdir -p ~/.config/kealthas-dev/opencode-mcp-loki/configs
40
- # real config at ~/.config/kealthas-dev/opencode-mcp-loki/configs/prod.json (see config.example.json for the shape)
51
+ mkdir -p ~/.config/kealthas-dev/opencode-mcp-loki
52
+ # real config at ~/.config/kealthas-dev/opencode-mcp-loki/config-prod.json (see config.example.json for the shape)
41
53
  LOKI_CONFIG_ENV=prod opencode-mcp-loki
42
54
  ```
43
55
 
44
- 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):
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 `config-<name>.json` (see `config.example.json` for the shape — the sandbox's docker-entrypoint.sh generates the default one automatically, see Testing below):
45
57
 
46
58
  ```bash
47
59
  npm install
@@ -68,4 +80,6 @@ The default config file is already in place inside that shell — `docker-entryp
68
80
 
69
81
  ## Status
70
82
 
71
- **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
@@ -16,18 +16,25 @@ 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`);
22
24
  console.error(JSON.stringify(sample, null, 2));
23
25
  console.error("");
24
26
  }
25
- // server.json is infrastructure config (which port to bind) that doesn't
26
- // vary per environment, so it lives at one fixed path rather than being
27
- // pointed at like the Loki config below. Missing entirely just means "use
28
- // the default port" - only a present-but-broken file is treated as a real
29
- // error, since its existence signals intent to override the default.
27
+ // LOKI_MCP_PORT env var overrides server.json, for running several
28
+ // instances (different projects/ports) without separate port files.
30
29
  function loadServerConfig() {
30
+ if (process.env.LOKI_MCP_PORT !== undefined) {
31
+ const port = Number(process.env.LOKI_MCP_PORT);
32
+ if (!Number.isInteger(port) || port <= 0) {
33
+ console.error(`LOKI_MCP_PORT must be a positive integer, got: ${JSON.stringify(process.env.LOKI_MCP_PORT)}`);
34
+ process.exit(1);
35
+ }
36
+ return { LOKI_MCP_PORT: port };
37
+ }
31
38
  if (!existsSync(SERVER_CONFIG_PATH)) {
32
39
  return { LOKI_MCP_PORT: DEFAULT_PORT };
33
40
  }
@@ -45,38 +52,12 @@ function loadServerConfig() {
45
52
  process.exit(1);
46
53
  }
47
54
  }
48
- // Loki connection details are per-environment, but the *location* they're
49
- // read from is never user-supplied - only a short env name is (e.g. "prod"),
50
- // which selects a fixed file under CONFIG_DIR/configs/. This avoids the
51
- // class of bug an arbitrary-path env var invites: a caller's shell not
52
- // expanding "~", a quoted value suppressing that expansion, a typo'd
53
- // relative path resolving against whatever cwd happens to be - all of
54
- // which point path.resolve() somewhere unintended, silently. A bare name
55
- // has none of that surface. No env var set falls back to config.json
56
- // directly in CONFIG_DIR (not configs/) for the common single-environment
57
- // case. Only LOKI_BASE_URL is required in the file itself - Loki is
58
- // commonly reachable unauthenticated on an internal LAN, unlike
59
- // mcp-servers/oracle.
60
- const DEFAULT_LOKI_CONFIG_PATH = join(CONFIG_DIR, "config.json");
61
- const LOKI_CONFIGS_DIR = join(CONFIG_DIR, "configs");
62
- const CONFIG_ENV_NAME_RE = /^[a-zA-Z0-9_-]+$/;
55
+ // config.json by default, config-<name>.json when LOKI_CONFIG_ENV is set.
63
56
  function loadLokiConfig() {
64
57
  const envName = process.env.LOKI_CONFIG_ENV;
65
- if (envName !== undefined && !CONFIG_ENV_NAME_RE.test(envName)) {
66
- console.error(`LOKI_CONFIG_ENV must be a plain name (letters, digits, "-", "_"), got: ${JSON.stringify(envName)}`);
67
- process.exit(1);
68
- }
69
- const resolvedPath = envName ? join(LOKI_CONFIGS_DIR, `${envName}.json`) : DEFAULT_LOKI_CONFIG_PATH;
58
+ const resolvedPath = join(CONFIG_DIR, envName ? `config-${envName}.json` : "config.json");
70
59
  if (!existsSync(resolvedPath)) {
71
- if (envName) {
72
- console.error(`Loki config file not found: ${resolvedPath}`);
73
- console.error(`(LOKI_CONFIG_ENV=${envName} looks for "${envName}.json" under ${LOKI_CONFIGS_DIR})`);
74
- }
75
- else {
76
- console.error(`No LOKI_CONFIG_ENV set and no default config file at: ${resolvedPath}`);
77
- console.error(`Either create that file, or set LOKI_CONFIG_ENV to the name of a file under ${LOKI_CONFIGS_DIR}/, e.g.:`);
78
- console.error(" LOKI_CONFIG_ENV=prod opencode-mcp-loki");
79
- }
60
+ console.error(`Loki config file not found: ${resolvedPath}`);
80
61
  printSampleConfig("Loki config file", resolvedPath, SAMPLE_LOKI_CONFIG);
81
62
  process.exit(1);
82
63
  }
@@ -91,6 +72,8 @@ function loadLokiConfig() {
91
72
  LOKI_PASSWORD: raw.LOKI_PASSWORD,
92
73
  LOKI_ORG_ID: raw.LOKI_ORG_ID,
93
74
  LOKI_DEFAULT_TZ_OFFSET: raw.LOKI_DEFAULT_TZ_OFFSET,
75
+ LOKI_VIA_GRAFANA: raw.LOKI_VIA_GRAFANA === true,
76
+ LOKI_GRAFANA_DATASOURCE_ID: raw.LOKI_GRAFANA_DATASOURCE_ID !== undefined ? String(raw.LOKI_GRAFANA_DATASOURCE_ID) : "1",
94
77
  };
95
78
  }
96
79
  catch (err) {
@@ -100,8 +83,6 @@ function loadLokiConfig() {
100
83
  }
101
84
  }
102
85
  const serverConfig = loadServerConfig();
103
- const lokiConfig = loadLokiConfig();
104
- const LOKI_DEFAULT_TZ_OFFSET = lokiConfig.LOKI_DEFAULT_TZ_OFFSET ?? "+08:00";
105
86
  // Computing a correct start/end by hand (an exact RFC3339 offset, or -
106
87
  // worse - a 19-digit nanosecond epoch) is real friction for whatever's
107
88
  // calling this tool, model or human. This resolves three friendlier
@@ -124,7 +105,7 @@ const RELATIVE_TIME_RE = /^now(?:-((?:\d+[smhd])+))?$/;
124
105
  const DURATION_PART_RE = /(\d+)([smhd])/g;
125
106
  const NAIVE_DATETIME_RE = /^(\d{4}-\d{2}-\d{2})[T ](\d{2}:\d{2}:\d{2}(?:\.\d+)?)$/;
126
107
  const UNIT_MS = { s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 };
127
- function resolveTimeParam(value) {
108
+ function resolveTimeParam(value, tzOffset) {
128
109
  if (value === undefined || value === null)
129
110
  return value;
130
111
  const relative = RELATIVE_TIME_RE.exec(value);
@@ -137,7 +118,7 @@ function resolveTimeParam(value) {
137
118
  }
138
119
  const naive = NAIVE_DATETIME_RE.exec(value);
139
120
  if (naive)
140
- return `${naive[1]}T${naive[2]}${LOKI_DEFAULT_TZ_OFFSET}`;
121
+ return `${naive[1]}T${naive[2]}${tzOffset}`;
141
122
  return value;
142
123
  }
143
124
  // Loki's query API (what every tool below hits) has no write side at all -
@@ -149,7 +130,11 @@ function resolveTimeParam(value) {
149
130
  // executeQuery() returns in mcp-servers/oracle/src/server.ts, for the same reason:
150
131
  // tool results should never surface as a raw MCP protocol error.
151
132
  async function lokiFetch(path, params) {
152
- const url = new URL(path, lokiConfig.LOKI_BASE_URL);
133
+ const lokiConfig = loadLokiConfig();
134
+ const effectivePath = lokiConfig.LOKI_VIA_GRAFANA
135
+ ? `/api/datasources/proxy/${lokiConfig.LOKI_GRAFANA_DATASOURCE_ID}${path}`
136
+ : path;
137
+ const url = new URL(effectivePath, lokiConfig.LOKI_BASE_URL);
153
138
  for (const [key, value] of Object.entries(params ?? {})) {
154
139
  if (value !== undefined && value !== null)
155
140
  url.searchParams.set(key, String(value));
@@ -178,30 +163,34 @@ async function lokiFetch(path, params) {
178
163
  }
179
164
  }
180
165
  async function queryRange({ query, start, end, limit, direction, step }) {
166
+ const tzOffset = loadLokiConfig().LOKI_DEFAULT_TZ_OFFSET ?? "+08:00";
181
167
  return lokiFetch("/loki/api/v1/query_range", {
182
168
  query,
183
- start: resolveTimeParam(start),
184
- end: resolveTimeParam(end),
169
+ start: resolveTimeParam(start, tzOffset),
170
+ end: resolveTimeParam(end, tzOffset),
185
171
  limit,
186
172
  direction,
187
173
  step,
188
174
  });
189
175
  }
190
176
  async function listLabels({ start, end }) {
191
- return lokiFetch("/loki/api/v1/labels", { start: resolveTimeParam(start), end: resolveTimeParam(end) });
177
+ const tzOffset = loadLokiConfig().LOKI_DEFAULT_TZ_OFFSET ?? "+08:00";
178
+ return lokiFetch("/loki/api/v1/labels", { start: resolveTimeParam(start, tzOffset), end: resolveTimeParam(end, tzOffset) });
192
179
  }
193
180
  async function listLabelValues({ label, start, end }) {
181
+ const tzOffset = loadLokiConfig().LOKI_DEFAULT_TZ_OFFSET ?? "+08:00";
194
182
  return lokiFetch(`/loki/api/v1/label/${encodeURIComponent(label)}/values`, {
195
- start: resolveTimeParam(start),
196
- end: resolveTimeParam(end),
183
+ start: resolveTimeParam(start, tzOffset),
184
+ end: resolveTimeParam(end, tzOffset),
197
185
  });
198
186
  }
199
- const TIME_PARAM_DESCRIPTION = `Accepts, in order of preference: a relative time ("now", "now-1h", "now-30m", "now-1d", ` +
200
- `"now-1h30m" - Grafana's own relative-time syntax for Loki/Prometheus); a local datetime with ` +
201
- `no timezone, e.g. "2026-09-15T10:00:00" or "2026-09-15 10:00:00" (assumed to be ${LOKI_DEFAULT_TZ_OFFSET}); ` +
202
- `or an already-qualified absolute value (RFC3339 with an explicit offset, e.g. "2026-09-15T10:00:00+08:00", ` +
203
- `or a unix epoch in seconds or nanoseconds).`;
204
187
  function createMcpServer() {
188
+ const tzOffset = loadLokiConfig().LOKI_DEFAULT_TZ_OFFSET ?? "+08:00";
189
+ const TIME_PARAM_DESCRIPTION = `Accepts, in order of preference: a relative time ("now", "now-1h", "now-30m", "now-1d", ` +
190
+ `"now-1h30m" - Grafana's own relative-time syntax for Loki/Prometheus); a local datetime with ` +
191
+ `no timezone, e.g. "2026-09-15T10:00:00" or "2026-09-15 10:00:00" (assumed to be ${tzOffset}); ` +
192
+ `or an already-qualified absolute value (RFC3339 with an explicit offset, e.g. "2026-09-15T10:00:00+08:00", ` +
193
+ `or a unix epoch in seconds or nanoseconds).`;
205
194
  const server = new Server({ name: "loki-mcp", version: "1.0.0" }, { capabilities: { tools: {} } });
206
195
  server.setRequestHandler(ListToolsRequestSchema, async () => ({
207
196
  tools: [
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kealthas-dev/opencode-mcp-loki",
3
- "version": "1.0.10",
3
+ "version": "1.0.12",
4
4
  "type": "module",
5
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",