@kealthas-dev/opencode-mcp-loki 1.0.11 → 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.
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",
@@ -48,12 +48,12 @@ Published as `@kealthas-dev/opencode-mcp-loki` — on a real deployment, install
48
48
 
49
49
  ```bash
50
50
  npm install -g @kealthas-dev/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)
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)
53
53
  LOKI_CONFIG_ENV=prod opencode-mcp-loki
54
54
  ```
55
55
 
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):
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):
57
57
 
58
58
  ```bash
59
59
  npm install
package/dist/server.js CHANGED
@@ -24,12 +24,17 @@ function printSampleConfig(label, path, sample) {
24
24
  console.error(JSON.stringify(sample, null, 2));
25
25
  console.error("");
26
26
  }
27
- // server.json is infrastructure config (which port to bind) that doesn't
28
- // vary per environment, so it lives at one fixed path rather than being
29
- // pointed at like the Loki config below. Missing entirely just means "use
30
- // the default port" - only a present-but-broken file is treated as a real
31
- // 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.
32
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
+ }
33
38
  if (!existsSync(SERVER_CONFIG_PATH)) {
34
39
  return { LOKI_MCP_PORT: DEFAULT_PORT };
35
40
  }
@@ -47,38 +52,12 @@ function loadServerConfig() {
47
52
  process.exit(1);
48
53
  }
49
54
  }
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.
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_-]+$/;
55
+ // config.json by default, config-<name>.json when LOKI_CONFIG_ENV is set.
65
56
  function loadLokiConfig() {
66
57
  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;
58
+ const resolvedPath = join(CONFIG_DIR, envName ? `config-${envName}.json` : "config.json");
72
59
  if (!existsSync(resolvedPath)) {
73
- if (envName) {
74
- console.error(`Loki config file not found: ${resolvedPath}`);
75
- console.error(`(LOKI_CONFIG_ENV=${envName} looks for "${envName}.json" under ${LOKI_CONFIGS_DIR})`);
76
- }
77
- else {
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");
81
- }
60
+ console.error(`Loki config file not found: ${resolvedPath}`);
82
61
  printSampleConfig("Loki config file", resolvedPath, SAMPLE_LOKI_CONFIG);
83
62
  process.exit(1);
84
63
  }
@@ -104,8 +83,6 @@ function loadLokiConfig() {
104
83
  }
105
84
  }
106
85
  const serverConfig = loadServerConfig();
107
- const lokiConfig = loadLokiConfig();
108
- const LOKI_DEFAULT_TZ_OFFSET = lokiConfig.LOKI_DEFAULT_TZ_OFFSET ?? "+08:00";
109
86
  // Computing a correct start/end by hand (an exact RFC3339 offset, or -
110
87
  // worse - a 19-digit nanosecond epoch) is real friction for whatever's
111
88
  // calling this tool, model or human. This resolves three friendlier
@@ -128,7 +105,7 @@ const RELATIVE_TIME_RE = /^now(?:-((?:\d+[smhd])+))?$/;
128
105
  const DURATION_PART_RE = /(\d+)([smhd])/g;
129
106
  const NAIVE_DATETIME_RE = /^(\d{4}-\d{2}-\d{2})[T ](\d{2}:\d{2}:\d{2}(?:\.\d+)?)$/;
130
107
  const UNIT_MS = { s: 1000, m: 60_000, h: 3_600_000, d: 86_400_000 };
131
- function resolveTimeParam(value) {
108
+ function resolveTimeParam(value, tzOffset) {
132
109
  if (value === undefined || value === null)
133
110
  return value;
134
111
  const relative = RELATIVE_TIME_RE.exec(value);
@@ -141,7 +118,7 @@ function resolveTimeParam(value) {
141
118
  }
142
119
  const naive = NAIVE_DATETIME_RE.exec(value);
143
120
  if (naive)
144
- return `${naive[1]}T${naive[2]}${LOKI_DEFAULT_TZ_OFFSET}`;
121
+ return `${naive[1]}T${naive[2]}${tzOffset}`;
145
122
  return value;
146
123
  }
147
124
  // Loki's query API (what every tool below hits) has no write side at all -
@@ -153,6 +130,7 @@ function resolveTimeParam(value) {
153
130
  // executeQuery() returns in mcp-servers/oracle/src/server.ts, for the same reason:
154
131
  // tool results should never surface as a raw MCP protocol error.
155
132
  async function lokiFetch(path, params) {
133
+ const lokiConfig = loadLokiConfig();
156
134
  const effectivePath = lokiConfig.LOKI_VIA_GRAFANA
157
135
  ? `/api/datasources/proxy/${lokiConfig.LOKI_GRAFANA_DATASOURCE_ID}${path}`
158
136
  : path;
@@ -185,30 +163,34 @@ async function lokiFetch(path, params) {
185
163
  }
186
164
  }
187
165
  async function queryRange({ query, start, end, limit, direction, step }) {
166
+ const tzOffset = loadLokiConfig().LOKI_DEFAULT_TZ_OFFSET ?? "+08:00";
188
167
  return lokiFetch("/loki/api/v1/query_range", {
189
168
  query,
190
- start: resolveTimeParam(start),
191
- end: resolveTimeParam(end),
169
+ start: resolveTimeParam(start, tzOffset),
170
+ end: resolveTimeParam(end, tzOffset),
192
171
  limit,
193
172
  direction,
194
173
  step,
195
174
  });
196
175
  }
197
176
  async function listLabels({ start, end }) {
198
- 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) });
199
179
  }
200
180
  async function listLabelValues({ label, start, end }) {
181
+ const tzOffset = loadLokiConfig().LOKI_DEFAULT_TZ_OFFSET ?? "+08:00";
201
182
  return lokiFetch(`/loki/api/v1/label/${encodeURIComponent(label)}/values`, {
202
- start: resolveTimeParam(start),
203
- end: resolveTimeParam(end),
183
+ start: resolveTimeParam(start, tzOffset),
184
+ end: resolveTimeParam(end, tzOffset),
204
185
  });
205
186
  }
206
- const TIME_PARAM_DESCRIPTION = `Accepts, in order of preference: a relative time ("now", "now-1h", "now-30m", "now-1d", ` +
207
- `"now-1h30m" - Grafana's own relative-time syntax for Loki/Prometheus); a local datetime with ` +
208
- `no timezone, e.g. "2026-09-15T10:00:00" or "2026-09-15 10:00:00" (assumed to be ${LOKI_DEFAULT_TZ_OFFSET}); ` +
209
- `or an already-qualified absolute value (RFC3339 with an explicit offset, e.g. "2026-09-15T10:00:00+08:00", ` +
210
- `or a unix epoch in seconds or nanoseconds).`;
211
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).`;
212
194
  const server = new Server({ name: "loki-mcp", version: "1.0.0" }, { capabilities: { tools: {} } });
213
195
  server.setRequestHandler(ListToolsRequestSchema, async () => ({
214
196
  tools: [
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kealthas-dev/opencode-mcp-loki",
3
- "version": "1.0.11",
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",