elog-mcp

OpenAPI/MCP Server, der LLM-Agenten schreibgeschützten Zugriff auf ELOG-Elektroniklogbücher über HTTP bietet. Referenzbereitstellung: das T2K/ND280-ELOG unter https://elog.nd280.org/elog/; funktioniert mit jeder Standard-elogd-Instanz.

• Durchsuchen von Einträgen nach Volltext (Regex), Attributen und Datumsbereich

• Einträge vollständig lesen (Attribute + Text + Anhänge)

• Anhänge herunterladen, Logbücher entdecken

Streng schreibgeschützt: Es werden nur HTTP-GET-Anfragen gesendet. TLS-Verifizierung ist standardmäßig aktiviert. Anmeldedaten stammen ausschließlich aus der Umgebung und werden nie protokolliert oder ausgegeben.

Setup

Erfordert Python ≥ 3.10 und uv:

uv sync

Related MCP server: mcp-opensearch

Konfiguration

Alle Einstellungen sind Umgebungsvariablen (ELOG_-Präfix):

Gemeinsames Präfix für jede Bereitstellung:

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

Bereitstellung

ELOG_MCP_TRANSPORT bestimmt, wie Clients mit dem Server kommunizieren:

stdio (lokale MCP-Clients)

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 (Remote-MCP-Clients)

ELOG_MCP_TRANSPORT=streamable-http uv run elog-mcp

Registrieren Sie http://127.0.0.1:8000/mcp als Remote-MCP-Server in Ihrer UI.

openapi (Open WebUI & Co.)

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

Fünf schreibgeschützte Endpunkte spiegeln die untenstehenden Tools wider (operationIds entsprechen den Toolnamen). In Open WebUI: Einstellungen → Tools → + (auf Benutzerebene, von Ihrem Browser abgerufen) oder Admin-Einstellungen → Tools (global, von dessen Backend abgerufen), geben Sie die Server-URL ein und tragen Sie Ihren ELOG_API_KEY-Wert in das Bearer-Key-Feld ein.

HTTPS: Übergeben Sie ELOG_MCP_CERTFILE/ELOG_MCP_KEYFILE oder setzen Sie einen Reverse-Proxy oder Tunnel (z. B. cloudflared tunnel --url http://localhost:8000) davor. Für lokal vertrauenswürdige Entwicklungszertifikate: mkcert -install && mkcert localhost 127.0.0.1 ::1, und geben Sie dann die beiden Dateien an die obigen Variablen weiter (absolute Pfade).

Erreichbarkeits-Faustregeln:

• Alles bindet standardmäßig an 127.0.0.1. Setzen Sie ELOG_MCP_HOST=0.0.0.0 und einen ELOG_API_KEY, wenn jemand anderes den Server erreichen muss.

• Client in Docker? 127.0.0.1 in dessen Container ist nicht Ihr Rechner — verwenden Sie http://host.docker.internal:<port> (--add-host=host.docker.internal:host-gateway unter Linux).

• Gehostete Instanz (z. B. eine Universitäts-WebUI)? Sie kann niemals das Loopback Ihres Laptops erreichen. Benutzerebene-Toolserver unterliegen zusätzlich der Content-Security-Policy der Website — wenn DevTools die Anfrage als Transferred: CSP anzeigt, hat der Browser sie blockiert, und nur eine IT-seitige Änderung von connect-src hilft. Der praktische Weg: Stellen Sie elog-mcp an einem erreichbaren Ort bereit und lassen Sie die Administratoren es einmal als globalen Toolserver registrieren.

Tools

Dieselben fünf Operationen auf jedem Transport (REST-Routen für openapi gezeigt):

Hinweise:

• Text- und Attributfilter sind reguläre Ausdrücke (elogd-Semantik); ^value$-Anker ergeben exakte Übereinstimmungen.

• Daten: YYYY-MM-DD[ HH:MM[:SS]], oder verwenden Sie last_days anstelle eines Bereichs; logbook="*" durchsucht alle bekannten Logbücher.

• Fehler erscheinen einheitlich: EntryNotFound, AuthFailed, ServerError, NetworkError, InvalidLogbook (REST-Statuscodes: 404/502/502/503/404, ungültige Abfrageparameter → 400/422).

Entwicklung

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)

Protokolldetails und Drahtformat-Referenzen finden Sie in RESOURCES.md; Architektur und Tool-Verträge in SPEC.md.