a2c-smcp 0.1.1rc0__tar.gz

a2c_smcp-0.1.1rc0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 A2C-SMCP
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

a2c_smcp-0.1.1rc0/PKG-INFO

@@ -0,0 +1,43 @@
+Metadata-Version: 2.4
+Name: a2c-smcp
+Version: 0.1.1rc0
+Summary: The official Python Computer Client SDK for A2C-SMCP
+License: MIT
+License-File: LICENSE
+Author: JQQ
+Author-email: jqq1716@gmail.com
+Requires-Python: >=3.11,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Provides-Extra: cli
+Provides-Extra: dev
+Provides-Extra: test
+Requires-Dist: aiohttp (>=3.12.15,<4.0.0) ; extra == "test"
+Requires-Dist: inline-snapshot (>=0.27.2,<0.28.0) ; extra == "test"
+Requires-Dist: mcp (==1.15.0)
+Requires-Dist: mypy (>=1.17.1,<2.0.0) ; extra == "dev"
+Requires-Dist: poethepoet (>=0.37.0,<0.38.0) ; extra == "dev"
+Requires-Dist: polyfactory (>=2.22.2,<3.0.0) ; extra == "test"
+Requires-Dist: prompt-toolkit (>=3.0.52,<4.0.0) ; extra == "cli"
+Requires-Dist: pydantic (>=2.11.7,<3.0.0)
+Requires-Dist: pytest (>=8.4.1,<9.0.0) ; extra == "dev"
+Requires-Dist: pytest-asyncio (>=1.1.0,<2.0.0) ; extra == "test"
+Requires-Dist: pytest-cov (>=6.2.1,<7.0.0) ; extra == "test"
+Requires-Dist: pytest-dotenv (>=0.5.2,<0.6.0) ; extra == "test"
+Requires-Dist: pytest-mock (>=3.14.1,<4.0.0) ; extra == "test"
+Requires-Dist: python-socketio (>=5.13.0,<6.0.0)
+Requires-Dist: rich (>=14.1.0,<15.0.0) ; extra == "cli"
+Requires-Dist: ruff (>=0.12.9,<0.13.0) ; extra == "dev"
+Requires-Dist: transitions (>=0.9.3,<0.10.0)
+Requires-Dist: typer (>=0.17.4,<1.0.0) ; extra == "cli"
+Requires-Dist: tzlocal (>=5.0.0,<6.0.0)
+Requires-Dist: vrl-python (>=0.1.0,<0.2.0)
+Description-Content-Type: text/markdown
+
+# python-sdk
+The official Python Client SDK for A2C-SMCP
+

a2c_smcp-0.1.1rc0/README.md

@@ -0,0 +1,2 @@
+# python-sdk
+The official Python Client SDK for A2C-SMCP

a2c_smcp-0.1.1rc0/a2c_smcp/__init__.py

@@ -0,0 +1,7 @@
+# -*- coding: utf-8 -*-
+# filename: __init__.py.py
+# @Time    : 2025/9/28 15:33
+# @Author  : JQQ
+# @Email   : jqq1716@gmail.com
+# @Software: PyCharm
+__version__: str = "0.1.1-rc0"

a2c_smcp-0.1.1rc0/a2c_smcp/agent/__init__.py

@@ -0,0 +1,56 @@
+# -*- coding: utf-8 -*-
+# filename: __init__.py
+# @Time    : 2025/9/30 13:56
+# @Author  : JQQ
+# @Email   : jqq1716@gmail.com
+# @Software: PyCharm
+
+"""
+A2C-SMCP Agent模块
+A2C-SMCP Agent module
+
+提供Agent端的SMCP协议客户端实现，包括同步和异步两种模式
+Provides Agent-side SMCP protocol client implementation, including both synchronous and asynchronous modes
+"""
+
+from a2c_smcp.agent.auth import AgentAuthProvider, DefaultAgentAuthProvider
+from a2c_smcp.agent.base import BaseAgentClient
+from a2c_smcp.agent.client import AsyncSMCPAgentClient
+from a2c_smcp.agent.sync_client import SMCPAgentClient
+from a2c_smcp.agent.types import (
+    AgentConfig,
+    AgentEventHandler,
+    AgentID,
+    AgentIDGetter,
+    AsyncAgentEventHandler,
+    AsyncAgentIDGetter,
+    AsyncToolCallCallback,
+    ComputerID,
+    RequestID,
+    ToolCallCallback,
+    ToolCallContext,
+)
+
+__all__ = [
+    # 认证相关 / Authentication related
+    "AgentAuthProvider",
+    "DefaultAgentAuthProvider",
+
+    # 客户端实现 / Client implementations
+    "BaseAgentClient",
+    "SMCPAgentClient",
+    "AsyncSMCPAgentClient",
+
+    # 类型定义 / Type definitions
+    "AgentConfig",
+    "AgentEventHandler",
+    "AsyncAgentEventHandler",
+    "AgentID",
+    "ComputerID",
+    "RequestID",
+    "ToolCallContext",
+    "ToolCallCallback",
+    "AsyncToolCallCallback",
+    "AgentIDGetter",
+    "AsyncAgentIDGetter",
+]

a2c_smcp-0.1.1rc0/a2c_smcp/agent/auth.py

@@ -0,0 +1,140 @@
+"""
+* 文件名: auth
+* 作者: JQQ
+* 创建日期: 2025/9/30
+* 最后修改日期: 2025/9/30
+* 版权: 2023 JQQ. All rights reserved.
+* 依赖: None
+* 描述: Agent端认证接口抽象定义 / Agent-side authentication interface abstract definition
+"""
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from a2c_smcp.agent.types import AgentConfig
+
+
+class AgentAuthProvider(ABC):
+    """
+    Agent认证提供者抽象基类，用于处理Agent连接的认证逻辑
+    Abstract base class for Agent authentication providers, handles Agent connection authentication logic
+    """
+
+    @abstractmethod
+    def get_agent_id(self) -> str:
+        """
+        获取agent_id，由用户实现具体逻辑
+        Get agent_id, implemented by user with specific logic
+
+        Returns:
+            str: agent_id
+        """
+        pass
+
+    @abstractmethod
+    def get_connection_auth(self) -> dict[str, Any] | None:
+        """
+        获取连接认证信息，用于Socket.IO连接时的auth参数
+        Get connection authentication info, used for Socket.IO connection auth parameter
+
+        Returns:
+            dict[str, Any] | None: 认证信息字典 / Authentication info dictionary
+        """
+        pass
+
+    @abstractmethod
+    def get_connection_headers(self) -> dict[str, str]:
+        """
+        获取连接请求头，用于Socket.IO连接时的headers参数
+        Get connection headers, used for Socket.IO connection headers parameter
+
+        Returns:
+            dict[str, str]: 请求头字典 / Headers dictionary
+        """
+        pass
+
+    @abstractmethod
+    def get_agent_config(self) -> AgentConfig:
+        """
+        获取Agent配置信息
+        Get Agent configuration information
+
+        Returns:
+            AgentConfig: Agent配置 / Agent configuration
+        """
+        pass
+
+
+class DefaultAgentAuthProvider(AgentAuthProvider):
+    """
+    默认Agent认证提供者，提供基础的认证逻辑实现
+    Default Agent authentication provider, provides basic authentication logic implementation
+    """
+
+    def __init__(
+        self,
+        agent_id: str,
+        office_id: str,
+        api_key: str | None = None,
+        api_key_header: str = "x-api-key",
+        extra_headers: dict[str, str] | None = None,
+        auth_data: dict[str, Any] | None = None,
+    ) -> None:
+        """
+        初始化默认Agent认证提供者
+        Initialize default Agent authentication provider
+
+        Args:
+            agent_id (str): Agent唯一标识 / Agent unique identifier
+            office_id (str): 办公室ID / Office ID
+            api_key (str | None): API密钥 / API key
+            api_key_header (str): API密钥请求头名称 / API key header name
+            extra_headers (dict[str, str] | None): 额外请求头 / Extra headers
+            auth_data (dict[str, Any] | None): 额外认证数据 / Extra auth data
+        """
+        self._agent_id = agent_id
+        self._office_id = office_id
+        self._api_key = api_key
+        self._api_key_header = api_key_header
+        self._extra_headers = extra_headers or {}
+        self._auth_data = auth_data or {}
+
+    def get_agent_id(self) -> str:
+        """
+        获取Agent ID
+        Get Agent ID
+        """
+        return self._agent_id
+
+    def get_connection_auth(self) -> dict[str, Any] | None:
+        """
+        获取连接认证信息
+        Get connection authentication info
+        """
+        if not self._auth_data:
+            return None
+        return self._auth_data.copy()
+
+    def get_connection_headers(self) -> dict[str, str]:
+        """
+        获取连接请求头
+        Get connection headers
+        """
+        headers = self._extra_headers.copy()
+
+        # 添加API密钥到请求头
+        # Add API key to headers
+        if self._api_key:
+            headers[self._api_key_header] = self._api_key
+
+        return headers
+
+    def get_agent_config(self) -> AgentConfig:
+        """
+        获取Agent配置信息
+        Get Agent configuration information
+        """
+        return AgentConfig(
+            agent_id=self._agent_id,
+            office_id=self._office_id,
+        )

a2c_smcp-0.1.1rc0/a2c_smcp/agent/base.py

@@ -0,0 +1,288 @@
+"""
+* 文件名: base
+* 作者: JQQ
+* 创建日期: 2025/9/30
+* 最后修改日期: 2025/9/30
+* 版权: 2023 JQQ. All rights reserved.
+* 依赖: socketio, loguru
+* 描述: Agent基础客户端抽象类 / Agent base client abstract class
+"""
+
+import uuid
+from abc import ABC, abstractmethod
+from typing import Any
+
+from mcp.types import CallToolResult, TextContent
+
+from a2c_smcp.agent.auth import AgentAuthProvider
+from a2c_smcp.agent.types import AgentEventHandler
+from a2c_smcp.smcp import (
+    EnterOfficeNotification,
+    GetDeskTopReq,
+    GetDeskTopRet,
+    GetToolsReq,
+    GetToolsRet,
+    LeaveOfficeNotification,
+    ToolCallReq,
+    UpdateMCPConfigNotification,
+)
+from a2c_smcp.utils.logger import logger
+
+
+class BaseAgentClient(ABC):
+    """
+    Agent基础客户端抽象类，提供通用的SMCP协议处理逻辑
+    Agent base client abstract class, provides common SMCP protocol handling logic
+    """
+
+    def __init__(
+        self,
+        auth_provider: AgentAuthProvider,
+        event_handler: AgentEventHandler | None = None,
+    ) -> None:
+        """
+        初始化基础Agent客户端
+        Initialize base Agent client
+
+        Args:
+            auth_provider (AgentAuthProvider): 认证提供者 / Authentication provider
+            event_handler (AgentEventHandler | None): 事件处理器 / Event handler
+        """
+        self.auth_provider = auth_provider
+        self.event_handler = event_handler
+
+    @abstractmethod
+    def emit(self, event: str, data: Any = None, namespace: str | None = None, callback: Any = None) -> Any:
+        """
+        发送事件的抽象方法
+        Abstract method for sending events
+        """
+        pass
+
+    @abstractmethod
+    def call(self, event: str, data: Any = None, namespace: str | None = None, timeout: int = 60) -> Any:
+        """
+        调用事件并等待响应的抽象方法
+        Abstract method for calling events and waiting for response
+        """
+        pass
+
+    def validate_emit_event(self, event: str) -> None:
+        """
+        验证发送事件的合法性
+        Validate the legality of emitted events
+
+        Args:
+            event (str): 事件名称 / Event name
+
+        Raises:
+            ValueError: 当事件不合法时 / When event is invalid
+        """
+        if event.startswith("notify:"):
+            raise ValueError("AgentClient不允许使用notify:*事件 / AgentClient is not allowed to use notify:* events")
+        if event.startswith("agent:"):
+            raise ValueError("AgentClient不允许发起agent:*事件 / AgentClient is not allowed to initiate agent:* events")
+
+    def create_tool_call_request(self, computer: str, tool_name: str, params: dict, timeout: int) -> ToolCallReq:
+        """
+        创建工具调用请求对象
+        Create tool call request object
+
+        Args:
+            computer (str): 目标计算机ID / Target computer ID
+            tool_name (str): 工具名称 / Tool name
+            params (dict): 调用参数 / Call parameters
+            timeout (int): 超时时间 / Timeout duration
+
+        Returns:
+            ToolCallReq: 工具调用请求 / Tool call request
+        """
+        agent_config = self.auth_provider.get_agent_config()
+        return ToolCallReq(
+            computer=computer,
+            tool_name=tool_name,
+            params=params,
+            robot_id=agent_config["agent_id"],
+            req_id=uuid.uuid4().hex,
+            timeout=timeout,
+        )
+
+    def create_get_tools_request(self, computer: str) -> GetToolsReq:
+        """
+        创建获取工具请求对象
+        Create get tools request object
+
+        Args:
+            computer (str): 目标计算机ID / Target computer ID
+
+        Returns:
+            GetToolsReq: 获取工具请求 / Get tools request
+        """
+        agent_config = self.auth_provider.get_agent_config()
+        return GetToolsReq(
+            computer=computer,
+            robot_id=agent_config["agent_id"],
+            req_id=uuid.uuid4().hex,
+        )
+
+    def create_get_desktop_request(self, computer: str, *, size: int | None = None, window: str | None = None) -> GetDeskTopReq:
+        """
+        创建获取桌面请求对象
+        Create get desktop request object
+
+        Args:
+            computer (str): 目标计算机ID / Target computer ID
+            size (int | None): 桌面窗口数量上限 / Max number of windows
+            window (str | None): 指定窗口URI / Specific window URI
+
+        Returns:
+            GetDeskTopReq: 获取桌面请求 / Get desktop request
+        """
+        agent_config = self.auth_provider.get_agent_config()
+        req: GetDeskTopReq = {
+            "computer": computer,
+            "robot_id": agent_config["agent_id"],
+            "req_id": uuid.uuid4().hex,
+        }
+        if size is not None:
+            req["desktop_size"] = size
+        if window is not None:
+            req["window"] = window
+        return req
+
+    def process_desktop_response(self, response: GetDeskTopRet, computer: str) -> None:
+        """
+        处理桌面响应（默认仅记录日志；留作后续扩展回调）。
+        Process desktop response (log only by default; placeholder for future callbacks).
+        """
+        try:
+            desktops = response.get("desktops", []) if isinstance(response, dict) else []
+            logger.info(f"Received desktop from computer {computer}, windows={len(desktops)}")
+        except Exception as e:
+            logger.error(f"Error processing desktop response: {e}")
+
+    def handle_tool_call_timeout(self, req_id: str) -> CallToolResult:
+        """
+        处理工具调用超时情况
+        Handle tool call timeout situation
+
+        Args:
+            req_id (str): 请求ID / Request ID
+
+        Returns:
+            CallToolResult: 超时错误结果 / Timeout error result
+        """
+        return CallToolResult(
+            content=[TextContent(text=f"工具调用超时 / Tool call timeout, req_id={req_id}", type="text")],
+            isError=True,
+        )
+
+    def validate_office_data(self, data: EnterOfficeNotification | LeaveOfficeNotification) -> str:
+        """
+        验证办公室数据并返回计算机ID
+        Validate office data and return computer ID
+
+        Args:
+            data: 办公室通知数据 / Office notification data
+
+        Returns:
+            str: 计算机ID / Computer ID
+
+        Raises:
+            AssertionError: 当数据无效时 / When data is invalid
+        """
+        agent_config = self.auth_provider.get_agent_config()
+        assert data["office_id"] == agent_config["office_id"], "无效的办公室ID / Invalid office ID"
+        assert data.get("computer"), "无效的计算机ID / Invalid computer ID"
+        return data["computer"]
+
+    def handle_computer_enter_office(self, data: EnterOfficeNotification) -> None:
+        """
+        处理Computer加入办公室事件
+        Handle Computer enter office event
+
+        Args:
+            data: 加入办公室通知数据 / Enter office notification data
+        """
+        try:
+            computer = self.validate_office_data(data)
+            logger.info(f"Computer {computer} entered office {data['office_id']}")
+
+            # 调用事件处理器
+            # Call event handler
+            if self.event_handler:
+                self.event_handler.on_computer_enter_office(data)
+
+        except Exception as e:
+            logger.error(f"Error handling computer enter office: {e}")
+
+    def handle_computer_leave_office(self, data: LeaveOfficeNotification) -> None:
+        """
+        处理Computer离开办公室事件
+        Handle Computer leave office event
+
+        Args:
+            data: 离开办公室通知数据 / Leave office notification data
+        """
+        try:
+            computer = self.validate_office_data(data)
+            logger.info(f"Computer {computer} left office {data['office_id']}")
+
+            # 调用事件处理器
+            # Call event handler
+            if self.event_handler:
+                self.event_handler.on_computer_leave_office(data)
+
+        except Exception as e:
+            logger.error(f"Error handling computer leave office: {e}")
+
+    def handle_computer_update_config(self, data: UpdateMCPConfigNotification) -> None:
+        """
+        处理Computer更新配置事件
+        Handle Computer update config event
+
+        Args:
+            data: 配置更新通知数据 / Config update notification data
+        """
+        try:
+            computer = data["computer"]
+            logger.info(f"Computer {computer} updated config")
+
+            # 调用事件处理器
+            # Call event handler
+            if self.event_handler:
+                self.event_handler.on_computer_update_config(data)
+
+        except Exception as e:
+            logger.error(f"Error handling computer update config: {e}")
+
+    def process_tools_response(self, response: GetToolsRet, computer: str) -> None:
+        """
+        处理工具响应
+        Process tools response
+
+        Args:
+            response: 工具响应数据 / Tools response data
+            computer: 计算机ID / Computer ID
+        """
+        try:
+            if tools := response.get("tools"):
+                logger.info(f"Received {len(tools)} tools from computer {computer}")
+
+                # 调用事件处理器
+                # Call event handler
+                if self.event_handler:
+                    self.event_handler.on_tools_received(computer, tools)
+
+        except Exception as e:
+            logger.error(f"Error processing tools response: {e}")
+
+    @abstractmethod
+    def register_event_handlers(self) -> None:
+        """
+        注册事件处理器，子类需要实现具体的注册逻辑
+        Register event handlers, subclasses need to implement specific registration logic
+        """
+        # 这个方法需要在子类中实现具体的事件注册逻辑
+        # This method needs to implement specific event registration logic in subclasses
+        pass