elog-mcp

OpenAPI/MCP сервер, предоставляющий LLM-агентам доступ только для чтения к электронным журналам ELOG по HTTP. Эталонное развертывание: журнал T2K/ND280 по адресу https://elog.nd280.org/elog/; работает с любым стандартным экземпляром elogd.

• Поиск записей по полному тексту (регулярные выражения), атрибутам и диапазону дат

• Чтение записей полностью (атрибуты + тело + вложения)

• Скачивание вложений, обнаружение журналов

Строго только для чтения: выполняются только HTTP GET-запросы. Проверка TLS включена по умолчанию. Учетные данные берутся только из окружения и никогда не записываются в журнал и не выводятся.

Setup

Требуется Python ≥ 3.10 и uv:

uv sync

Related MCP server: mcp-opensearch

Configuration

Все настройки задаются переменными окружения (префикс ELOG_):

Общий префикс для каждого развертывания:

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

Deployment

ELOG_MCP_TRANSPORT определяет, как клиенты общаются с сервером:

stdio (локальные MCP-клиенты)

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 (удаленные MCP-клиенты)

ELOG_MCP_TRANSPORT=streamable-http uv run elog-mcp

Зарегистрируйте http://127.0.0.1:8000/mcp как удаленный MCP-сервер в вашем интерфейсе.

openapi (Open WebUI и другие)

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

Пять конечных точек только для чтения повторяют инструменты ниже (operationIds совпадают с именами инструментов). В Open WebUI: Settings → Tools → + (на уровне пользователя, загружается вашим браузером) или Admin Settings → Tools (глобально, загружается его серверной частью), введите URL сервера и поместите значение ELOG_API_KEY в поле ключа Bearer.

HTTPS: передайте ELOG_MCP_CERTFILE/ELOG_MCP_KEYFILE или поместите перед сервером обратный прокси или туннель (например, cloudflared tunnel --url http://localhost:8000). Для локально доверенных сертификатов разработки: mkcert -install && mkcert localhost 127.0.0.1 ::1, затем передайте два файла в указанные выше переменные (абсолютные пути).

Правила доступности (эмпирические):

• Все по умолчанию привязывается к 127.0.0.1. Установите ELOG_MCP_HOST=0.0.0.0 и ELOG_API_KEY, если кто-то еще должен получить доступ к серверу.

• Клиент в Docker? 127.0.0.1 внутри его контейнера — это не ваша машина; используйте http://host.docker.internal:<port> (--add-host=host.docker.internal:host-gateway на Linux).

• Размещенный экземпляр (например, университетский WebUI)? Он никогда не сможет получить доступ к loopback вашего ноутбука. Пользовательские серверы инструментов дополнительно подчиняются Content-Security-Policy этого сайта — если DevTools показывает запрос как Transferred: CSP, браузер заблокировал его, и только изменение connect-src на стороне ИТ-отдела поможет. Практический путь: разверните elog-mcp в доступном месте и попросите администраторов зарегистрировать его один раз как глобальный сервер инструментов.

Tools

Те же пять операций на каждом транспорте (маршруты REST показаны для openapi):

Примечания:

• Фильтры по тексту и атрибутам — это регулярные выражения (семантика elogd); якоря ^value$ дают точные совпадения.

• Даты: YYYY-MM-DD[ HH:MM[:SS]] или используйте last_days вместо диапазона; logbook="*" ищет по всем известным журналам.

• Ошибки отображаются единообразно: EntryNotFound, AuthFailed, ServerError, NetworkError, InvalidLogbook (коды состояния REST: 404/502/502/503/404, недопустимые параметры запроса → 400/422).

Development

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)

Детали протокола и ссылки на формат передачи данных находятся в RESOURCES.md; архитектура и контракты инструментов — в SPEC.md.