elog-mcp

OpenAPI/MCP 服务器，为 LLM 代理提供对 ELOG 电子日志的只读访问（通过 HTTP）。参考部署：T2K/ND280 日志，位于 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

五个只读端点与下面的工具对应（operationId 与工具名称相同）。在 Open WebUI 中：设置 → 工具 → +（用户级，由您的浏览器获取）或管理员设置 → 工具（全局，由其后端获取），输入服务器 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 部署在可访问的位置，并让管理员将其注册为一次全局工具服务器。

工具

每种传输方式都有相同的五个操作（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）。

开发

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。