elog-mcp

OpenAPI/MCP 서버로, LLM 에이전트에게 ELOG 전자 로그북에 대한 읽기 전용 HTTP 접근을 제공합니다. 참조 배포: T2K/ND280 elog https://elog.nd280.org/elog/; 표준 elogd 인스턴스와 함께 동작합니다.

• 전체 텍스트(정규식), 속성, 날짜 범위로 항목 검색

• 항목 전체 읽기(속성 + 본문 + 첨부 파일)

• 첨부 파일 다운로드, 로그북 검색

엄격히 읽기 전용: HTTP GET 요청만 발행합니다. TLS 검증은 기본적으로 켜져 있습니다. 자격 증명은 환경 변수에서만 가져오며 절대 로그에 기록되거나 에코되지 않습니다.

설정

Python ≥ 3.10 및 uv 필요:

uv sync

Related MCP server: mcp-opensearch

구성

모든 설정은 환경 변수(ELOG_ 접두사)입니다:

모든 배포에 공통 접두사:

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

배포

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

UI에서 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

아래 도구를 미러링하는 5개의 읽기 전용 엔드포인트가 있습니다(operationId는 도구 이름과 동일). 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>를 사용하세요 (Linux에서는 --add-host=host.docker.internal:host-gateway).

• 호스팅된 인스턴스(예: 대학 WebUI)? 여러분의 노트북 루프백에 절대 도달할 수 없습니다. 사용자 수준 도구 서버는 추가로 해당 사이트의 Content-Security-Policy의 적용을 받습니다 — DevTools에서 요청이 Transferred: CSP로 표시되면 브라우저가 차단한 것이며, IT 측의 connect-src 변경만이 도움이 됩니다. 실용적인 방법: elog-mcp를 도달 가능한 곳에 배포하고 관리자가 한 번 전역 도구 서버로 등록하게 하세요.

도구

모든 전송에서 동일한 5가지 작업 (openapi에 대한 REST 경로 표시):

참고:

• 텍스트 및 속성 필터는 정규식입니다(elogd 의미론); ^value$ 앵커는 정확히 일치를 제공합니다.

• 날짜: YYYY-MM-DD[ HH:MM[:SS]], 또는 범위 대신 last_days를 사용하세요; logbook="*"는 알려진 모든 로그북을 검색합니다.

• 오류는 균일하게 표시됩니다: EntryNotFound, AuthFailed, ServerError, NetworkError, InvalidLogbook (REST 상태 코드: 404/502/502/503/404, 잘못된 쿼리 매개변수 → 400/422).

개발

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에 있습니다.