Helium Rapid Websocket MCP

WebSocket MCP服务器

MCP服务器，连接到WebSocket并将实时日志条目暴露给 光标 （或任何MCP客户端）进行调试。它支持两种传输方式：

安装： npm install badger-websocket-mcp 或跑步 npx badger-websocket-mcp

• 标准 （建议用于Cursor）：Cursor生成服务器并通过以下方式传递配置 mcp.json env。所有凭据都保存在mcp.json中。
• 上海证券交易所：服务器作为HTTP进程运行，Cursor通过URL连接。新消息通过SSE上的MCP资源订阅推送。

存储库：

建筑

sequenceDiagram
  participant Cursor
  participant MCP as MCP_Server
  participant WS as WebSocket

  Cursor->>MCP: resources/list
  MCP-->>Cursor: logs resource
  Cursor->>MCP: resources/subscribe (ws-log://logs)
  MCP-->>Cursor: subscribed
  MCP->>WS: connect (wss + Basic auth)
  WS-->>MCP: log message
  MCP->>MCP: append to buffer, emit resources/updated
  MCP->>Cursor: notifications/resources/updated (ws-log://logs)
  Cursor->>MCP: resources/read (ws-log://logs)
  MCP-->>Cursor: current log buffer (text)

先决条件

• Node.js 18岁或以后
• 光标 支持MCP（或其他MCP客户端）
• WebSocket的凭据（用户名和密码）

使用NPM包

无需克隆或构建。直接安装并运行：

npm install badger-websocket-mcp

或者使用npx（无需安装）：

npx badger-websocket-mcp

对于Cursor stdio模式，添加到 mcp.json 并指向包裹：

• npx： "command": "npx", "args": ["-y", "badger-websocket-mcp"]
• 安装： "command": "node", "args": ["${workspaceFolder}/node_modules/badger-websocket-mcp/build/index.js"]

看 光标配置 如需查看完整示例。

配置：凭据和WebSocket URL

服务器仅需要MCP服务器配置中的配置。集 WS_URL, WS_USER，以及 WS_PASSWORD （或 WS_AUTH)在 env 一块 .cursor/mcp.jsonCursor在生成服务器时将这些传递给进程。

\*DEBUG_LOG_FILE 当需要时 OUTPUT_TO_CURSOR_DEBUG_LOG 这是真的。光标解析 ${workspaceFolder} 在mcp.json中使用时。

备选方案： 使用 WS_AUTH=username:password 而不是 WS_USER 和 WS_PASSWORD.

您可以在中使用文字值 mcp.json 或光标插值（例如。 "WS_USER": "${env:HELIUM_USER}")从shell环境中读取。不要承诺 mcp.json 如果它包含秘密；在这个回购中，它被忽视了。

输出到游标调试日志

使用Cursor进行调试时，您可以将websocket输出管道传输到代理可以读取的格式化文件。

1. 集 OUTPUT_TO_CURSOR_DEBUG_LOG 到 "true" 在 mcp.json env.
2. 集 DEBUG_LOG_FILE 输出路径，例如。 "${workspaceFolder}/.cursor/debug.log".

示例 mcp.json env块：

"env": {
  "MCP_TRANSPORT": "stdio",
  "WS_URL": "wss://helium.mezzanineware.com/api/ws2/logging?appId=YOUR_APP_ID",
  "WS_USER": "your-username",
  "WS_PASSWORD": "your-password",
  "OUTPUT_TO_CURSOR_DEBUG_LOG": "true",
  "DEBUG_LOG_FILE": "${workspaceFolder}/.cursor/debug.log"
}

Helium JSON格式的日志消息被解析并写成： {local timestamp} - {LEVEL} - {message}时间戳使用系统的本地时区。例如：

2026-02-13T12:45:18.651+02:00 - WARN - WaterMapCurrent:feature groups fallback for layer=vw_geo_wa_pipe_full

连接生命周期事件（打开、关闭、错误）也会被写入。非JSON或格式错误的消息将保持不变。

设置

从源代码克隆仓库并安装：

git clone https://github.com/ajgreyling/badger-websocket-mcp.git
cd badger-websocket-mcp

1. 安装依赖项

   npm install

1. 设置配置 （参见 配置 以上）：set WS_URL, WS_USER，以及 WS_PASSWORD （或 WS_AUTH)in mcp.json env。对于SSE模式，在启动服务器时将它们导出到shell中。

1. 可选： 集 PORT （默认值： 3000)对于处于SSE模式的HTTP服务器。

1. 构建并运行

   npm run build
   npm start

服务器正在监听 http://127.0.0.1:3000 （或你的 PORT).终点：

- GET/mcp --SSE流（光标在此处连接） - POST/消息 --JSON-RPC消息（由客户端使用 ?sessionId=...)

对于开发（运行TypeScript而不构建）：

   npm run dev

运行测试脚本(node test-get-logs.mjs)，set WS_USER 和 WS_PASSWORD 在您的环境中（例如。 export WS_USER=... WS_PASSWORD=...).

光标配置

选项A:stdio（mcp.json中的配置）

在中配置WebSocket URL和凭据 mcp.json 因此，Cursor会生成服务器。不需要单独的服务器进程。

1. 打开 光标设置 → 特性 → 主控程序.
2. 添加到您的 mcp.json （项目： .cursor/mcp.json 或全球： ~/.cursor/mcp.json).

使用npx （无需安装，NPM包）：

{
  "mcpServers": {
    "helium-logs": {
      "command": "npx",
      "args": ["-y", "badger-websocket-mcp"],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "WS_URL": "wss://helium.mezzanineware.com/api/ws2/logging?appId=YOUR_APP_ID",
        "WS_USER": "your-username",
        "WS_PASSWORD": "your-password",
        "OUTPUT_TO_CURSOR_DEBUG_LOG": "true",
        "DEBUG_LOG_FILE": "${workspaceFolder}/.cursor/debug.log"
      }
    }
  }
}

使用已安装的NPM软件包：

{
  "mcpServers": {
    "helium-logs": {
      "command": "node",
      "args": ["${workspaceFolder}/node_modules/badger-websocket-mcp/build/index.js"],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "WS_URL": "wss://helium.mezzanineware.com/api/ws2/logging?appId=YOUR_APP_ID",
        "WS_USER": "your-username",
        "WS_PASSWORD": "your-password",
        "OUTPUT_TO_CURSOR_DEBUG_LOG": "true",
        "DEBUG_LOG_FILE": "${workspaceFolder}/.cursor/debug.log"
      }
    }
  }
}

从源头进行测试 (克隆仓库，之后 npm run build):

{
  "mcpServers": {
    "helium-logs": {
      "command": "node",
      "args": ["${workspaceFolder}/build/index.js"],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "WS_URL": "wss://helium.mezzanineware.com/api/ws2/logging?appId=YOUR_APP_ID",
        "WS_USER": "your-username",
        "WS_PASSWORD": "your-password",
        "OUTPUT_TO_CURSOR_DEBUG_LOG": "true",
        "DEBUG_LOG_FILE": "${workspaceFolder}/.cursor/debug.log"
      }
    }
  }
}

OUTPUT_TO_CURSOR_DEBUG_LOG 和 DEBUG_LOG_FILE 是可选的；省略或设置 OUTPUT_TO_CURSOR_DEBUG_LOG 到 "false" 禁用文件中的管道日志。

1. 重新启动Cursor或重新加载MCP服务器。

选项B:SSE（独立HTTP服务器）

1. 启动服务器 （请参阅上面的设置），因此它在Cursor连接之前正在监听。
2. 打开 光标设置 → 特性 → 主控程序.
3. 配置：

- 运输： SSE（或选择基于URL的远程服务器）。 - 网址： http://127.0.0.1:3000/mcp\ （使用您的 PORT 如果你改变了它。）

示例 mcp.json 条目（服务器必须在设置了环境变量的情况下运行）：

{
  "mcpServers": {
    "websocket-logs": {
      "url": "http://127.0.0.1:3000/mcp"
    }
  }
}

在连接Cursor之前，使用WebSocket URL和凭据运行服务器：

export WS_URL="wss://helium.mezzanineware.com/api/ws2/logging?appId=09a1e3ab-6219-4206-99fb-c5c68de47382"
export WS_USER="your-username"
export WS_PASSWORD="your-password"
npm start

游标中的用法

• 资源： 在MCP/上下文UI中，打开资源 WebSocket日志 (ws-log://logs).订阅它，这样当新的日志行到达时，游标就会刷新。
• 工具： 代理人可以打电话 get_ws_logs 从内存缓冲区中获取日志条目。所有参数都是可选的，可以组合使用：

示例：

• 最近100条记录： { "lines": 100 }
• 两次之间的条目： { "from_time": "2026-03-13T08:00:00+02:00", "to_time": "2026-03-13T09:00:00+02:00" }
• 窗口内的最后50个条目： { "from_time": "2026-03-13T08:00:00+02:00", "lines": 50 }
• 所有缓冲条目： {} （无争议）

输出已格式化——Helium JSON条目呈现为 {timestamp} - {key} - {value}无效的时间戳字符串返回结构化错误。

游标401（wscat/终端工作，游标获取401）

当Cursor生成MCP时，即使终端使用相同的凭据，WebSocket连接也可以获得401。 解决方法：从终端运行服务器 并通过URL连接光标：

1. 从终端启动服务器（凭据在那里工作）：

   cd badger-websocket-mcp
   ./scripts/start-munic-chat-logs.sh   # for munic-chat (port 3000)
   # or
   ./scripts/start-sams-logs.sh          # for sams (port 3001)

1. 继续运行。在 mcp.json 使用URL传输：

   "munic-chat-logs": { "url": "http://127.0.0.1:3000/mcp" }
   "sams-logs":       { "url": "http://127.0.0.1:3001/mcp" }

1. 重新启动游标。

用env覆盖凭据： WS_USER=... WS_PASSWORD=... ./scripts/start-munic-chat-logs.sh

故障排除

WebSocket error: Unexpected server response: 401 --服务器拒绝了凭据。客户端正确发送基本身份验证；401表示此端点不接受用户名/密码。从命令行验证：

wscat -c "wss://helium.mezzanineware.com/api/ws2/logging?appId=YOUR_APP_ID" --auth "USERNAME:PASSWORD"

如果wscat也获得401，则凭证是错误的或不允许记录API（例如，不同的环境、密码更改或未授予API访问权限）。与管理员确认。

安全

• 做 不 提交凭据。集 WS_USER 和 WS_PASSWORD （或 WS_AUTH)只有在你的 mcp.json 或者，如果使用 ${env:...} 插值，在您的shell环境中。不要承诺 mcp.json 如果它包含秘密；在这个回购中，它被忽视了。