elog-mcp

OpenAPI/MCP servidor que da a los agentes LLM acceso de solo lectura a los cuadernos de bitácora electrónicos ELOG a través de HTTP. Despliegue de referencia: el elog de T2K/ND280 en https://elog.nd280.org/elog/; funciona con cualquier instancia estándar de elogd.

• Buscar entradas por texto completo (regex), atributos y rango de fechas

• Leer entradas completas (atributos + cuerpo + adjuntos)

• Descargar adjuntos, descubrir cuadernos de bitácora

Estrictamente de solo lectura: solo se emiten peticiones HTTP GET. La verificación TLS está activada por defecto. Las credenciales provienen únicamente del entorno y nunca se registran ni se muestran.

Configuración

Requiere Python ≥ 3.10 y uv:

uv sync

Related MCP server: mcp-opensearch

Configuración

Todos los ajustes son variables de entorno (prefijo ELOG_):

Prefijo común para cada despliegue:

export ELOG_URL=https://elog.nd280.org/elog
export ELOG_USER=your-shared-user
export ELOG_PASSWORD=your-shared-password

Despliegue

ELOG_MCP_TRANSPORT elige cómo los clientes se comunican con el servidor:

stdio (clientes MCP locales)

uv run elog-mcp

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "elog": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/elog-mcp", "run", "elog-mcp"],
      "env": { "ELOG_URL": "…", "ELOG_USER": "…", "ELOG_PASSWORD": "…" }
    }
  }
}

opencode (~/.config/opencode/opencode.json):

{
  "mcp": {
    "elog": {
      "type": "local",
      "command": ["uv", "--directory", "/absolute/path/to/elog-mcp", "run", "elog-mcp"],
      "environment": { "ELOG_URL": "…", "ELOG_USER": "…", "ELOG_PASSWORD": "…" }
    }
  }
}

streamable-http (clientes MCP remotos)

ELOG_MCP_TRANSPORT=streamable-http uv run elog-mcp

Registra http://127.0.0.1:8000/mcp como servidor MCP remoto en tu interfaz.

openapi (Open WebUI y similares)

ELOG_MCP_TRANSPORT=openapi \
ELOG_API_KEY=pick-a-random-secret \
uv run elog-mcp

Cinco endpoints de solo lectura reflejan las herramientas siguientes (los operationIds coinciden con los nombres de las herramientas). En Open WebUI: Ajustes → Herramientas → + (a nivel de usuario, obtenido por tu navegador) o Ajustes de administrador → Herramientas (global, obtenido por su backend), introduce la URL del servidor y pon el valor de tu ELOG_API_KEY en el campo de clave Bearer.

HTTPS: pasa ELOG_MCP_CERTFILE/ELOG_MCP_KEYFILE, o coloca un proxy inverso o túnel (p. ej. cloudflared tunnel --url http://localhost:8000) delante. Para certificados de desarrollo de confianza local: mkcert -install && mkcert localhost 127.0.0.1 ::1, luego proporciona los dos archivos a las variables anteriores (rutas absolutas).

Reglas prácticas de accesibilidad:

• Todo se enlaza a 127.0.0.1 por defecto. Establece ELOG_MCP_HOST=0.0.0.0 y una ELOG_API_KEY siempre que otra persona deba alcanzar el servidor.

• ¿Cliente en Docker? 127.0.0.1 dentro de su contenedor no es tu máquina — usa http://host.docker.internal:<port> (--add-host=host.docker.internal:host-gateway en Linux).

• ¿Instancia alojada (p. ej. una WebUI universitaria)? Nunca puede alcanzar el loopback de tu portátil. Los servidores de herramientas a nivel de usuario están además sujetos a la Content-Security-Policy de ese sitio — si DevTools muestra la solicitud como Transferred: CSP, el navegador la bloqueó y solo un cambio de connect-src por parte de TI ayuda. La ruta práctica: desplegar elog-mcp en algún lugar accesible y dejar que los administradores lo registren una vez como servidor de herramientas global.

Herramientas

Mismas cinco operaciones en cada transporte (rutas REST mostradas para openapi):

Notas:

• Los filtros de texto y atributos son expresiones regulares (semántica de elogd); los anclajes ^value$ dan coincidencias exactas.

• Fechas: YYYY-MM-DD[ HH:MM[:SS]], o usa last_days en lugar de un rango; logbook="*" busca en todos los cuadernos conocidos.

• Los errores aparecen de forma uniforme: EntryNotFound, AuthFailed, ServerError, NetworkError, InvalidLogbook (códigos de estado REST: 404/502/502/503/404, parámetros de consulta no válidos → 400/422).

Desarrollo

uv run pytest                # unit tests, offline
uv run pytest -m live        # live suite (needs ELOG_TEST_URL)
uv run ruff check .          # lint
uv run ruff format --check . # formatting gate
uv run mypy src              # type check (strict)

Los detalles del protocolo y las referencias de formato de cable están en RESOURCES.md; la arquitectura y los contratos de herramientas en SPEC.md.