da2-mcp-socket 0.2.0__py3-none-any.whl

mcp_socket/server.py

@@ -0,0 +1,559 @@
+"""
+Copyright (c) 2026 Danny, DA2 Studio (https://da2.35g.tw)
+Socket MCP Server - Main server implementation.
+
+Provides tools for AI assistants to communicate via TCP/IP sockets
+including connection management, data transmission, and status monitoring.
+"""
+
+import json
+import logging
+import os
+import sys
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+from typing import Any, Optional
+
+from dotenv import load_dotenv
+from mcp.server.fastmcp import FastMCP
+
+# Support both direct execution and module import
+try:
+    from .socket_manager import SocketManager
+except ImportError:
+    from pathlib import Path
+    sys.path.insert(0, str(Path(__file__).parent))
+    from socket_manager import SocketManager
+
+
+# Load environment variables from .env file
+env_path = os.path.join(os.getcwd(), '.env')
+if os.path.exists(env_path):
+    load_dotenv(env_path)
+else:
+    load_dotenv()
+
+# Configure logging
+LOG_LEVEL = os.getenv("LOG_LEVEL", "INFO").upper()
+logging.basicConfig(
+    level=getattr(logging, LOG_LEVEL, logging.INFO),
+    format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+    datefmt="%Y-%m-%d %H:%M:%S",
+    stream=sys.stderr
+)
+logger = logging.getLogger("mcp-socket")
+
+# Default settings from environment
+DEFAULT_TIMEOUT = float(os.getenv("DEFAULT_TIMEOUT", "10.0"))
+DEFAULT_READ_TIMEOUT = float(os.getenv("DEFAULT_READ_TIMEOUT", "5.0"))
+DEFAULT_BUFFER_SIZE = int(os.getenv("DEFAULT_BUFFER_SIZE", "4096"))
+
+
+# Global socket manager instance
+_socket_manager: Optional[SocketManager] = None
+
+
+def get_socket_manager() -> SocketManager:
+    """Get or create the global socket manager instance."""
+    global _socket_manager
+    if _socket_manager is None:
+        _socket_manager = SocketManager()
+    return _socket_manager
+
+
+@dataclass
+class AppContext:
+    """Application context with socket manager."""
+    manager: SocketManager
+
+
+@asynccontextmanager
+async def app_lifespan(server: FastMCP) -> AsyncIterator[AppContext]:
+    """Manage application lifecycle with socket manager."""
+    logger.info("Starting Socket MCP Server...")
+    manager = get_socket_manager()
+    logger.info(f"Default settings: timeout={DEFAULT_TIMEOUT}s, read_timeout={DEFAULT_READ_TIMEOUT}s, buffer_size={DEFAULT_BUFFER_SIZE}")
+    try:
+        yield AppContext(manager=manager)
+    finally:
+        logger.info("Shutting down Socket MCP Server...")
+        result = manager.disconnect_all()
+        if result.get("count", 0) > 0:
+            logger.info(f"Closed {result['count']} connections: {result['closed_connections']}")
+
+
+# Create MCP Server
+mcp = FastMCP(
+    "Socket MCP Server",
+    lifespan=app_lifespan,
+    debug=True
+)
+
+
+def _format_result(data: Any) -> str:
+    """Format data as JSON string for MCP response."""
+    return json.dumps(data, ensure_ascii=False, indent=2, default=str)
+
+
+# ==================== Connection Management ====================
+
+@mcp.tool()
+def connect(
+    host: str,
+    port: int,
+    timeout: Optional[float] = None,
+    read_timeout: Optional[float] = None,
+    buffer_size: Optional[int] = None
+) -> str:
+    """建立 TCP 連線到指定的主機和埠號。
+
+    連線成功後會返回 connection_id，用於後續操作。一個 MCP Server 可以同時維護多個連線。
+
+    Args:
+        host: 目標主機（IP 位址或主機名稱）
+        port: 目標埠號（1-65535）
+        timeout: 連線超時秒數（預設 10.0）
+        read_timeout: 讀取超時秒數（預設 5.0）
+        buffer_size: 接收緩衝區大小（預設 4096）
+
+    Returns:
+        JSON 格式的執行結果，包含 connection_id
+
+    Examples:
+        - connect("192.168.1.100", 8080)
+        - connect("localhost", 80)
+        - connect("example.com", 443, timeout=5.0)
+    """
+    logger.info(f"Connecting to {host}:{port}")
+    manager = get_socket_manager()
+    result = manager.connect(
+        host=host,
+        port=port,
+        timeout=timeout or DEFAULT_TIMEOUT,
+        read_timeout=read_timeout or DEFAULT_READ_TIMEOUT,
+        buffer_size=buffer_size or DEFAULT_BUFFER_SIZE
+    )
+    if result.get("success"):
+        logger.info(f"Connected: {result.get('connection_id')}")
+    else:
+        logger.warning(f"Connection failed: {result.get('error')}")
+    return _format_result(result)
+
+
+@mcp.tool()
+def disconnect(connection_id: str) -> str:
+    """關閉指定的 TCP 連線。
+
+    關閉連線後會釋放資源，並顯示傳輸統計資訊。
+
+    Args:
+        connection_id: 要關閉的連線 ID（由 connect 返回）
+
+    Returns:
+        JSON 格式的執行結果，包含傳輸統計
+
+    Examples:
+        - disconnect("192.168.1.100:8080_abc12345")
+    """
+    logger.info(f"Disconnecting: {connection_id}")
+    manager = get_socket_manager()
+    result = manager.disconnect(connection_id)
+    return _format_result(result)
+
+
+@mcp.tool()
+def get_connection_status(connection_id: Optional[str] = None) -> str:
+    """查詢連線狀態。
+
+    可以查詢特定連線或所有已建立連線的狀態。
+
+    Args:
+        connection_id: 連線 ID（選填，不指定則列出所有連線）
+
+    Returns:
+        JSON 格式的連線狀態資訊
+
+    Examples:
+        - get_connection_status()  # 列出所有連線
+        - get_connection_status("192.168.1.100:8080_abc12345")  # 查詢特定連線
+    """
+    manager = get_socket_manager()
+    result = manager.get_connection_status(connection_id)
+    return _format_result(result)
+
+
+# ==================== Data Transmission ====================
+
+@mcp.tool()
+def send_data(
+    connection_id: str,
+    data: str,
+    encoding: str = "utf-8",
+    as_hex: bool = False
+) -> str:
+    """通過 Socket 連線發送資料。
+
+    可以發送文字或十六進位資料。
+
+    Args:
+        connection_id: 連線 ID
+        data: 要發送的資料（文字或 Hex 字串）
+        encoding: 文字編碼（預設 utf-8）
+        as_hex: 是否將 data 解析為 Hex 字串（如 \"48454C4C4F\" 或 \"48 45 4C 4C 4F\"）
+
+    Returns:
+        JSON 格式的執行結果，包含發送的位元組數
+
+    Examples:
+        - send_data("conn_id", "Hello\\r\\n")
+        - send_data("conn_id", "GET / HTTP/1.1\\r\\nHost: example.com\\r\\n\\r\\n")
+        - send_data("conn_id", "48454C4C4F", as_hex=True)
+    """
+    logger.debug(f"Sending to {connection_id}: {data[:50]}{'...' if len(data) > 50 else ''}")
+    manager = get_socket_manager()
+    result = manager.send_data(connection_id=connection_id, data=data, encoding=encoding, as_hex=as_hex)
+    if result.get("success"):
+        logger.debug(f"Sent {result.get('bytes_sent')} bytes")
+    return _format_result(result)
+
+
+@mcp.tool()
+def receive_data(
+    connection_id: str,
+    size: Optional[int] = None,
+    timeout: Optional[float] = None,
+    as_hex: bool = False
+) -> str:
+    """從 Socket 連線接收資料。
+
+    接收指定數量的位元組，或直到超時。
+
+    Args:
+        connection_id: 連線 ID
+        size: 最大接收位元組數（預設使用 buffer_size）
+        timeout: 接收超時秒數（選填，預設使用連線的設定）
+        as_hex: 只返回 Hex 格式（預設同時返回文字和 Hex）
+
+    Returns:
+        JSON 格式的接收結果，包含資料內容
+
+    Examples:
+        - receive_data("conn_id")
+        - receive_data("conn_id", size=1024, timeout=10.0)
+    """
+    manager = get_socket_manager()
+    result = manager.receive_data(connection_id=connection_id, size=size, timeout=timeout, as_hex=as_hex)
+    if result.get("success"):
+        logger.debug(f"Received {result.get('bytes_received')} bytes")
+    return _format_result(result)
+
+
+@mcp.tool()
+def receive_line(
+    connection_id: str,
+    timeout: Optional[float] = None,
+    encoding: str = "utf-8"
+) -> str:
+    """從 Socket 連線接收一行（直到換行符號）。
+
+    適合接收以換行結尾的文字訊息。
+
+    Args:
+        connection_id: 連線 ID
+        timeout: 接收超時秒數（選填）
+        encoding: 文字編碼（預設 utf-8）
+
+    Returns:
+        JSON 格式的接收結果，包含接收的行
+
+    Examples:
+        - receive_line("conn_id")
+        - receive_line("conn_id", timeout=5.0)
+    """
+    manager = get_socket_manager()
+    result = manager.receive_line(connection_id=connection_id, timeout=timeout, encoding=encoding)
+    return _format_result(result)
+
+
+@mcp.tool()
+def receive_until(
+    connection_id: str,
+    terminator: str = "\n",
+    size: int = 4096,
+    timeout: Optional[float] = None
+) -> str:
+    """接收資料直到遇到指定的結束符號。
+
+    Args:
+        connection_id: 連線 ID
+        terminator: 結束符號（預設換行 \\n）
+        size: 最大接收位元組數（預設 4096）
+        timeout: 接收超時秒數（選填）
+
+    Returns:
+        JSON 格式的接收結果
+
+    Examples:
+        - receive_until("conn_id", terminator="\\r\\n")
+        - receive_until("conn_id", terminator=">", timeout=10.0)
+    """
+    manager = get_socket_manager()
+    result = manager.receive_until(connection_id=connection_id, terminator=terminator, size=size, timeout=timeout)
+    return _format_result(result)
+
+
+# ==================== Protocol Management ====================
+
+@mcp.tool()
+def set_protocol(
+    connection_id: str,
+    mode: str = "raw",
+    start_delimiter: Optional[str] = None,
+    end_delimiter: Optional[str] = None,
+    start_delimiter_hex: Optional[str] = None,
+    end_delimiter_hex: Optional[str] = None,
+    include_delimiters: bool = False
+) -> str:
+    """設定連線的接收協議（封包格式）。
+
+    配置資料應該如何被接收和解析。
+
+    Args:
+        connection_id: 連線 ID
+        mode: 接收模式
+              - raw: 原始模式，直接接收資料
+              - line: 行模式，以換行符號 (\\n) 為結尾
+              - packet: 封包模式，使用自訂的起始/結束符號解析資料流
+        start_delimiter: 封包起始符號（文字格式）
+        end_delimiter: 封包結束符號（文字格式）
+        start_delimiter_hex: 起始符號（Hex 格式，如 "0A"）
+        end_delimiter_hex: 結束符號（Hex 格式，如 "0D0A"）
+        include_delimiters: 是否在接收的資料中包含分隔符號
+
+    Returns:
+        JSON 格式的協議設定結果
+
+    Examples:
+        - set_protocol("conn_id", mode="line")
+        - set_protocol("conn_id", mode="packet", end_delimiter_hex="0D0A")
+        - set_protocol("conn_id", mode="packet", start_delimiter_hex="0A", end_delimiter_hex="0D0A")
+    """
+    manager = get_socket_manager()
+    result = manager.set_protocol(
+        connection_id=connection_id,
+        mode=mode,
+        start_delimiter=start_delimiter,
+        end_delimiter=end_delimiter,
+        start_delimiter_hex=start_delimiter_hex,
+        end_delimiter_hex=end_delimiter_hex,
+        include_delimiters=include_delimiters
+    )
+    if result.get("success"):
+        logger.info(f"Set protocol for {connection_id}: mode={mode}")
+    return _format_result(result)
+
+
+@mcp.tool()
+def receive_packet(
+    connection_id: str,
+    timeout: Optional[float] = None,
+    max_size: int = 4096
+) -> str:
+    """依照設定的協議接收完整封包。
+
+    使用 set_protocol 設定的起始/結束符號解析資料流。
+    - packet 模式：等待 start_delimiter 和 end_delimiter 之間的完整資料
+    - line 模式：等同於 receive_line
+    - raw 模式：等同於 receive_data
+
+    Args:
+        connection_id: 連線 ID
+        timeout: 接收超時秒數（選填）
+        max_size: 最大封包大小（預設 4096）
+
+    Returns:
+        JSON 格式的封包資料，包含 payload_hex 和 payload_text
+
+    Examples:
+        - receive_packet("conn_id")
+        - receive_packet("conn_id", timeout=10.0)
+    """
+    manager = get_socket_manager()
+    result = manager.receive_packet(
+        connection_id=connection_id,
+        timeout=timeout,
+        max_size=max_size
+    )
+    return _format_result(result)
+
+
+@mcp.tool()
+def get_protocol(connection_id: str) -> str:
+    """查詢連線的當前接收協議設定。
+
+    Args:
+        connection_id: 連線 ID
+
+    Returns:
+        JSON 格式的協議設定資訊
+
+    Examples:
+        - get_protocol("conn_id")
+    """
+    manager = get_socket_manager()
+    result = manager.get_protocol(connection_id)
+    return _format_result(result)
+
+
+# ==================== Background Listener ====================
+
+@mcp.tool()
+def start_listening(connection_id: str) -> str:
+    """啟動背景封包監聽器。
+
+    開始在背景執行緒中持續接收資料並解析封包，解析後的封包會存入 buffer。
+    使用 get_packets 取得累積的封包。
+
+    Args:
+        connection_id: 連線 ID
+
+    Returns:
+        JSON 格式的執行結果
+
+    Examples:
+        - start_listening("conn_id")
+    """
+    logger.info(f"Starting listener for {connection_id}")
+    manager = get_socket_manager()
+    result = manager.start_listening(connection_id)
+    return _format_result(result)
+
+
+@mcp.tool()
+def stop_listening(connection_id: str) -> str:
+    """停止背景封包監聽器。
+
+    Args:
+        connection_id: 連線 ID
+
+    Returns:
+        JSON 格式的執行結果
+
+    Examples:
+        - stop_listening("conn_id")
+    """
+    logger.info(f"Stopping listener for {connection_id}")
+    manager = get_socket_manager()
+    result = manager.stop_listening(connection_id)
+    return _format_result(result)
+
+
+@mcp.tool()
+def get_packets(connection_id: str, clear: bool = True) -> str:
+    """取得所有累積的封包。
+
+    返回背景監聽器收到的所有封包陣列，預設會清空 buffer。
+
+    Args:
+        connection_id: 連線 ID
+        clear: 取得後是否清空 buffer（預設 True）
+
+    Returns:
+        JSON 格式的封包陣列
+
+    Examples:
+        - get_packets("conn_id")
+        - get_packets("conn_id", clear=False)
+    """
+    manager = get_socket_manager()
+    result = manager.get_packets(connection_id, clear=clear)
+    if result.get("success"):
+        logger.info(f"Got {result.get('count', 0)} packets from {connection_id}")
+    return _format_result(result)
+
+
+@mcp.tool()
+def get_buffer_status(connection_id: str) -> str:
+    """查詢 buffer 狀態。
+
+    返回目前 buffer 中的封包數量、最大容量、溢出次數等資訊。
+
+    Args:
+        connection_id: 連線 ID
+
+    Returns:
+        JSON 格式的 buffer 狀態
+
+    Examples:
+        - get_buffer_status("conn_id")
+    """
+    manager = get_socket_manager()
+    result = manager.get_buffer_status(connection_id)
+    return _format_result(result)
+
+
+# ==================== Server Info ====================
+
+@mcp.tool()
+def get_server_info() -> str:
+    """取得 MCP Server 的資訊。
+
+    返回伺服器版本、支援的功能和預設設定。
+
+    Returns:
+        JSON 格式的伺服器資訊
+    """
+    manager = get_socket_manager()
+    status = manager.get_connection_status()
+    
+    return _format_result({
+        "server_name": "Socket MCP Server",
+        "version": "0.2.0",
+        "features": {
+            "connection_management": ["connect", "disconnect", "status"],
+            "data_transmission": ["send_data", "receive_data", "receive_line", "receive_until"],
+            "protocol_management": ["set_protocol", "receive_packet", "get_protocol"],
+            "background_listener": ["start_listening", "stop_listening", "get_packets", "get_buffer_status"],
+        },
+        "default_settings": {
+            "timeout": DEFAULT_TIMEOUT,
+            "read_timeout": DEFAULT_READ_TIMEOUT,
+            "buffer_size": DEFAULT_BUFFER_SIZE
+        },
+        "protocol_modes": ["raw", "line", "packet"],
+        "active_connections": status.get("count", 0)
+    })
+
+
+# ==================== Entry Point ====================
+
+def main():
+    """Entry point for the MCP server."""
+    import argparse
+
+    parser = argparse.ArgumentParser(description="Socket MCP Server")
+    parser.add_argument("--http", action="store_true", help="Run in HTTP mode (default: stdio mode)")
+    parser.add_argument("--port", type=int, default=8000, help="Port for HTTP mode (default: 8000)")
+    parser.add_argument("--host", type=str, default="0.0.0.0", help="Host for HTTP mode (default: 0.0.0.0)")
+    args = parser.parse_args()
+
+    logger.info("=" * 50)
+    logger.info("Socket MCP Server v0.1.0")
+    logger.info("=" * 50)
+    logger.info(f"Log level: {LOG_LEVEL}")
+
+    if args.http:
+        mcp.settings.host = args.host
+        mcp.settings.port = args.port
+        logger.info(f"Starting HTTP mode on http://localhost:{args.port}/mcp")
+        logger.info("Use MCP Inspector to connect: npx @modelcontextprotocol/inspector")
+        mcp.run(transport="streamable-http")
+    else:
+        logger.info("Starting stdio mode (for Claude Desktop, Cursor, etc.)")
+        logger.info("Waiting for MCP client connection...")
+        mcp.run()
+
+
+if __name__ == "__main__":
+    main()