Npm Package Ws Has 241560546 Weekly Downloads But Sdk

io.github.nexus-mcp-infra由 GitHub 账号 nexus-mcp-infra 发布v1.0.0更新于 Oct 24, 2026

Stateful WebSocket session registry with per-connection Shannon entropy delta tracking for schema di

已验证Streamable HTTP可网页运行开发者工具安全与监控

概览

AI 生成的概览

远程 MCP 服务器,用于建立和管理实时 WebSocket 会话,收发帧并给出每帧的香农熵评分。

可以做什么
  • 向 ws:// 或 wss:// 地址建立持久 WebSocket 会话并取得 session_id
  • 在已打开的会话上发送单个文本或二进制帧,返回该帧的熵增量
  • 读取缓冲区中的入站帧,每帧附带熵增量与结构校验结果
  • 查看会话遥测:连接状态、帧计数、熵统计、结构违规率与运行时长
  • 以指定状态码和原因关闭会话,并返回最终遥测快照
适用场景
适合助手需要与实时 WebSocket 服务交互的场景,例如订阅数据流、下发命令或轮询事件,并希望借助逐帧信号发现结构漂移或异常负载,而无需额外的外部监控工具。
运行要求
远程 streamable HTTP 端点,无需本地安装。未声明任何 API 密钥或请求头认证。打开会话需通过 x402 支付 0.01 USDC(Base Sepolia 测试网),因此需要能完成该支付的钱包;其余四项操作不单独计费。需要能访问目标 WebSocket 主机的网络。
安装前请注意
打开会话会产生费用(测试网上的 0.01 USDC),也是唯一收费的调用。该服务会对你提供的任意地址保持实时连接,且 extra_headers 会随升级请求转发,请勿在其中放入机密信息。收发的帧都会经过第三方服务器。会话保存在进程内存中,重启后不保留,已关闭的 session_id 无法复用。README 提示其中一个附带的 Python 封装已损坏且指向其他域名。

安装

在 SourceWeft 中

  1. 打开 控制台中的 Npm Package Ws Has 241560546 Weekly Downloads But Sdk,将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Web executable,通过 Streamable HTTP。 远程服务在工作区中配置后即可从网页运行时运行。

交给智能体安装

把这段提示词粘贴到 Claude Code、Codex、Cursor 等智能体,或 SourceWeft 对话中。智能体会读取该服务器的安装指南,先向你展示发布者、端点和登录方式,经你同意后再把它添加到你的客户端。密钥不会写进任何命令。

阅读 https://sourceweft.com/mcp/io.github.nexus-mcp-infra%2Fnpm-package-ws-has-241560546-weekly-downloads-but-sdk/install.md,并按其中说明把这个 MCP 服务器接入我的客户端。修改任何配置之前,先告诉我它的发布者、端点和登录方式,等我确认。不要把 API 密钥写进命令或我会提交的文件;问我密钥应从哪里获取。

查看智能体所依据的安装指南

其他 MCP 客户端

把它添加到你客户端的 mcpServers 配置中。

{
  "mcpServers": {
    "npm-package-ws-has-241560546-weekly-down": {
      "type": "http",
      "url": "https://npm-package-ws-has-241560546-w-production.up.railway.app/mcp"
    }
  }
}

README

ws-mcp

WebSocket session management as MCP tools — with per-frame Shannon entropy tracking.

ws has 241,560,546 weekly downloads. There are zero MCP servers that expose WebSocket primitives. This is that server.


The problem

AI agents cannot interact with live WebSocket streams without custom glue code per integration. There is no standardized way for an LLM to open a persistent connection, send a typed frame, and receive structured events as tool call responses. Debugging message flows requires external tooling (Wireshark, browser devtools) that is incompatible with agentic workflows.

ws-mcp exposes five atomic operations over HTTP: open a session, send a frame, drain buffered frames, inspect telemetry, and close. Each frame — inbound or outbound — is scored with a Shannon entropy delta relative to the session's cumulative message distribution, so an agent can detect when a stream is diverging from its expected schema without any external monitoring.


Why the entropy delta is not optional

The server maintains a live token-frequency Counter per session_id inside the same process that holds the socket open. For each frame, it computes:

delta = H(t) - H(t-1)

where H(t) is the Shannon entropy of the cumulative byte distribution after frame t. A delta near zero means the frame is statistically consistent with the session's established message pattern. A large positive delta means the frame introduced new information — schema divergence, anomalous payload, or a new message type.

This requires coupling MCP tool state with a live socket registry and a probabilistic frame classifier in the same process. It cannot be replicated by wrapping ws.send() in a stateless proxy.


Base URL

https://npm-package-ws-has-241560546-w-production.up.railway.app

Authentication

None. There is no API key, header, or auth mechanism of any kind on this asset today — every request is served regardless of headers sent.

Pricing

  • POST /ws-sessions/open requires an x402 payment: $0.01 USDC on Base Sepolia (testnet), scheme exact. A request without payment gets 402 Payment Required with the payment details in the payment-required response header.
  • All other operations (send-frame, drain-frames, telemetry, close) act on a session that was already paid for at open time and are not separately charged.

Endpoints

POST /ws-sessions/open

Establishes a persistent WebSocket connection to a target URL and registers it in the stateful session registry. Returns a session_id for all subsequent operations. Requires an x402 payment (see Pricing above).

Use when an agent needs to initiate a long-lived connection before sending or receiving frames. Do NOT use to reconnect an already-open session — call close first, or use the session_id of an existing session.

Request

json
{  "target_url": "wss://echo.websocket.org",  "connect_timeout_seconds": 10.0,  "extra_headers": {    "X-Custom-Header": "value"  }}

target_url must start with ws:// or wss:// (validated, not just a regex in the schema). connect_timeout_seconds defaults to 10.0, range 0.5–60.0. extra_headers is optional (HTTP headers sent on the upgrade request).

Response (201)

json
{  "session_id": "8662044208f54095b327ab4c29e1554c",  "target_url": "wss://echo.websocket.org",  "state": "OPEN",  "opened_at_unix": 1785012145.03,  "message": "Session '8662044208f54095b327ab4c29e1554c' is OPEN. Use session_id for all subsequent operations."}

session_id is a 32-character hex string (uuid.uuid4().hex, no dashes) — use it as-is in the paths below.

Errors: 422 if target_url doesn't start with ws:///wss://; 504 if the handshake doesn't complete within connect_timeout_seconds; 502 if the host is unreachable or refuses the connection; 503 if the server is already at NEXUS_WS_MAX_SESSIONS concurrent sessions.


POST /ws-sessions/{session_id}/send-frame

Sends a single text or binary frame over an open session and returns the frame's Shannon entropy delta relative to the session baseline.

Use for request-response patterns or publishing commands to a WebSocket server. Do NOT use to send a sequence of frames in bulk — call this endpoint once per frame. Fails if session_id does not exist or the connection is not in OPEN state.

Request

json
{  "payload": "{\"action\": \"subscribe\", \"channel\": \"trades\"}",  "frame_type": "text"}

frame_type is "text" (default) or "binary" — if binary, payload must be a hex-encoded string.

Response (200)

json
{  "session_id": "8662044208f54095b327ab4c29e1554c",  "frame_type": "text",  "payload_bytes": 44,  "entropy_after": 4.237441,  "entropy_delta": 0.245712,  "schema_valid": true,  "sent_at_unix": 1785012151.68}

Errors: 404 if session_id is not in the registry (session_id '<id>' not found in registry); 409 if the session isn't in OPEN state; 422 if frame_type is "binary" and payload isn't valid hex; 502 if the underlying socket send fails.


POST /ws-sessions/{session_id}/drain-frames

Returns up to max_frames buffered inbound frames received since the last drain (or session open), each annotated with its Shannon entropy delta and schema validation result.

Use to poll for incoming messages without holding a blocking connection. Do NOT use as a real-time streaming mechanism — it returns only frames already buffered (buffer capped at 512 frames per session; oldest frames are dropped once full).

Request

json
{  "max_frames": 10}

max_frames defaults to 32, range 1–256.

Response (200)

json
{  "session_id": "8662044208f54095b327ab4c29e1554c",  "frames_returned": 2,  "frames": [    {      "payload": "{\"event\": \"trade\", \"price\": 42381.50}",      "frame_type": "text",      "entropy_after": 3.91,      "entropy_delta": 0.12,      "schema_valid": true,      "received_at": 1785012155.203    },    {      "payload": "{\"event\": \"liquidation\", \"size\": 180000, \"side\": \"long\"}",      "frame_type": "text",      "entropy_after": 5.38,      "entropy_delta": 1.47,      "schema_valid": false,      "received_at": 1785012155.891    }  ],  "buffer_remaining": 0}

The entropy_delta of 1.47 on the second frame combined with schema_valid: false indicates the stream introduced content statistically inconsistent with the session's established byte distribution — a signal an agent can use to decide whether to escalate or re-negotiate the subscription.

Errors: 404 if session_id is not in the registry.


POST /ws-sessions/{session_id}/telemetry

Returns real-time telemetry for a session: connection state, frame counts, cumulative and rolling Shannon entropy statistics, schema violation rate, and uptime. Takes no request body.

Use to diagnose whether a stream is diverging from its expected schema or to verify a session is still alive before sending. Do NOT use as the primary liveness check in a tight loop — it recomputes rolling statistics on every call.

Response (200)

json
{  "session_id": "8662044208f54095b327ab4c29e1554c",  "target_url": "wss://echo.websocket.org",  "state": "OPEN",  "uptime_seconds": 108.77,  "frames_sent": 1,  "frames_received": 2,  "current_entropy": 4.16695,  "rolling_entropy_mean": 0.18,  "rolling_entropy_std": 0.31,  "rolling_entropy_max": 1.47,  "cumulative_entropy_bits": 4.16695,  "schema_violations": 1,  "schema_violation_rate": 0.333333,  "inbound_buffer_depth": 2}

Errors: 404 if session_id is not in the registry.


POST /ws-sessions/{session_id}/close

Sends a WebSocket close frame with the specified status code, waits for the server close handshake, and removes the session from the registry. Returns a final telemetry snapshot. session_id is permanently deallocated after this call and cannot be reused.

Request (both fields optional)

json
{  "status_code": 1000,  "reason": "agent task complete"}

status_code defaults to 1000, range 1000–4999 (RFC 6455). reason defaults to "", max 123 bytes.

Response (200)

json
{  "session_id": "8662044208f54095b327ab4c29e1554c",  "target_url": "wss://echo.websocket.org",  "final_state": "CLOSED",  "frames_sent": 1,  "frames_received": 2,  "terminal_entropy": 4.16695,  "schema_violations": 1,  "uptime_seconds": 310.2,  "message": "Session '8662044208f54095b327ab4c29e1554c' closed with status 1000. Total frames exchanged: 3. session_id is permanently deallocated."}

Errors: 404 if session_id is not in the registry.


End-to-end example: open a session, send a frame, drain, close

python
import httpx
BASE = "https://npm-package-ws-has-241560546-w-production.up.railway.app"
# 1. Open a session (requires x402 payment on this call — omitted here for brevity,#    see https://docs.x402.org for how to attach a payment header)r = httpx.post(f"{BASE}/ws-sessions/open", json={    "target_url": "wss://echo.websocket.org",    "connect_timeout_seconds": 10.0,})r.raise_for_status()session_id = r.json()["session_id"]
# 2. Send a frame (not billed)httpx.post(f"{BASE}/ws-sessions/{session_id}/send-frame", json={    "payload": '{"action": "ping"}',    "frame_type": "text",}).raise_for_status()
# 3. Drain buffered inbound frames, alert on entropy spikesENTROPY_ALERT_THRESHOLD = 1.0
drain = httpx.post(f"{BASE}/ws-sessions/{session_id}/drain-frames", json={    "max_frames": 20,}).json()
for frame in drain["frames"]:    if frame["entropy_delta"] > ENTROPY_ALERT_THRESHOLD or not frame["schema_valid"]:        print(f"[ALERT] delta={frame['entropy_delta']:.2f} schema_valid={frame['schema_valid']}")        print(f"        payload={frame['payload'][:120]}")
# 4. Inspect session health before deciding to continuetelemetry = httpx.post(f"{BASE}/ws-sessions/{session_id}/telemetry").json()print(f"schema_violation_rate={telemetry['schema_violation_rate']:.3f} "      f"current_entropy={telemetry['current_entropy']:.2f}")
# 5. Close cleanlyhttpx.post(f"{BASE}/ws-sessions/{session_id}/close", json={    "status_code": 1000,    "reason": "task complete",}).raise_for_status()

curl example

bash
# Open a session (requires x402 payment — this call alone will return 402# without a valid payment header; see https://docs.x402.org)curl -X POST https://npm-package-ws-has-241560546-w-production.up.railway.app/ws-sessions/open \  -H "Content-Type: application/json" \  -d '{"target_url": "wss://echo.websocket.org"}'
# Send a frame (replace SESSION_ID with the value returned above — not billed)curl -X POST https://npm-package-ws-has-241560546-w-production.up.railway.app/ws-sessions/SESSION_ID/send-frame \  -H "Content-Type: application/json" \  -d '{"payload": "hello world", "frame_type": "text"}'
# Drain buffered inbound framescurl -X POST https://npm-package-ws-has-241560546-w-production.up.railway.app/ws-sessions/SESSION_ID/drain-frames \  -H "Content-Type: application/json" \  -d '{"max_frames": 5}'

MCP

Connect an MCP-compatible client to the streamable HTTP endpoint at:

https://npm-package-ws-has-241560546-w-production.up.railway.app/mcp

Exposes the same 5 operations as MCP tools (open_websocket_session, send_typed_ws_frame, drain_ws_frame_buffer, inspect_ws_session_telemetry, close_websocket_session), with the same parameters and payment requirement (open_websocket_session requires x402 payment; the other 4 do not).


SDKs

  • sdk_wrappers/sdk.js — real HTTP client (axios) against the base URL above. Published to npm as @nexus-mcp-infra/npm-package-ws-has-241560546-weekly-downloads-but-sdk. This is the one to use.
  • mcp_wrapper/npm_package_ws_has_241560546_weekly_downloads_but_sdk.py — do not use. It defaults to a placeholder domain (https://api.ws-mcp.nexus.ai/v1) that isn't this service, calls routes (/sessions/open, /frames/send, etc.) that don't exist on this API, and requires an api_key that this service doesn't check. It was never fixed after the initial build; kept in the repo for history, not for use.

Direct HTTP calls to the endpoint above (via httpx, requests, or curl as shown) require no SDK.


Error reference

HTTP statusCondition
402Payment required (only on POST /ws-sessions/open, x402)
404session_id does not exist in the registry
409Session is not in OPEN state (e.g., not yet connected or already closing)
422target_url is not a valid ws:///wss:// URL, or a binary payload is not valid hex
502Network error connecting to target_url, or error sending a frame
503Session registry at capacity
504WebSocket handshake did not complete within connect_timeout_seconds

Stack

Python 3.13 — FastAPI — websockets (asyncio-native). The session registry and per-session entropy state live in-process; the entropy tracker maintains a token-frequency Counter per session_id that is updated on every frame without blocking the socket loop. Sessions do not survive a process restart/redeploy.

来源:README.md,提交 36d0318

工具

5

nexus_npm_package_ws_has_241560546_weekly_down_open_websocket_session

Establishes a persistent WebSocket connection to a target URL and registers it in the stateful session registry. Returns a session_id for all subsequent operations. Use when an agent needs to initiate a long-lived connection before sending or receiving frames. Do NOT use to reconnect an already-open session -- call close_websocket_session first, or use the session_id of an existing session.

输入参数target_url必填connect_timeout_seconds

nexus_npm_package_ws_has_241560546_weekly_down_send_typed_ws_frame

Sends a single text or binary frame over an open session and returns the frame's Shannon entropy delta relative to the session baseline. Use for request-response patterns or publishing commands to a WebSocket server. Do NOT use to send a sequence of frames in bulk -- call this tool once per frame. Fails if session_id does not exist or connection is not in OPEN state.

输入参数payload必填frame_typesession_id必填

nexus_npm_package_ws_has_241560546_weekly_down_drain_ws_frame_buffer

Returns up to max_frames buffered inbound frames received since the last drain (or session open), each annotated with its Shannon entropy delta and schema validation result. Use to poll for incoming messages without holding a blocking connection. Do NOT use as a real-time streaming mechanism -- it returns only frames already buffered.

输入参数max_framessession_id必填

nexus_npm_package_ws_has_241560546_weekly_down_inspect_ws_session_telemetry

Returns real-time telemetry for a session: connection state, frame counts, cumulative and rolling Shannon entropy statistics, schema violation rate, and uptime. Use to diagnose whether a stream is diverging from its expected schema or to verify a session is still alive before sending. Do NOT use as the primary liveness check in a tight loop.

输入参数session_id必填

nexus_npm_package_ws_has_241560546_weekly_down_close_websocket_session

Sends a WebSocket close frame with the specified status code, waits for the server close handshake, and removes the session from the registry. Returns a final telemetry snapshot. Use when a session is no longer needed. Do NOT use to temporarily pause a session -- the session_id is permanently deallocated after this call and cannot be reused.

输入参数reasonsession_id必填status_code

版本历史

1
  1. v1.0.0最新Sep 16, 2026

评分

已满足适用检查项的 90%

该评分衡量此收录条目的完整程度,依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价,也不表示服务器安全或当前可用:可连通性是带日期的检查结果,评分也不包含安装量或用户评价。

  • 近 30 天内可连通必需25 分
  • 已声明认证方式必需10 分
  • 已列出工具必需15 分
  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分

    请在仓库或注册中心条目中声明许可证。