npm-package-ws-has-241560546-weekly-downloads-but-sdk

ws-mcp

MCP ツールとしての WebSocket セッション管理 — フレームごとのシャノンエントロピー追跡機能付き。

ws の週間ダウンロード数は 241,560,546 件です。WebSocket プリミティブを公開する MCP サーバーはひとつもありません。これがそのサーバーです。

---

問題点

AI エージェントは、インテグレーションごとにカスタムのグルーコードを用意しなければ、ライブ WebSocket ストリームとやり取りできません。LLM が永続的な接続を開き、型付きフレームを送信し、構造化されたイベントをツール呼び出しの応答として受け取るための標準化された方法がありません。メッセージフローのデバッグには、エージェント型ワークフローと互換性のない外部ツール（Wireshark、ブラウザーの開発者ツール）が必要です。

ws-mcp は HTTP 経由で、セッションを開く、フレームを送信する、バッファーされたフレームを取得する、テレメトリーを調べる、セッションを閉じるという 5 つのアトミックな操作を公開します。各フレーム（受信または送信）は、セッションの累積メッセージ分布を基準としたシャノンエントロピーの変化量で評価されるため、外部監視を使わずに、ストリームが想定スキーマから逸脱しているかどうかをエージェントが検出できます。

---

エントロピーの変化量が必須である理由

サーバーは、ソケットを開いている同じプロセス内で、session_id ごとにライブのトークン頻度 Counter を保持します。各フレームについて、次のように計算します。

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

ここで H(t) は、フレーム t の処理後における累積バイト分布のシャノンエントロピーです。変化量がゼロに近い場合、そのフレームはセッションで確立されたメッセージパターンと統計的に一貫しています。大きな正の変化量は、そのフレームによって新しい情報（スキーマの逸脱、異常なペイロード、新しいメッセージタイプ）が持ち込まれたことを示します。

これには、同じプロセス内で MCP ツールの状態をライブソケットレジストリーおよび確率的なフレーム分類器と連携させる必要があります。ステートレスなプロキシで ws.send() をラップしても再現できません。

---

ベース URL

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

認証

ありません。 現在、このサービスには API キー、ヘッダー、その他いかなる種類の認証機構もありません。送信されたヘッダーにかかわらず、すべてのリクエストが処理されます。

料金

• POST /ws-sessions/open には x402 の支払いが必要です。Base Sepolia（テストネット）で $0.01 USDC、スキームは exact です。支払いなしのリクエストには 402 Payment Required が返され、支払いの詳細は payment-required レスポンスヘッダーに含まれます。
• その他すべての操作（send-frame、drain-frames、telemetry、close）は、セッションを開いた時点ですでに支払い済みであるセッションに対して実行され、別途課金されません。

---

エンドポイント

POST /ws-sessions/open

対象 URL への永続的な WebSocket 接続を確立し、ステートフルなセッションレジストリーに登録します。以降のすべての操作で使用する session_id を返します。x402 の支払いが必要です（上記の「料金」を参照）。

フレームの送受信に先立って、エージェントが長期間維持される接続を開始する必要がある場合に使用します。すでに開いているセッションへの再接続には使用しないでください。まず close を呼び出すか、既存のセッションの session_id を使用してください。

リクエスト

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

target_url は ws:// または wss:// で始まる必要があります（スキーマ内の正規表現だけではなく、実際に検証されます）。connect_timeout_seconds の既定値は 10.0、範囲は 0.5～60.0 です。extra_headers は省略可能です（アップグレードリクエストで送信される HTTP ヘッダー）。

レスポンス（201）

{
  "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 は 32 文字の 16 進文字列（uuid.uuid4().hex、ハイフンなし）です。以下のパスでは、そのまま使用してください。

エラー：target_url が ws://／wss:// で始まらない場合は 422、connect_timeout_seconds 以内にハンドシェイクが完了しない場合は 504、ホストに到達できないか接続が拒否された場合は 502、サーバーがすでに NEXUS_WS_MAX_SESSIONS 個の同時セッションに達している場合は 503。

---

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

オープン中のセッションに単一のテキストフレームまたはバイナリフレームを送信し、セッションのベースラインと比較したフレームのシャノンエントロピーの変化量を返します。

リクエストとレスポンスのパターンや、WebSocket サーバーへのコマンドの公開に使用します。フレームをまとめて一括送信するためには使用しないでください。フレームごとにこのエンドポイントを呼び出してください。session_id が存在しない場合、または接続が OPEN 状態でない場合は失敗します。

リクエスト

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

frame_type は "text"（デフォルト）または "binary" です。バイナリの場合、payload は 16 進数でエンコードされた文字列である必要があります。

レスポンス（200）

{
  "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
}

エラー：session_id がレジストリに存在しない場合は 404（session_id '<id>' not found in registry）、セッションが OPEN 状態でない場合は 409、frame_type が "binary" で payload が有効な 16 進数でない場合は 422、基盤となるソケットの送信に失敗した場合は 502 です。

---

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

前回のドレイン時（またはセッションのオープン時）以降に受信した、バッファー内の受信フレームを最大 max_frames 件返します。各フレームには、シャノンエントロピーの変化量とスキーマ検証結果が付加されます。

ブロッキング接続を維持せずに受信メッセージをポーリングする場合に使用します。リアルタイムのストリーミング手段としては使用しないでください。すでにバッファーに格納されたフレームのみを返します（セッションあたりのバッファー上限は 512 フレームで、上限に達すると最も古いフレームが破棄されます）。

リクエスト

{
  "max_frames": 10
}

max_frames のデフォルト値は 32、範囲は 1～256 です。

レスポンス（200）

{
  "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
}

2 番目のフレームの entropy_delta が 1.47 で、schema_valid: false であることは、ストリームに、セッションで確立されたバイト分布と統計的に一致しない内容が含まれていたことを示します。これは、エージェントがエスカレーションするか、サブスクリプションを再ネゴシエートするか判断する際に利用できるシグナルです。

エラー：session_id がレジストリに存在しない場合は 404 です。

---

POST /ws-sessions/{session_id}/telemetry

セッションのリアルタイムテレメトリを返します。接続状態、フレーム数、累積およびローリングのシャノンエントロピー統計、スキーマ違反率、稼働時間が含まれます。リクエストボディは不要です。

ストリームが想定されるスキーマから逸脱しているかを診断する場合や、送信前にセッションがまだアクティブであることを確認する場合に使用します。短い間隔でのループにおける主要な稼働確認手段としては使用しないでください。呼び出しのたびにローリング統計が再計算されます。

レスポンス（200）

{
  "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
}

エラー：session_id がレジストリに存在しない場合は 404 です。

---

POST /ws-sessions/{session_id}/close

指定したステータスコードで WebSocket のクローズフレームを送信し、サーバーとのクローズハンドシェイクを待ってから、セッションをレジストリから削除します。最終的なテレメトリスナップショットを返します。この呼び出しの後、session_id は恒久的に割り当て解除され、再利用できません。

リクエスト（両フィールドとも任意）

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

status_code のデフォルト値は 1000、範囲は 1000～4999（RFC 6455）です。reason のデフォルト値は ""、最大長は 123 バイトです。

レスポンス（200）

{
  "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."
}

エラー：session_id がレジストリに存在しない場合は 404 です。

---

エンドツーエンドの例：セッションを開き、フレームを送信し、ドレインして閉じる

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 spikes
ENTROPY_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 continue
telemetry = 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 cleanly
httpx.post(f"{BASE}/ws-sessions/{session_id}/close", json={
    "status_code": 1000,
    "reason": "task complete",
}).raise_for_status()

---

curl の例

# 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 frames
curl -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

MCP 対応クライアントを、以下のストリーミング可能な HTTP エンドポイントに接続します。

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

MCP ツールとして同じ 5 つの操作（open_websocket_session、send_typed_ws_frame、drain_ws_frame_buffer、inspect_ws_session_telemetry、close_websocket_session）を、同じパラメーターと支払い要件で提供します（open_websocket_session には x402 による支払いが必要ですが、他の 4 つには必要ありません）。

---

SDK

• sdk_wrappers/sdk.js — 上記のベース URL を使用する、実際の HTTP クライアント（axios）です。npm では @nexus-mcp-infra/npm-package-ws-has-241560546-weekly-downloads-but-sdk として公開されています。使用するのはこちらです。
• mcp_wrapper/npm_package_ws_has_241560546_weekly_downloads_but_sdk.py — 使用しないでください。 プレースホルダーのドメイン（https://api.ws-mcp.nexus.ai/v1）をデフォルトで使用しますが、これはこのサービスのものではありません。また、この API に存在しないルート（/sessions/open、/frames/send など）を呼び出し、このサービスではチェックされない api_key を要求します。初回ビルド以降、修正されていません。履歴を残すためにリポジトリに置かれていますが、使用しないでください。

上記のエンドポイントへの直接の HTTP 呼び出し（例に示す httpx、requests、curl 経由）には SDK は不要です。

---

エラーリファレンス

HTTP ステータス	条件
402	支払いが必要です（POST /ws-sessions/open のみ。x402）
404	レジストリに session_id が存在しません
409	セッションが OPEN 状態ではありません（例：まだ接続されていない、またはすでに終了処理中）
422	target_url が有効な ws://／wss:// URL ではない、またはバイナリの payload が有効な 16 進数ではありません
502	target_url への接続中にネットワークエラーが発生した、またはフレーム送信中にエラーが発生しました
503	セッションレジストリが上限に達しています
504	connect_timeout_seconds 以内に WebSocket ハンドシェイクが完了しませんでした

---

スタック

Python 3.13 — FastAPI — websockets（asyncio ネイティブ）。セッションレジストリとセッションごとのエントロピー状態はプロセス内に保持されます。エントロピートラッカーは、ソケットループをブロックせずに各フレームで更新される、session_id ごとのトークン頻度 Counter を維持します。プロセスの再起動や再デプロイ後にセッションは引き継がれません。