Add Python unified parity and MCP server

Author: jaws777

PYTHON_SDK_UNIFIED_PARITY_AND_MCP.md

@@ -0,0 +1,69 @@
+# Python SDK Unified Parity And MCP
+
+This document tracks the Python SDK additions required to keep pace with the Hypernode unified-sidecar rollout completed on March 12, 2026.
+
+## Added Unified Client Coverage
+
+The Python `UnifiedStreamClient` now exposes the browser-safe Hypernode surfaces:
+
+- `consensus_pulse()`
+- `all_mids(dex="")`
+- `l2_book(coin, dex="", depth=None)`
+- `asset_contexts(coin=None, dex="")`
+- `sse_all_mids(dex="", max_events=20)`
+- `sse_l2_book(coin, dex="", depth=None, max_events=20)`
+- `sse_asset_contexts(coin=None, dex="", max_events=20)`
+
+These map to:
+
+- `GET /api/v1/unified/consensus-pulse`
+- `GET /api/v1/unified/all-mids`
+- `GET /api/v1/unified/l2-book`
+- `GET /api/v1/unified/asset-contexts`
+- and their SSE `/stream` variants
+
+## Added Status Client
+
+The Python SDK now ships `StatusClient` for:
+
+- `health()`
+- `public_status()`
+- `private_status()`
+- `admin_tokens()`
+
+Private/admin calls use `HYPER_STATUS_TOKEN`.
+
+## Added Python MCP
+
+The SDK now ships a stdio MCP server and console entrypoint:
+
+- module: `hypercore_sdk.mcp`
+- entrypoint: `hypercore-sdk-mcp`
+
+Current MCP tools:
+
+- `catalog_interfaces`
+- `grpc_get_mid_price`
+- `grpc_stream_mids_sample`
+- `grpc_get_block_number`
+- `grpc_stream_liquidations_sample`
+- `unified_get_stats`
+- `unified_get_events`
+- `unified_get_consensus_pulse`
+- `unified_get_all_mids`
+- `unified_get_l2_book`
+- `unified_get_asset_contexts`
+- `status_get_public`
+- `status_get_private`
+- `rpc_call`
+
+## Validation
+
+Validated in this repo with:
+
+- `pytest`
+- `mypy -p hypercore_sdk`
+- `python -m build`
+- `python -m twine check dist/*`
+
+The parity and MCP additions keep the Python SDK aligned with the TypeScript SDK for the Hypernode-local browser-safe market-data surfaces.

hypercore_sdk/__init__.py

@@ -3,14 +3,18 @@
 from .api import HyperCoreAPI
 from .config import SDKConfig
 from .grpc_client import GrpcClient
+from .mcp import HypercoreMCPServer
 from .speed import run_grpc_health_speed_test, run_rpc_speed_test, run_ws_speed_test
+from .status import StatusClient
 from .unified_stream import UnifiedStreamClient
 from .ws import get_price_from_ws
 
 __all__ = [
     "GrpcClient",
     "HyperCoreAPI",
+    "HypercoreMCPServer",
     "SDKConfig",
+    "StatusClient",
     "UnifiedStreamClient",
     "get_price_from_ws",
     "run_grpc_health_speed_test",

hypercore_sdk/cli.py

@@ -137,6 +137,28 @@ def _build_parser() -> argparse.ArgumentParser:
     stream_sse.add_argument("--max-events", type=int, default=20)
     _add_common_network_args(stream_sse)
 
+    stream_pulse = stream_sub.add_parser("consensus-pulse", help="Get unified consensus pulse metrics.")
+    stream_pulse.add_argument("--stream-url", default=DEFAULT_CFG.unified_stream_url)
+    _add_common_network_args(stream_pulse)
+
+    stream_all_mids = stream_sub.add_parser("all-mids", help="Get browser-safe allMids snapshot from unified stream.")
+    stream_all_mids.add_argument("--stream-url", default=DEFAULT_CFG.unified_stream_url)
+    stream_all_mids.add_argument("--dex", default="")
+    _add_common_network_args(stream_all_mids)
+
+    stream_l2_book = stream_sub.add_parser("l2-book", help="Get browser-safe canonical L2 book snapshot from unified stream.")
+    stream_l2_book.add_argument("--stream-url", default=DEFAULT_CFG.unified_stream_url)
+    stream_l2_book.add_argument("--coin", required=True)
+    stream_l2_book.add_argument("--dex", default="")
+    stream_l2_book.add_argument("--depth", type=int, default=None)
+    _add_common_network_args(stream_l2_book)
+
+    stream_asset_contexts = stream_sub.add_parser("asset-contexts", help="Get funding/OI/24h volume asset contexts from unified stream.")
+    stream_asset_contexts.add_argument("--stream-url", default=DEFAULT_CFG.unified_stream_url)
+    stream_asset_contexts.add_argument("--coin", default=None)
+    stream_asset_contexts.add_argument("--dex", default="")
+    _add_common_network_args(stream_asset_contexts)
+
     grpc = sub.add_parser("grpc", help="gRPC setup and diagnostics.")
     grpc_sub = grpc.add_subparsers(dest="grpc_cmd", required=True)
 
@@ -358,6 +380,30 @@ def main(argv: list[str] | None = None) -> int:
                 _print_json({"events": list(stream_client.sse_events(max_events=args.max_events))})
             return 0
 
+        if args.command == "stream" and args.stream_cmd == "consensus-pulse":
+            cfg = _sdk_cfg_from_args(args, unified_stream_url=args.stream_url)
+            with UnifiedStreamClient(cfg) as stream_client:
+                _print_json(stream_client.consensus_pulse())
+            return 0
+
+        if args.command == "stream" and args.stream_cmd == "all-mids":
+            cfg = _sdk_cfg_from_args(args, unified_stream_url=args.stream_url)
+            with UnifiedStreamClient(cfg) as stream_client:
+                _print_json(stream_client.all_mids(dex=args.dex))
+            return 0
+
+        if args.command == "stream" and args.stream_cmd == "l2-book":
+            cfg = _sdk_cfg_from_args(args, unified_stream_url=args.stream_url)
+            with UnifiedStreamClient(cfg) as stream_client:
+                _print_json(stream_client.l2_book(args.coin, dex=args.dex, depth=args.depth))
+            return 0
+
+        if args.command == "stream" and args.stream_cmd == "asset-contexts":
+            cfg = _sdk_cfg_from_args(args, unified_stream_url=args.stream_url)
+            with UnifiedStreamClient(cfg) as stream_client:
+                _print_json(stream_client.asset_contexts(coin=args.coin, dex=args.dex))
+            return 0
+
         if args.command == "grpc" and args.grpc_cmd == "health":
             grpc_client = GrpcClient(_grpc_cfg_from_args(args))
             _print_json(grpc_client.health_check(service=args.service))

hypercore_sdk/config.py

@@ -17,8 +17,12 @@ class SDKConfig:
     ws_url: str = os.getenv("HYPER_WS_URL", "wss://disk.grpc.aleatoric.systems/")
     info_url: str = os.getenv("HYPER_INFO_URL", "https://api.hyperliquid.xyz/info")
     unified_stream_url: str = os.getenv("HYPER_UNIFIED_STREAM_URL", "https://unified.grpc.aleatoric.systems")
+    status_url: str = os.getenv("HYPER_STATUS_URL", "http://127.0.0.1:8090")
     grpc_target: str = os.getenv("HYPER_GRPC_TARGET", "hl.grpc.aleatoric.systems:443")
     api_key: str | None = os.getenv("HYPER_API_KEY")
+    unified_stream_api_key: str | None = os.getenv("UNIFIED_STREAM_KEY") or os.getenv("HYPER_UNIFIED_STREAM_API_KEY")
+    grpc_api_key: str | None = os.getenv("ALEATORIC_GRPC_KEY") or os.getenv("HYPER_GRPC_API_KEY")
+    status_token: str | None = os.getenv("HYPER_STATUS_TOKEN")
     timeout_s: float = float(os.getenv("HYPER_TIMEOUT_S", "10"))
     verify_tls: bool = _env_bool("HYPER_VERIFY_TLS", True)
     grpc_tls: bool = _env_bool("HYPER_GRPC_TLS", True)