@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.
- package/README.md +21 -7
- package/dist/server.js +38 -49
- 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).
|
|
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,
|
|
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
|
|
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
|
|
40
|
-
# real config at ~/.config/kealthas-dev/opencode-mcp-loki/
|
|
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
|
|
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
|
-
**
|
|
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
|
-
//
|
|
26
|
-
//
|
|
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
|
-
//
|
|
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
|
-
|
|
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
|
-
|
|
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]}${
|
|
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
|
|
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
|
-
|
|
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.
|
|
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",
|