@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.
- package/README.md +23 -7
- package/dist/server.js +34 -17
- 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)
|
|
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,
|
|
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
|
-
|
|
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),
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
**
|
|
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
|
|
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
|
|
49
|
-
//
|
|
50
|
-
//
|
|
51
|
-
//
|
|
52
|
-
//
|
|
53
|
-
//
|
|
54
|
-
//
|
|
55
|
-
//
|
|
56
|
-
//
|
|
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
|
|
60
|
-
|
|
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 (
|
|
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
|
|
67
|
-
console.error(
|
|
68
|
-
console.error("
|
|
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
|
|
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.
|
|
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
|
|
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"
|