mcp-scalyr-dataset
# mcp-scalyr-dataset
Read-only MCP server for SentinelOne DataSet (formerly Scalyr) log search.
Agents can `search_logs`, `count_logs`, `list_log_facets`, and `power_query` without dumping raw API JSON, auto-paginating, or requiring Config/Write keys.
## Requirements
- Node.js `>= 20`
- A **Log Read Access** token (the only required key / scope — Config Read and Write are never required)
- Operator-set HTTPS region base URL
## Environment (mcp.json `env`)
Put secrets in your agent mcp.json — **do not** create a project `.env` for runtime secrets.
| Variable | Required | Notes |
|----------|----------|-------|
| `DATASET_READ_TOKEN` | yes | Log Read Access Bearer token |
| `DATASET_BASE_URL` | yes | `https://app.scalyr.com` (US) or `https://app.eu.scalyr.com` (EU) |
`.env.example` documents names/placeholders only.
## Tools
| Tool | Job | Annotations (R/D/I/O) |
|------|-----|------------------------|
| `search_logs` | Small page of matching events (fenced pipe table) | T/F/T/T |
| `count_logs` | Volume check (`count:` lines only) | T/F/T/T |
| `list_log_facets` | Top values for one field | T/F/T/T |
| `power_query` | PowerQuery table (requires an allowed `\|` stage) | T/F/T/T |
Recommended workflow: `count_logs` or `list_log_facets` first, then a tight `search_logs` field clause (for example `severity >= 5` or `serverHost contains "api"`). Do not treat a lone `*` as match-all. Use `power_query` with `| group`, `| sort`, `| count(`, `| filter`, `| let`, `| join`, or `| timebucket` — not `| columns` dumps.
Defaults: `start_time=15m`, `end_time=0h`, `priority=low`, `max_count=25` (hard max 50). First-page relative windows are snapshotted to epoch-ms so page 2 can reuse them. `search_logs` prints `more: yes` and `continuation_token` only when the page is full; never auto-followed. `cpu_ms` is milliseconds from DataSet.
## Install / run (local)
```bash
npm ci
npm run build
npm test
npm run test:connections # needs DATASET_* exported in the shell
```
Binary after build: `mcp-scalyr-dataset` → `dist/index.js` (stdio).
## mcp.json snippet (post-qc only)
Only wire this into Cursor after `mcp-maker qc` is not FAIL:
```json
{
"mcpServers": {
"mcp-scalyr-dataset": {
"command": "node",
"args": ["/absolute/path/to/mcp-scalyr-dataset/dist/index.js"],
"env": {
"DATASET_BASE_URL": "https://app.scalyr.com",
"DATASET_READ_TOKEN": "your-log-read-token"
}
}
}
}
```
## Architecture
Hexagonal single package (ADR-001/002):
- `src/tools` — inbound MCP adapters
- `src/clients` — outbound HTTP DataSet adapter
- `src/adapters/outbound/memory` + `src/adapters/inbound/test` — Cockburn pair
- `src/application` / `src/domain` — no MCP SDK or fetch imports
## Security / residual risks
- Log bodies are untrusted: allowlist → truncate → redact → untrusted fence
- Secrets never in tool args, request bodies, stdout, or README examples that are real
- HTTPS-only `DATASET_BASE_URL`; no userinfo; tools cannot override it
- No write/config/generic-HTTP tools
- Residual lethal trifecta: private logs + untrusted text + agent tools — this server must not grow an exfil channel
## Scripts
| Script | Purpose |
|--------|---------|
| `npm run build` | Compile TypeScript to `dist/` |
| `npm test` | Compile tests + run node:test |
| `npm run test:connections` | Live smoke count (shell-exported env) |
| `npm run depcruise` | Hexagonal import boundaries |
TDQS
Scored across 4 tools
The four tools map to reasonably distinct jobs: facet discovery, volume counting, raw event retrieval, and aggregation. There is mild overlap — count_logs and power_query can both produce counts, and power_query can filter the same data search_logs filters — but the descriptions explicitly steer callers (e.g. 'not for dumping raw messages — use search_logs').
Three of four names follow a clean verb_noun pattern (search_logs, count_logs, list_log_facets) with a shared 'logs'/'facet' vocabulary. power_query deviates by naming a product feature rather than an action, but it is still readable and unambiguous.
Four tools is a lean but defensible surface for a log-query server covering discovery, counting, search, and aggregation. It sits slightly on the thin side — there is no schema/field-listing tool to support exploration — but no tool feels redundant.
Search, count, facet discovery, and aggregation with a continuation_token cover the core query workflow. However, list_log_facets requires already knowing a field name, and there is no way to enumerate fields/datasets or to fetch a specific event or surrounding context, which will cause dead ends for an agent exploring an unfamiliar dataset.