mcp-elk 1.0.0__tar.gz

mcp_elk-1.0.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/
+dist/
+.DS_Store
+uv.lock

mcp_elk-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Xavier Araújo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_elk-1.0.0/PKG-INFO

@@ -0,0 +1,100 @@
+Metadata-Version: 2.5
+Name: mcp-elk
+Version: 1.0.0
+Summary: MCP server de leitura para Elasticsearch/Kibana (ELK): busca, contagem, consultas salvas e exportação CSV
+Project-URL: Repository, https://github.com/dxaraujo/mcp-elk
+Author-email: Daniel Xavier Araújo <danielxaraujo@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: mcp[cli]>=2.2
+Requires-Dist: requests>=2.31
+Description-Content-Type: text/markdown
+
+# mcp-elk
+
+Servidor MCP **de leitura** para o ELK (Elasticsearch + Kibana): busca, contagem com agrupamento, consultas prontas do
+Kibana e exportação CSV. É **agnóstico**: índice, campos (ex.: sistema, categoria) e consultas do projeto chegam como
+parâmetro.
+
+## Credenciais e servidores
+
+| SO | Arquivo |
+|---|---|
+| Linux/Mac | `~/.config/mcp-elk/elk.properties` |
+| Windows | `%APPDATA%\mcp-elk\elk.properties` |
+
+Para usar outro caminho, defina a variável de ambiente `MCP_ELK_CONFIG`.
+
+```ini
+[DEFAULT]
+user = SEU_USUARIO
+password = SUA_SENHA
+prod = https://logs.SEU-SERVIDOR
+homol = https://hlogs.SEU-SERVIDOR
+dev = https://dlogs.SEU-SERVIDOR
+```
+
+`prod`, `homol` e `dev` são as URLs do **Kibana**; só `prod` é obrigatória. Opcionalmente, `es_prod`, `es_homol` e
+`es_dev` são as URLs do **Elasticsearch** direto: quando presentes, o MCP usa as APIs REST oficiais (`_search`,
+`_field_caps`, PIT). Sem elas, a busca passa pelo Kibana em `POST /internal/search/es`, uma API **interna** do Kibana e
+o primeiro ponto a revalidar num upgrade.
+
+**Certificados:** o MCP confia nas CAs instaladas na máquina (no Windows, as do repositório do Windows) e, se existir,
+em `elk-bundle.pem`, na mesma pasta do `elk.properties`: a cadeia PEM do Kibana, quando a CA
+não estiver instalada. `REQUESTS_CA_BUNDLE` também funciona. Se o certificado não for aceito, a tool devolve uma mensagem
+dizendo onde gravar a cadeia. A sessão aceita as cifras padrão do OpenSSL, porque alguns Kibana só oferecem
+`AES256-SHA256`, que a lista do Python exclui.
+
+## Instalação
+
+Publicado no [PyPI](https://pypi.org/project/mcp-elk/); requer o [uv](https://docs.astral.sh/uv/) (`uvx` no PATH).
+No cliente MCP (`mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "elk": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["mcp-elk@latest"],
+      "env": { "UV_SYSTEM_CERTS": "true" }
+    }
+  }
+}
+```
+
+`UV_SYSTEM_CERTS` faz o `uvx` usar as CAs da máquina para baixar o pacote (proxy corporativo).
+
+Desenvolvimento:
+
+```bash
+uv sync
+uv run pytest
+uv run mcp dev mcp_elk/server.py   # MCP Inspector
+```
+
+## Tools (só leitura)
+
+Parâmetros comuns:
+- `ambiente`: prod/produção (padrão), homol/homologação/hml ou dev/desenvolvimento;
+- `inicio`/`fim`: `now-15m` ou ISO 8601. `inicio` é obrigatório;
+- `campo_tempo`: padrão `@timestamp`.
+
+| Tool | Para quê |
+|---|---|
+| `elk_buscar_logs(indice, inicio, consulta?, campos?, filtros?, limite≤100, retornar?)` | Investigar: itens achatados (`{"a.b": v}`), textos cortados em 2000 caracteres |
+| `elk_contar(..., agrupar_por?, top=10)` | Dimensionar; os valores mais frequentes de um campo |
+| `elk_exportar_csv(..., arquivo, retornar?, max_linhas=100000)` | Volume grande: pagina e grava o CSV em disco, sem passar documentos pela conversa |
+| `elk_listar_consultas(busca?, espaco?, limite=50)` | Buscas salvas do Discover e saved queries do Kibana (todos os spaces, ou só `espaco`), com `consulta`, `filtros` (DSL) e `indice` prontos para reuso |
+| `elk_listar_indices(busca?, espaco?)` | Data views (padrão de índice e campo de tempo) |
+| `elk_listar_campos(indice, busca?)` | Campos, tipo e se são agregáveis |
+
+- `consulta` é **Lucene** (`query_string`): `campo:valor AND msg:*timeout*`. O KQL do Kibana é convertido no navegador
+  e o ES 8.15 não o entende. Por isso o MCP passa `and`/`or`/`not` para maiúsculas fora de aspas: sem isso, `a: x and b: y`
+  virava OR e trazia centenas de vezes mais documentos. `campo:{...}` aninhado continua sem suporte.
+- `campos` = filtros exatos `{campo: valor}` (`term`); `filtros` = Query DSL crua.
+- Exportação: com ES direto, usa PIT + `search_after` (consistente). Só com o Kibana, usa `search_after` por
+  `campo_tempo` e descarta os `_id` repetidos na virada da página. Com documentos demais no mesmo timestamp, dá
+  erro e pede `es_<ambiente>`. A página cresce para acomodar os documentos repetidos, e o erro só aparece quando passa de
+  10.000 documentos no mesmo timestamp.

mcp_elk-1.0.0/README.md

@@ -0,0 +1,87 @@
+# mcp-elk
+
+Servidor MCP **de leitura** para o ELK (Elasticsearch + Kibana): busca, contagem com agrupamento, consultas prontas do
+Kibana e exportação CSV. É **agnóstico**: índice, campos (ex.: sistema, categoria) e consultas do projeto chegam como
+parâmetro.
+
+## Credenciais e servidores
+
+| SO | Arquivo |
+|---|---|
+| Linux/Mac | `~/.config/mcp-elk/elk.properties` |
+| Windows | `%APPDATA%\mcp-elk\elk.properties` |
+
+Para usar outro caminho, defina a variável de ambiente `MCP_ELK_CONFIG`.
+
+```ini
+[DEFAULT]
+user = SEU_USUARIO
+password = SUA_SENHA
+prod = https://logs.SEU-SERVIDOR
+homol = https://hlogs.SEU-SERVIDOR
+dev = https://dlogs.SEU-SERVIDOR
+```
+
+`prod`, `homol` e `dev` são as URLs do **Kibana**; só `prod` é obrigatória. Opcionalmente, `es_prod`, `es_homol` e
+`es_dev` são as URLs do **Elasticsearch** direto: quando presentes, o MCP usa as APIs REST oficiais (`_search`,
+`_field_caps`, PIT). Sem elas, a busca passa pelo Kibana em `POST /internal/search/es`, uma API **interna** do Kibana e
+o primeiro ponto a revalidar num upgrade.
+
+**Certificados:** o MCP confia nas CAs instaladas na máquina (no Windows, as do repositório do Windows) e, se existir,
+em `elk-bundle.pem`, na mesma pasta do `elk.properties`: a cadeia PEM do Kibana, quando a CA
+não estiver instalada. `REQUESTS_CA_BUNDLE` também funciona. Se o certificado não for aceito, a tool devolve uma mensagem
+dizendo onde gravar a cadeia. A sessão aceita as cifras padrão do OpenSSL, porque alguns Kibana só oferecem
+`AES256-SHA256`, que a lista do Python exclui.
+
+## Instalação
+
+Publicado no [PyPI](https://pypi.org/project/mcp-elk/); requer o [uv](https://docs.astral.sh/uv/) (`uvx` no PATH).
+No cliente MCP (`mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "elk": {
+      "type": "stdio",
+      "command": "uvx",
+      "args": ["mcp-elk@latest"],
+      "env": { "UV_SYSTEM_CERTS": "true" }
+    }
+  }
+}
+```
+
+`UV_SYSTEM_CERTS` faz o `uvx` usar as CAs da máquina para baixar o pacote (proxy corporativo).
+
+Desenvolvimento:
+
+```bash
+uv sync
+uv run pytest
+uv run mcp dev mcp_elk/server.py   # MCP Inspector
+```
+
+## Tools (só leitura)
+
+Parâmetros comuns:
+- `ambiente`: prod/produção (padrão), homol/homologação/hml ou dev/desenvolvimento;
+- `inicio`/`fim`: `now-15m` ou ISO 8601. `inicio` é obrigatório;
+- `campo_tempo`: padrão `@timestamp`.
+
+| Tool | Para quê |
+|---|---|
+| `elk_buscar_logs(indice, inicio, consulta?, campos?, filtros?, limite≤100, retornar?)` | Investigar: itens achatados (`{"a.b": v}`), textos cortados em 2000 caracteres |
+| `elk_contar(..., agrupar_por?, top=10)` | Dimensionar; os valores mais frequentes de um campo |
+| `elk_exportar_csv(..., arquivo, retornar?, max_linhas=100000)` | Volume grande: pagina e grava o CSV em disco, sem passar documentos pela conversa |
+| `elk_listar_consultas(busca?, espaco?, limite=50)` | Buscas salvas do Discover e saved queries do Kibana (todos os spaces, ou só `espaco`), com `consulta`, `filtros` (DSL) e `indice` prontos para reuso |
+| `elk_listar_indices(busca?, espaco?)` | Data views (padrão de índice e campo de tempo) |
+| `elk_listar_campos(indice, busca?)` | Campos, tipo e se são agregáveis |
+
+- `consulta` é **Lucene** (`query_string`): `campo:valor AND msg:*timeout*`. O KQL do Kibana é convertido no navegador
+  e o ES 8.15 não o entende. Por isso o MCP passa `and`/`or`/`not` para maiúsculas fora de aspas: sem isso, `a: x and b: y`
+  virava OR e trazia centenas de vezes mais documentos. `campo:{...}` aninhado continua sem suporte.
+- `campos` = filtros exatos `{campo: valor}` (`term`); `filtros` = Query DSL crua.
+- Exportação: com ES direto, usa PIT + `search_after` (consistente). Só com o Kibana, usa `search_after` por
+  `campo_tempo` e descarta os `_id` repetidos na virada da página. Com documentos demais no mesmo timestamp, dá
+  erro e pede `es_<ambiente>`. A página cresce para acomodar os documentos repetidos, e o erro só aparece quando passa de
+  10.000 documentos no mesmo timestamp.

mcp_elk-1.0.0/mcp_elk/config.py

@@ -0,0 +1,52 @@
+"""Carrega credenciais e servidores do ELK a partir de elk.properties."""
+from __future__ import annotations
+
+import configparser
+import os
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+
+REQUIRED = ("user", "password", "prod")
+AMBIENTES = ("prod", "homol", "dev")
+TEMPLATE = (
+    "[DEFAULT]\nuser = SEU_USUARIO\npassword = SUA_SENHA\n"
+    "prod = https://logs.SEU-SERVIDOR\nhomol = https://hlogs.SEU-SERVIDOR\ndev = https://dlogs.SEU-SERVIDOR"
+)
+
+
+@dataclass(frozen=True)
+class ElkConfig:
+    user: str
+    password: str = field(repr=False)
+    kibana: dict = field(default_factory=dict)  # {ambiente: url do Kibana}
+    es: dict = field(default_factory=dict)  # {ambiente: url do Elasticsearch}, opcional (es_<ambiente>)
+
+
+def default_path() -> Path:
+    if env := os.environ.get("MCP_ELK_CONFIG"):
+        return Path(env)
+    if sys.platform == "win32":
+        return Path(os.environ["APPDATA"]) / "mcp-elk" / "elk.properties"
+    return Path.home() / ".config" / "mcp-elk" / "elk.properties"
+
+
+def load_config(path: Path | None = None) -> ElkConfig:
+    path = path or default_path()
+    if not path.is_file():
+        raise FileNotFoundError(f"Arquivo de credenciais não encontrado: {path}\nCrie-o com:\n{TEMPLATE}")
+    # interpolation=None: senhas podem conter '%'
+    parser = configparser.ConfigParser(interpolation=None)
+    try:
+        parser.read(path, encoding="utf-8")
+    except configparser.Error as exc:  # ex.: chave repetida
+        raise ValueError(f"{path} inválido: {exc}") from exc
+    section = parser.defaults()
+    missing = [k for k in REQUIRED if not section.get(k, "").strip()]
+    if missing:
+        raise ValueError(f"Chave(s) ausente(s) em {path} [DEFAULT]: {', '.join(missing)}")
+
+    def urls(prefix: str) -> dict:
+        return {a: v.strip().rstrip("/") for a in AMBIENTES if (v := section.get(prefix + a, "")).strip()}
+
+    return ElkConfig(user=section["user"].strip(), password=section["password"], kibana=urls(""), es=urls("es_"))

mcp_elk-1.0.0/mcp_elk/server.py

@@ -0,0 +1,441 @@
+"""Servidor MCP de leitura para ELK (Elasticsearch + Kibana), agnóstico de índice e campos.
+
+Índice, campos e consultas chegam como parâmetro; o elk.properties só tem credenciais e servidores.
+
+Transporte: Elasticsearch direto quando `es_<ambiente>` está configurado (APIs REST oficiais); senão o Kibana
+via POST /internal/search/es (API interna do Kibana, mesmo corpo Query DSL; é o primeiro lugar a revalidar num upgrade).
+"""
+from __future__ import annotations
+
+import csv
+import functools
+import json
+import re
+import threading
+import unicodedata
+from pathlib import Path
+
+import requests
+import ssl
+from requests.adapters import HTTPAdapter
+from mcp.server.mcpserver import MCPServer
+from mcp.server.mcpserver.exceptions import ToolError
+
+from .config import ElkConfig, default_path, load_config
+
+mcp = MCPServer(
+    "elk",
+    instructions=(
+        "Leitura de logs no ELK (Elasticsearch/Kibana). Toda consulta exige `indice` e `inicio` (janela de tempo: "
+        "'now-15m' ou ISO 8601). `ambiente` aceita prod/produção, homol/homologação ou dev/desenvolvimento; sem ele, "
+        "produção. Descubra índices com elk_listar_indices, campos com elk_listar_campos e consultas prontas do Kibana "
+        "com elk_listar_consultas. Dimensione com elk_contar antes de buscar; volume grande vai para "
+        "elk_exportar_csv (grava em disco, nada passa pela conversa)."
+    ),
+)
+
+EXPECTED = (RuntimeError, OSError, LookupError, ValueError)
+TIMEOUT = 120
+LIMITE_TETO = 100
+PAGINA = 1000
+MAX_RESULT_WINDOW = 10_000  # index.max_result_window padrão do ES
+TEXTO_MAX = 2000
+ALIASES = {
+    "prod": "prod", "producao": "prod", "p": "prod",
+    "homol": "homol", "homologacao": "homol", "hml": "homol", "h": "homol",
+    "dev": "dev", "desenvolvimento": "dev", "desenv": "dev", "d": "dev",
+}
+
+
+def tool(fn):
+    """Registra `fn` como tool (ToolError com o texto da exceção) e devolve `fn` intacta."""
+    @functools.wraps(fn)
+    def wrapper(*args, **kwargs):
+        try:
+            return fn(*args, **kwargs)
+        except EXPECTED as exc:
+            raise ToolError(str(exc)) from exc
+
+    mcp.tool()(wrapper)
+    return fn
+
+
+# ---------------------------------------------------------------- HTTP
+
+class ElkHttpError(RuntimeError):
+    def __init__(self, resp: requests.Response):
+        super().__init__(f"HTTP {resp.status_code} em {resp.request.method} {resp.url}: {resp.text[:500].strip()}")
+        self.status_code = resp.status_code
+
+
+def ca_bundle() -> Path:
+    """CAs extras (ex.: cadeia interna do Kibana), ao lado do elk.properties."""
+    return default_path().parent / "elk-bundle.pem"
+
+
+class _TlsAdapter(HTTPAdapter):
+    """CAs do sistema (no Windows, o repositório do Windows) + elk-bundle.pem, se existir.
+    Cifras padrão do OpenSSL: a lista do Python/urllib3 exclui AES256-SHA256 (RSA estático), única oferecida por
+    alguns Kibana internos (handshake failure)."""
+
+    def init_poolmanager(self, *args, **kwargs):
+        ctx = ssl.create_default_context()
+        if ca_bundle().is_file():
+            ctx.load_verify_locations(ca_bundle())
+        ctx.set_ciphers("DEFAULT")
+        super().init_poolmanager(*args, ssl_context=ctx, **kwargs)
+
+
+class ElkSession:
+    def __init__(self, cfg: ElkConfig):
+        self.cfg = cfg
+        self.session = requests.Session()
+        self.session.mount("https://", _TlsAdapter())
+        self.session.auth = (cfg.user, cfg.password)
+        self.session.headers.update({"kbn-xsrf": "true", "Accept": "application/json"})
+
+    def request(self, method: str, url: str, **kwargs) -> dict:
+        try:
+            resp = self.session.request(method, url, timeout=TIMEOUT, **kwargs)
+        except requests.exceptions.SSLError as exc:
+            raise RuntimeError(
+                f"Certificado do servidor não confiável em {url}. Instale a CA na máquina ou grave a cadeia de "
+                f"certificados (PEM) em {ca_bundle()} (ou aponte REQUESTS_CA_BUNDLE para ela) e reinicie o MCP. "
+                f"Detalhe: {exc}") from exc
+        if not resp.ok:
+            raise ElkHttpError(resp)
+        try:
+            return resp.json() if resp.content else {}
+        except ValueError as exc:
+            raise ValueError(f"Resposta não é JSON em {method} {url}: {resp.text[:300]}") from exc
+
+
+_instance: ElkSession | None = None
+_lock = threading.Lock()
+
+
+def get_session() -> ElkSession:
+    """Sessão única por processo; carrega o elk.properties na primeira chamada."""
+    global _instance
+    with _lock:
+        if _instance is None:
+            _instance = ElkSession(load_config())
+        return _instance
+
+
+def set_session(session: ElkSession | None) -> None:
+    """Substitui a sessão global (testes)."""
+    global _instance
+    _instance = session
+
+
+def _ambiente(ambiente: str | None) -> str:
+    if not ambiente:
+        return "prod"
+    sem_acento = unicodedata.normalize("NFKD", ambiente.strip().lower()).encode("ascii", "ignore").decode()
+    if sem_acento not in ALIASES:
+        raise ValueError(f"Ambiente desconhecido: '{ambiente}'. Use prod/produção (padrão), homol/homologação ou "
+                         "dev/desenvolvimento.")
+    return ALIASES[sem_acento]
+
+
+def _kibana(amb: str) -> str:
+    url = get_session().cfg.kibana.get(amb)
+    if not url:
+        raise ValueError(f"Ambiente '{amb}' sem URL no elk.properties: adicione '{amb} = https://...'.")
+    return url
+
+
+def _es(amb: str) -> str | None:
+    return get_session().cfg.es.get(amb)
+
+
+def _search(amb: str, indice: str | None, body: dict) -> dict:
+    """POST _search pelo ES direto ou pelo Kibana. `indice=None` só com PIT (ES direto)."""
+    s = get_session()
+    if es := _es(amb):
+        return s.request("POST", f"{es}/{indice}/_search" if indice else f"{es}/_search", json=body)
+    resp = s.request("POST", f"{_kibana(amb)}/internal/search/es", json={"params": {"index": indice, "body": body}})
+    return resp.get("rawResponse", resp)
+
+
+def _espacos(amb: str, espaco: str | None) -> list[str]:
+    """`espaco` informado, ou todos os spaces do Kibana visíveis ao usuário."""
+    if espaco:
+        return [espaco]
+    return [sp["id"] for sp in get_session().request("GET", f"{_kibana(amb)}/api/spaces/space")]
+
+
+def _saved_objects(amb: str, espaco: str, tipos: list[str], busca: str | None) -> list[dict]:
+    params = {"type": tipos, "per_page": 10000}
+    if busca:
+        params |= {"search": f"{busca}*", "search_fields": "title"}
+    base = _kibana(amb) if espaco == "default" else f"{_kibana(amb)}/s/{espaco}"
+    return get_session().request("GET", f"{base}/api/saved_objects/_find", params=params)["saved_objects"]
+
+
+# ---------------------------------------------------------------- consulta
+
+_OPERADOR = re.compile(r'("(?:[^"\\]|\\.)*")|\b(and|or|not)\b', re.IGNORECASE)
+
+
+def _lucene(consulta: str) -> str:
+    """Operadores em maiúsculas fora de aspas: no KQL `and` é operador, no Lucene vira termo (e o resultado explode)."""
+    return _OPERADOR.sub(lambda m: m.group(1) or m.group(2).upper(), consulta)
+
+
+def _query(inicio: str, fim: str, consulta: str | None, campos: dict | None, filtros: list | None,
+           campo_tempo: str) -> dict:
+    if not (consulta or campos or filtros):
+        raise ValueError("Consulta vazia: informe `consulta`, `campos` ou `filtros`.")
+    must = [{"query_string": {"query": _lucene(consulta)}}] if consulta else []
+    filtro = [{"term": {campo: valor}} for campo, valor in (campos or {}).items()]
+    filtro += list(filtros or [])
+    filtro.append({"range": {campo_tempo: {"gte": inicio, "lte": fim}}})
+    return {"bool": {"must": must, "filter": filtro}}
+
+
+def _total(resp: dict) -> int | None:
+    total = resp.get("hits", {}).get("total")
+    return total.get("value") if isinstance(total, dict) else total
+
+
+def _flat(src: dict, prefix: str = "") -> dict:
+    """{'a': {'b': 1}} -> {'a.b': 1}; listas ficam como estão."""
+    out = {}
+    for k, v in src.items():
+        if isinstance(v, dict):
+            out |= _flat(v, f"{prefix}{k}.")
+        else:
+            out[f"{prefix}{k}"] = v
+    return out
+
+
+def _cut(v):
+    return v[:TEXTO_MAX] + "…" if isinstance(v, str) and len(v) > TEXTO_MAX else v
+
+
+def _janela(amb, indice, inicio, fim) -> dict:
+    return {"ambiente": amb, "indice": indice, "janela": {"inicio": inicio, "fim": fim}}
+
+
+# ---------------------------------------------------------------- tools
+
+@tool
+def elk_buscar_logs(indice: str, inicio: str, consulta: str | None = None, campos: dict[str, str] | None = None,
+                    filtros: list[dict] | None = None, fim: str = "now", limite: int = 20, mais_recentes: bool = True,
+                    retornar: list[str] | None = None, campo_tempo: str = "@timestamp",
+                    ambiente: str | None = None) -> dict:
+    """Busca documentos (só leitura). `consulta` é Lucene (query_string): `campo:valor AND msg:*timeout*`
+    (and/or/not viram maiúsculas fora de aspas, então KQL simples funciona; `campo:{...}` aninhado não).
+    `campos` = filtros exatos {campo: valor} (term); `filtros` = Query DSL
+    crua (como vem de elk_listar_consultas). `inicio`/`fim`: 'now-15m', 'now-1d' ou ISO 8601.
+    `limite` ≤ 100; `retornar` limita os campos de cada item. Itens achatados ({'a.b': v}), textos cortados em 2000.
+    Para muitos documentos use elk_exportar_csv."""
+    if not 1 <= limite <= LIMITE_TETO:
+        raise ValueError(f"`limite` deve estar entre 1 e {LIMITE_TETO}; para mais, use elk_exportar_csv.")
+    amb = _ambiente(ambiente)
+    body = {
+        "size": limite,
+        "track_total_hits": True,
+        "sort": [{campo_tempo: {"order": "desc" if mais_recentes else "asc"}}],
+        "query": _query(inicio, fim, consulta, campos, filtros, campo_tempo),
+    }
+    if retornar:
+        body["_source"] = retornar
+    resp = _search(amb, indice, body)
+    itens = [{"_id": h["_id"], "_index": h["_index"], **{k: _cut(v) for k, v in _flat(h.get("_source", {})).items()}}
+             for h in resp.get("hits", {}).get("hits", [])]
+    return {**_janela(amb, indice, inicio, fim), "total": _total(resp), "retornados": len(itens), "itens": itens}
+
+
+@tool
+def elk_contar(indice: str, inicio: str, consulta: str | None = None, campos: dict[str, str] | None = None,
+               filtros: list[dict] | None = None, fim: str = "now", agrupar_por: str | None = None, top: int = 10,
+               campo_tempo: str = "@timestamp", ambiente: str | None = None) -> dict:
+    """Conta documentos sem trazê-los (só leitura). Mesmos filtros de elk_buscar_logs. `agrupar_por` (campo
+    agregável, ex.: keyword) devolve os `top` valores mais frequentes: use para dimensionar um problema ou para
+    conhecer os valores reais de um campo."""
+    amb = _ambiente(ambiente)
+    body = {"size": 0, "track_total_hits": True, "query": _query(inicio, fim, consulta, campos, filtros, campo_tempo)}
+    if agrupar_por:
+        body["aggs"] = {"grupos": {"terms": {"field": agrupar_por, "size": top}}}
+    resp = _search(amb, indice, body)
+    out = {**_janela(amb, indice, inicio, fim), "total": _total(resp)}
+    if agrupar_por:
+        out["grupos"] = [{"valor": b["key"], "total": b["doc_count"]}
+                         for b in resp.get("aggregations", {}).get("grupos", {}).get("buckets", [])]
+    return out
+
+
+def _filtros_kibana(filters: list[dict]) -> list[dict]:
+    """Filtros do Kibana ({meta, query, $state}) -> Query DSL; ignora os desativados e aplica `negate`."""
+    out = []
+    for f in filters or []:
+        meta = f.get("meta", {})
+        if meta.get("disabled"):
+            continue
+        dsl = f.get("query") or {k: v for k, v in f.items() if k not in ("meta", "$state")}
+        out.append({"bool": {"must_not": [dsl]}} if meta.get("negate") else dsl)
+    return out
+
+
+@tool
+def elk_listar_consultas(busca: str | None = None, espaco: str | None = None, limite: int = 50,
+                         ambiente: str | None = None) -> dict:
+    """Consultas prontas do Kibana: buscas salvas do Discover (tipo `search`) e saved queries (`query`).
+    `busca` filtra pelo início das palavras do título; `espaco` = space do Kibana (sem ele, todos).
+    Devolve {total, itens[:limite]}; total > limite → refine a `busca`. Cada item traz `consulta`, `filtros`
+    (Query DSL) e `indice` (padrão do data view, só em `search`), prontos para elk_buscar_logs/elk_contar/
+    elk_exportar_csv. Se `linguagem` = kuery, a consulta é KQL e vai como Lucene (operadores normalizados; `campo:{...}` não funciona)."""
+    amb = _ambiente(ambiente)
+    objetos, views = [], {}
+    for sp in _espacos(amb, espaco):
+        achados = [o | {"espaco": sp} for o in _saved_objects(amb, sp, ["search", "query"], busca)]
+        if any(o["type"] == "search" for o in achados[:limite]):
+            views |= {o["id"]: o["attributes"] for o in _saved_objects(amb, sp, ["index-pattern"], None)}
+        objetos += achados
+    out = []
+    for o in objetos[:limite]:
+        attrs, indice = o["attributes"], None
+        if o["type"] == "search":
+            src = json.loads(attrs.get("kibanaSavedObjectMeta", {}).get("searchSourceJSON") or "{}")
+            query, filters = src.get("query", {}), src.get("filter", [])
+            ref = next((r["id"] for r in o.get("references", []) if r.get("type") == "index-pattern"), None)
+            indice = views.get(ref, {}).get("title")
+        else:
+            query, filters = attrs.get("query", {}), attrs.get("filters", [])
+        out.append({
+            "id": o["id"], "espaco": o["espaco"], "tipo": o["type"], "titulo": attrs.get("title"), "descricao": attrs.get("description") or None,
+            "consulta": query.get("query") or None, "linguagem": query.get("language"),
+            "filtros": _filtros_kibana(filters), "indice": indice, "colunas": attrs.get("columns"),
+        })
+    return {"total": len(objetos), "itens": out}
+
+
+@tool
+def elk_listar_indices(busca: str | None = None, espaco: str | None = None, ambiente: str | None = None) -> list[dict]:
+    """Data views do Kibana: [{espaco, nome, padrao (use como `indice`), campo_tempo}], sem repetir padrão no mesmo
+    space. `busca` filtra pelo início das palavras do título; `espaco` = space do Kibana (sem ele, todos)."""
+    amb = _ambiente(ambiente)
+    out = {}
+    for sp in _espacos(amb, espaco):
+        for o in _saved_objects(amb, sp, ["index-pattern"], busca):
+            a = o["attributes"]
+            out[(sp, a["title"])] = {"espaco": sp, "nome": a.get("name") or a["title"], "padrao": a["title"],
+                                     "campo_tempo": a.get("timeFieldName")}
+    return sorted(out.values(), key=lambda d: (d["espaco"], d["padrao"]))
+
+
+@tool
+def elk_listar_campos(indice: str, busca: str | None = None, ambiente: str | None = None) -> list[dict]:
+    """Campos do índice: [{campo, tipo, agregavel}]. `busca` filtra por trecho do nome. `agregavel` = serve para
+    `agrupar_por` e `campos` (filtro exato)."""
+    amb = _ambiente(ambiente)
+    s = get_session()
+    if es := _es(amb):
+        caps = s.request("GET", f"{es}/{indice}/_field_caps", params={"fields": "*"})["fields"]
+        campos = [{"campo": nome, "tipo": "|".join(tipos), "agregavel": any(t.get("aggregatable") for t in tipos.values())}
+                  for nome, tipos in caps.items()]
+    else:
+        # API interna do Kibana 8.x (a pública /api/index_patterns/... responde 404)
+        resp = s.request("GET", f"{_kibana(amb)}/internal/data_views/_fields_for_wildcard",
+                         params={"pattern": indice}, headers={"elastic-api-version": "1"})
+        campos = [{"campo": f["name"], "tipo": "|".join(f.get("esTypes") or [f.get("type")]),
+                   "agregavel": bool(f.get("aggregatable"))} for f in resp["fields"]]
+    return sorted((c for c in campos if not c["campo"].startswith("_") and (not busca or busca in c["campo"])),
+                  key=lambda c: c["campo"])
+
+
+def _cell(v):
+    return json.dumps(v, ensure_ascii=False) if isinstance(v, (list, dict)) else v
+
+
+@tool
+def elk_exportar_csv(indice: str, inicio: str, arquivo: str, consulta: str | None = None,
+                     campos: dict[str, str] | None = None, filtros: list[dict] | None = None, fim: str = "now",
+                     retornar: list[str] | None = None, max_linhas: int = 100_000, campo_tempo: str = "@timestamp",
+                     ambiente: str | None = None) -> dict:
+    """Exporta para CSV todos os documentos da consulta, do mais antigo ao mais novo, sem passar pela conversa.
+    Mesmos filtros de elk_buscar_logs. `arquivo` = caminho absoluto (pastas criadas, arquivo sobrescrito; UTF-8
+    com BOM). Colunas = `retornar` ou os campos achatados da primeira página. Para em `max_linhas` (`truncado`).
+    Devolve só o resumo: {arquivo, linhas, total, truncado, colunas}."""
+    path = Path(arquivo)
+    if not path.is_absolute():
+        raise ValueError(f"`arquivo` deve ser um caminho absoluto: {arquivo}")
+    amb = _ambiente(ambiente)
+    s = get_session()
+    body = {"size": PAGINA, "track_total_hits": True,
+            "query": _query(inicio, fim, consulta, campos, filtros, campo_tempo)}
+    if retornar:
+        body["_source"] = retornar
+    es = _es(amb)
+    pit = None
+    if es:  # PIT + _shard_doc: paginação oficial, sem perda nem duplicata
+        pit = s.request("POST", f"{es}/{indice}/_pit", params={"keep_alive": "2m"})["id"]
+        body["sort"] = [{campo_tempo: "asc"}, {"_shard_doc": "asc"}]
+    else:
+        body["sort"] = [{campo_tempo: "asc"}]
+
+    path.parent.mkdir(parents=True, exist_ok=True)
+    linhas, total, colunas, truncado = 0, None, list(retornar or []), False
+    borda, vistos = None, set()  # sem PIT: _ids já gravados no último timestamp
+    try:
+        with path.open("w", newline="", encoding="utf-8-sig") as f:
+            writer = csv.DictWriter(f, colunas, extrasaction="ignore") if colunas else None
+            if writer:
+                writer.writeheader()
+            while not truncado:
+                if pit:
+                    body["pit"] = {"id": pit, "keep_alive": "2m"}
+                resp = _search(amb, None if pit else indice, body)
+                pit = resp.get("pit_id", pit)
+                if total is None:
+                    total = _total(resp)
+                    body["track_total_hits"] = False
+                hits = resp.get("hits", {}).get("hits", [])
+                novos = [h for h in hits if h["_id"] not in vistos]
+                for h in novos:
+                    row = _flat(h.get("_source", {}))
+                    if writer is None:
+                        colunas = list(row)
+                        writer = csv.DictWriter(f, colunas, extrasaction="ignore")
+                        writer.writeheader()
+                    writer.writerow({k: _cell(v) for k, v in row.items()})
+                    linhas += 1
+                    if linhas >= max_linhas:
+                        truncado = linhas < (total or 0)
+                        break
+                if len(hits) < body["size"] or linhas >= max_linhas:
+                    break
+                ultimo = hits[-1]["sort"]
+                if pit:
+                    body["search_after"] = ultimo
+                    continue
+                # sem PIT: recomeça em ts >= último ts e descarta os _ids já gravados nesse ts;
+                # a página cresce com os vistos para sempre trazer documentos novos
+                if ultimo[0] != borda:
+                    borda, vistos = ultimo[0], set()
+                vistos |= {h["_id"] for h in hits if h["sort"][0] == borda}
+                body["search_after"] = [borda - 1]
+                body["size"] = PAGINA + len(vistos)
+                if body["size"] > MAX_RESULT_WINDOW:
+                    raise RuntimeError(f"Documentos demais com o mesmo {campo_tempo} ({borda}): configure "
+                                       "es_<ambiente> (ES direto, com PIT) para exportar esta consulta.")
+    except EXPECTED as exc:
+        raise RuntimeError(f"Exportação interrompida após {linhas} linha(s) gravadas em {path}: {exc}") from exc
+    finally:
+        if pit and es:
+            try:
+                s.request("DELETE", f"{es}/_pit", json={"id": pit})
+            except EXPECTED:
+                pass  # o PIT expira sozinho em 2m
+    return {"arquivo": str(path), "linhas": linhas, "total": total, "truncado": truncado, "colunas": colunas}
+
+
+def main() -> None:
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

mcp_elk-1.0.0/pyproject.toml

@@ -0,0 +1,30 @@
+[project]
+name = "mcp-elk"
+version = "1.0.0"
+description = "MCP server de leitura para Elasticsearch/Kibana (ELK): busca, contagem, consultas salvas e exportação CSV"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Daniel Xavier Araújo", email = "danielxaraujo@gmail.com" }]
+requires-python = ">=3.10"
+dependencies = [
+    "mcp[cli]>=2.2",
+    "requests>=2.31",
+]
+
+[project.urls]
+Repository = "https://github.com/dxaraujo/mcp-elk"
+
+[project.scripts]
+mcp-elk = "mcp_elk.server:main"
+
+[dependency-groups]
+dev = ["pytest>=8"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["."]

mcp_elk-1.0.0/tests/test_server.py

@@ -0,0 +1,245 @@
+import csv
+import json
+from pathlib import Path
+
+import pytest
+import requests
+from requests.adapters import BaseAdapter
+
+from mcp_elk import config, server
+from mcp_elk.config import ElkConfig
+
+KIBANA = "https://kibana.test"
+ES = "https://es.test"
+HIT = {"_id": "1", "_index": "logs-1", "_source": {"@timestamp": "2026-10-08T10:00:00Z", "app": {"nome": "x"},
+                                                   "message": "m" * 3000}}
+
+
+class FakeAdapter(BaseAdapter):
+    """routes: {(METODO, url_sem_query): handler(request) -> (status, dict|bytes) ou tupla}."""
+
+    def __init__(self, routes=None):
+        super().__init__()
+        self.routes = routes or {}
+        self.calls: list[requests.PreparedRequest] = []
+
+    def send(self, request, **kwargs):
+        self.calls.append(request)
+        route = self.routes.get((request.method, request.url.split("?")[0]))
+        status, body = (route(request) if callable(route) else route) if route else (404, b"not found")
+        resp = requests.Response()
+        resp.status_code = status
+        resp._content = body if isinstance(body, bytes) else json.dumps(body).encode()
+        resp.url, resp.request = request.url, request
+        return resp
+
+    def close(self):
+        pass
+
+
+def body(req) -> dict:
+    return json.loads(req.body)
+
+
+@pytest.fixture
+def fake():
+    adapter = FakeAdapter()
+    session = server.ElkSession(ElkConfig(user="joao", password="segredo", kibana={"prod": KIBANA, "homol": KIBANA}))
+    session.session.mount("https://", adapter)
+    server.set_session(session)
+    yield adapter
+    server.set_session(None)
+
+
+@pytest.fixture
+def fake_es(fake):
+    server.get_session().cfg.es["prod"] = ES
+    return fake
+
+
+# ---------------------------------------------------------------- config
+
+def write(tmp_path: Path, text: str) -> Path:
+    p = tmp_path / "elk.properties"
+    p.write_text(text, encoding="utf-8")
+    return p
+
+
+def test_load_config(tmp_path):
+    cfg = config.load_config(write(tmp_path, "[DEFAULT]\nuser = u\npassword = p%s#s\nprod = https://k/\n"
+                                             "es_prod = https://e:9200\n"))
+    assert (cfg.user, cfg.password, cfg.kibana, cfg.es) == ("u", "p%s#s", {"prod": "https://k"},
+                                                            {"prod": "https://e:9200"})
+    assert "p%s#s" not in repr(cfg)
+
+
+def test_load_config_errors(tmp_path):
+    with pytest.raises(ValueError, match="prod"):
+        config.load_config(write(tmp_path, "[DEFAULT]\nuser = u\npassword = p\n"))
+    with pytest.raises(FileNotFoundError):
+        config.load_config(tmp_path / "nao-existe")
+
+
+# ---------------------------------------------------------------- ambiente e consulta
+
+@pytest.mark.parametrize("entrada,esperado", [(None, "prod"), ("Produção", "prod"), ("homologação", "homol"),
+                                              ("HML", "homol"), ("desenvolvimento", "dev")])
+def test_ambiente(entrada, esperado):
+    assert server._ambiente(entrada) == esperado
+
+
+def test_ambiente_desconhecido_e_sem_url(fake):
+    with pytest.raises(ValueError, match="desconhecido"):
+        server._ambiente("qa")
+    with pytest.raises(ValueError, match="'dev' sem URL"):
+        server.elk_contar("logs-*", "now-1h", consulta="x", ambiente="dev")
+
+
+def test_lucene():
+    assert server._lucene('a: x and b: "y and z" or not c') == 'a: x AND b: "y and z" OR NOT c'
+    assert server._lucene("android:1 AND brand:x") == "android:1 AND brand:x"
+
+
+def test_query():
+    q = server._query("now-1h", "now", "msg:erro", {"sis.nome": "a", "sis.cat": "b"}, [{"exists": {"field": "f"}}],
+                      "ts")
+    assert q == {"bool": {"must": [{"query_string": {"query": "msg:erro"}}], "filter": [
+        {"term": {"sis.nome": "a"}}, {"term": {"sis.cat": "b"}}, {"exists": {"field": "f"}},
+        {"range": {"ts": {"gte": "now-1h", "lte": "now"}}}]}}
+    with pytest.raises(ValueError, match="vazia"):
+        server._query("now-1h", "now", None, None, None, "ts")
+
+
+# ---------------------------------------------------------------- busca e contagem
+
+def test_buscar_logs_kibana(fake):
+    fake.routes[("POST", f"{KIBANA}/internal/search/es")] = (200, {"rawResponse": {
+        "hits": {"total": {"value": 7}, "hits": [HIT]}}})
+    out = server.elk_buscar_logs("logs-*", "now-15m", campos={"sis": "a"}, limite=5, retornar=["message"],
+                                 ambiente="homologação")
+    sent = body(fake.calls[0])
+    assert sent["params"]["index"] == "logs-*"
+    assert sent["params"]["body"]["size"] == 5 and sent["params"]["body"]["_source"] == ["message"]
+    assert sent["params"]["body"]["sort"] == [{"@timestamp": {"order": "desc"}}]
+    assert fake.calls[0].headers["kbn-xsrf"] == "true" and fake.calls[0].headers["Authorization"].startswith("Basic")
+    assert out["ambiente"] == "homol" and out["total"] == 7
+    item = out["itens"][0]
+    assert item["app.nome"] == "x" and len(item["message"]) == server.TEXTO_MAX + 1
+
+
+def test_buscar_logs_limite():
+    with pytest.raises(ValueError, match="elk_exportar_csv"):
+        server.elk_buscar_logs("logs-*", "now-1h", consulta="x", limite=500)
+
+
+def test_contar_agrupado_es_direto(fake_es):
+    fake_es.routes[("POST", f"{ES}/logs-*/_search")] = (200, {"hits": {"total": {"value": 30}, "hits": []},
+        "aggregations": {"grupos": {"buckets": [{"key": "app-a", "doc_count": 20}]}}})
+    out = server.elk_contar("logs-*", "now-1h", consulta="x", agrupar_por="sis.nome", top=3)
+    assert body(fake_es.calls[0])["aggs"] == {"grupos": {"terms": {"field": "sis.nome", "size": 3}}}
+    assert out["total"] == 30 and out["grupos"] == [{"valor": "app-a", "total": 20}]
+
+
+def test_erro_de_certificado(fake, monkeypatch):
+    def ssl_error(req):
+        raise requests.exceptions.SSLError("CERTIFICATE_VERIFY_FAILED")
+
+    fake.routes[("POST", f"{KIBANA}/internal/search/es")] = ssl_error
+    with pytest.raises(RuntimeError, match="elk-bundle.pem"):
+        server.elk_contar("logs-*", "now-1h", consulta="x")
+
+
+def test_http_403(fake):
+    fake.routes[("POST", f"{KIBANA}/internal/search/es")] = (403, b'{"error":"Forbidden"}')
+    with pytest.raises(server.ElkHttpError, match="HTTP 403 em POST"):
+        server.elk_contar("logs-*", "now-1h", consulta="x")
+
+
+# ---------------------------------------------------------------- consultas salvas, índices e campos
+
+def test_listar_consultas(fake):
+    search = {"id": "s1", "type": "search", "attributes": {"title": "Erros", "columns": ["message"],
+        "kibanaSavedObjectMeta": {"searchSourceJSON": json.dumps({
+            "query": {"query": "level:ERROR", "language": "kuery"},
+            "filter": [{"meta": {"negate": True}, "query": {"match_phrase": {"a": "b"}}},
+                       {"meta": {"disabled": True}, "query": {"match_phrase": {"c": "d"}}}]})}},
+        "references": [{"type": "index-pattern", "id": "dv1"}]}
+    saved_query = {"id": "q1", "type": "query", "attributes": {"title": "Lentas", "description": "",
+        "query": {"query": "tempo:>1000", "language": "lucene"}, "filters": []}}
+    dv = {"id": "dv1", "type": "index-pattern", "attributes": {"title": "logs-*", "timeFieldName": "@timestamp"}}
+
+    def find(req):
+        return 200, {"saved_objects": [dv] if "index-pattern" in req.url else [search, saved_query]}
+
+    fake.routes[("GET", f"{KIBANA}/api/spaces/space")] = (200, [{"id": "default"}, {"id": "neg"}])
+    fake.routes[("GET", f"{KIBANA}/api/saved_objects/_find")] = find
+    fake.routes[("GET", f"{KIBANA}/s/neg/api/saved_objects/_find")] = (200, {"saved_objects": []})
+    resp = server.elk_listar_consultas(busca="Err")
+    assert "search=Err%2A" in fake.calls[1].url
+    out = resp["itens"]
+    assert resp["total"] == 2
+    assert out[0] == {"id": "s1", "espaco": "default", "tipo": "search", "titulo": "Erros", "descricao": None, "consulta": "level:ERROR",
+                      "linguagem": "kuery", "filtros": [{"bool": {"must_not": [{"match_phrase": {"a": "b"}}]}}],
+                      "indice": "logs-*", "colunas": ["message"]}
+    assert out[1]["tipo"] == "query" and out[1]["consulta"] == "tempo:>1000" and out[1]["indice"] is None
+    assert server.elk_listar_indices(espaco="default") == [{"espaco": "default", "nome": "logs-*", "padrao": "logs-*",
+                                                            "campo_tempo": "@timestamp"}]
+    assert server.elk_listar_consultas(espaco="neg") == {"total": 0, "itens": []}
+
+
+def test_listar_campos(fake):
+    fake.routes[("GET", f"{KIBANA}/internal/data_views/_fields_for_wildcard")] = (200, {"fields": [
+        {"name": "sis.nome", "esTypes": ["keyword"], "aggregatable": True},
+        {"name": "_id", "type": "string"}, {"name": "message", "esTypes": ["text"], "aggregatable": False}]})
+    assert server.elk_listar_campos("logs-*", busca="sis") == [{"campo": "sis.nome", "tipo": "keyword",
+                                                                "agregavel": True}]
+
+
+# ---------------------------------------------------------------- exportação CSV
+
+def _hit(i, ts):
+    return {"_id": str(i), "_index": "l", "_source": {"ts": ts, "a": {"b": i}, "tags": ["x"]}, "sort": [ts]}
+
+
+def test_exportar_csv_sem_pit_nao_perde_nem_duplica(fake, tmp_path, monkeypatch):
+    monkeypatch.setattr(server, "PAGINA", 3)
+    docs = [_hit(1, 10), _hit(2, 20), _hit(3, 20), _hit(4, 20), _hit(5, 30)]
+
+    def search(req):  # simula o ES: ordena por ts e aplica search_after
+        b = body(req)["params"]["body"]
+        after = b.get("search_after", [float("-inf")])[0]
+        page = [d for d in docs if d["sort"][0] > after][:b["size"]]
+        return 200, {"rawResponse": {"hits": {"total": {"value": 5}, "hits": page}}}
+
+    fake.routes[("POST", f"{KIBANA}/internal/search/es")] = search
+    arquivo = tmp_path / "sub" / "out.csv"
+    out = server.elk_exportar_csv("l", "now-1h", str(arquivo), consulta="x", campo_tempo="ts")
+    rows = list(csv.DictReader(arquivo.open(encoding="utf-8-sig")))
+    assert [r["a.b"] for r in rows] == ["1", "2", "3", "4", "5"]
+    assert rows[0]["tags"] == '["x"]'
+    assert out == {"arquivo": str(arquivo), "linhas": 5, "total": 5, "truncado": False,
+                   "colunas": ["ts", "a.b", "tags"]}
+
+
+def test_exportar_csv_pit_e_truncado(fake_es, tmp_path, monkeypatch):
+    monkeypatch.setattr(server, "PAGINA", 2)
+    fake_es.routes[("POST", f"{ES}/l/_pit")] = (200, {"id": "pit1"})
+    fake_es.routes[("DELETE", f"{ES}/_pit")] = (200, {})
+    docs = [_hit(i, i) for i in range(1, 6)]
+
+    def search(req):
+        b = body(req)
+        assert b["pit"]["id"] == "pit1" and b["sort"][1] == {"_shard_doc": "asc"}
+        after = b.get("search_after", [0])[0]
+        return 200, {"pit_id": "pit1", "hits": {"total": {"value": 5}, "hits": [d for d in docs if d["sort"][0] > after][:2]}}
+
+    fake_es.routes[("POST", f"{ES}/_search")] = search
+    out = server.elk_exportar_csv("l", "now-1h", str(tmp_path / "o.csv"), consulta="x", retornar=["a.b"],
+                                  max_linhas=3, campo_tempo="ts")
+    assert out["linhas"] == 3 and out["truncado"] is True and out["colunas"] == ["a.b"]
+    assert fake_es.calls[-1].method == "DELETE"
+
+
+def test_exportar_csv_caminho_relativo():
+    with pytest.raises(ValueError, match="absoluto"):
+        server.elk_exportar_csv("l", "now-1h", "out.csv", consulta="x")