# a2c-smcp
The official Rust SDK for A2C-SMCP
---
# A2C-SMCP Rust SDK
A Rust implementation of the A2C-SMCP protocol, providing Agent, Computer, and Server components for building intelligent agent systems with tool execution capabilities.
## 🚀 Quick Start
Add to your `Cargo.toml`:
```toml
[dependencies]
a2c-smcp = { version = "0.1.0", features = ["agent", "computer"] }
```
Or use all features:
```toml
[dependencies]
a2c-smcp = { version = "0.1.0", features = ["full"] }
```
## 📦 Features
- **agent** - Agent client for connecting to SMCP servers and calling tools
- **computer** - Computer client for managing MCP servers and desktop resources
- **server** - Server implementation with Socket.IO support
- **full** - Enables all features
## 📜 协议规范
A2C-SMCP 协议规范已拆分为独立仓库，支持多语言 SDK 开发。
- **协议仓库**: [a2c-smcp-protocol](https://github.com/A2C-SMCP/a2c-smcp-protocol)
- **当前协议版本**: 0.1.2-rc1
开发时参考路径：
- 协议规范：`a2c-smcp-protocol/specification/`
- Python 参考实现：`python-sdk/a2c_smcp/`
## 📋 Project Structure
This is a **real workspace** with a main package that aggregates sub-crates:
```
rust-sdk/
├── src/ # Main package entry point (re-exports based on features)
├── tests/ # Cross-crate integration tests
├── crates/
│ ├── smcp/ # Core protocol types
│ ├── smcp-agent/ # Agent implementation
│ ├── smcp-computer/# Computer implementation
│ ├── smcp-server-core/ # Server core logic
│ └── smcp-server-hyper/ # Hyper adapter for server
└── Cargo.toml # Workspace + main package configuration
```
本仓库目标：使用 Rust 实现 A2C-SMCP 协议，并对齐 `python-sdk` 的能力边界与使用体验。
本 README 给出 Rust SDK 的技术选型与实现路线，并明确当前版本的能力边界。
## 1. 背景与协议轮廓（来自 python-sdk）
Python 参考实现中，A2C-SMCP 的最核心抽象是三大模块：
- **Computer**：管理 MCP Servers、聚合工具列表与桌面资源；并负责接收来自 Agent 的工具调用请求、执行工具并返回结果，同时向 Server 上报更新。
- **Server**：中心信令服务，负责会话管理、转发调用、广播通知。
- **Agent**：业务侧智能体客户端，通过协议事件调用 Computer 的工具。
传输层：`python-sdk` 选择 **Socket.IO** 做实时通信（带 namespace 与 room），并定义了 `SMCP_NAMESPACE = /smcp`。
事件命名规范（来自 `python-sdk/a2c_smcp/smcp.py`）：
- `client:*`：由 Agent 发起、由 Server 转发到特定 Computer 执行（例如 `client:tool_call`、`client:get_tools`、`client:get_desktop`）。
- `server:*`：由 Computer/Agent 发起，Server 负责执行并转换为通知（例如 join/leave office、update desktop/config、cancel tool call）。
- `notify:*`：只由 Server 发出，向 room 广播状态变更（例如 enter/leave office、update config/tool list/desktop）。
Rust 版本以 `smcp.py` 的事件与数据结构为“权威源”，优先保证互通与行为一致，再逐步补齐 Computer/CLI/Desktop 等高级能力。
## 2. Rust 技术选型
### 2.1 异步运行时
- **Tokio**
- 选择理由：
- Rust 网络生态与 Socket.IO/WebSocket/HTTP client-server 基本都以 Tokio 为默认运行时。
- 便于统一 Server 与 Agent/Computer 客户端的并发模型。
### 2.2 Server 端框架：Socket.IO 紧绑定 + HTTP 承载层可插拔
Python 版本最小集成示例是 `FastAPI + python-socketio(ASGI)`。从 SMCP 视角：
- **实时通信层固定使用 Socket.IO**（namespace/room/ack/notify）。
- **消息格式当前只支持 JSON**（`serde_json`）。
- **HTTP 不等于必须提供 REST API**；它主要作为 Socket.IO 的承载监听器，用于握手、升级（WebSocket）、以及 long-polling 回退。
为了保持“开源协议 SDK”依赖最小且方便使用者集成：
- **Socket.IO Server：socketioxide**（紧绑定，不可替换）。
- `socketioxide` 是当前 Rust 生态中唯一成熟的 Socket.IO Server 实现，SDK 直接依赖它。
- 它通过 Tower Layer/Service 模式工作，天然支持与多种 HTTP 框架集成。
- **HTTP 承载层默认：Hyper**（最小依赖/最通用）。
- **HTTP 承载层可替换**：`socketioxide` 可作为 Tower Layer 嵌入任何 Tower 兼容框架（Axum/Salvo/Viz 等），使用者可以在自己的项目中选择框架。
### 2.3 Socket 客户端（Agent/Computer 模块）
Agent/Computer 需要连接 Server，并支持：
- connect with headers/auth
- emit/call（ack）
- on notify events
- room（office_id）管理
Rust 侧采用：
- **tf-rust-socketio（客户端）**
- 注意：`socketioxide` 是纯 Server 端实现，不提供客户端功能。Agent/Computer 作为客户端使用 `tf-rust-socketio` crate（基于 `rust_socketio` 增加了 ACK 响应支持）。
- 支持点（来自 docs.rs）：
- **namespace**：`ClientBuilder::namespace("/smcp")`；但**一个 socket 只能连接一个 namespace**，多 namespace 需要多个 socket。
- **ack + timeout**：`emit_with_ack(event, data, Duration, callback)`，可按每次调用设置超时。
- **reconnect/backoff**：提供开关与参数：
- `reconnect(true)` / `reconnect_on_disconnect(true)`
- `reconnect_delay(min, max)`（最小/最大重连间隔）
- `max_reconnect_attempts(n)`（最大重试次数）
- **headers/auth**：支持 `opening_header(k, v)` 与 `auth(json!)`，可对齐 Python 端的 header api-key 与 auth payload。
- 注意点：
- async 版本需要开启 feature `async`，且文档标注当前 async 实现处于 beta，接口可能变化。
- 需要在正式开发前验证 `tf-rust-socketio` 与 `socketioxide` 的互通性（见 `tests/e2e/`）。
### 2.4 序列化 / 类型校验
Python 版大量使用 TypedDict/Pydantic 做校验。Rust 端遵循“一切从简”原则：优先保证协议载荷能稳定反序列化为结构化数据。
- **serde + serde_json**：作为 wire format 的默认实现（与 Socket.IO JSON payload 最契合），并承担“反序列化即结构校验”的职责。
- **类型建模策略**：
- 协议结构体使用 `#[derive(Serialize, Deserialize)]`
- 事件 payload 尽量用强类型，而不是 `serde_json::Value`
- **类型边界划分**（方案 C）：
- `smcp` crate：只放**协议层公共类型**（事件常量、`AgentCallData`、`ToolCallReq`、`GetToolsReq/Ret`、`EnterOfficeReq` 等跨角色共享的协议结构）
- `smcp-computer` crate：放 Computer 专属配置类型（如 `MCPServerConfig`、`MCPServerStdioConfig` 等）
- `smcp-agent` crate：放 Agent 专属类型（如 `AgentEventHandler`）
说明：工具侧的 `params_schema/return_schema` 在本 SDK 中以 MCP Tools 的 schema 为准，当前仅做透传，不在 SDK 内生成或做额外 schema 校验。
### 2.5 错误处理
- **thiserror**：定义 `SmcpError` 等错误枚举。
- **anyhow**：应用层（CLI/示例）快速聚合错误。
- 错误边界：
- SDK 层对外暴露稳定的 `Result<T, SmcpError>`
- CLI/示例使用 `anyhow::Result<()>` 即可。
### 2.6 日志与可观测性
- **tracing + tracing-subscriber**
- 原因：异步场景的结构化日志更适合排查事件流（尤其是 room 广播、ack 超时、重连）。
### 2.7 CLI（Computer 模块）
Python 版 Computer 侧提供交互式 CLI（添加 server、start/stop、status、socket connect/join、notify update）。
Rust 端采用：
- **clap**：命令行参数解析（只负责 args/subcommands，不负责交互能力）。
- **pexpect 级交互**：使用 **expectrl** 实现“spawn + PTY + expect/send”风格的交互控制；比直接用管道读写的 subprocess 方式更适合做强交互 CLI。
- **颜色与终端能力**：
- 轻量彩色输出：`owo-colors`（或兼容生态的 `anstyle` 体系）
- 终端事件与渲染基础：`crossterm`
-（可选）更强交互体验：
- TUI：`ratatui`（基于 `crossterm`）
- 行编辑/补全：`reedline`/`rustyline`（如需类似 shell 的输入体验）
### 2.8 测试策略
- **单元测试**：协议结构体序列化/反序列化、事件路由与权限校验。
- **集成测试**：起一个内嵌 Server（Socket.IO），用 Agent/Computer 客户端对打，覆盖：
- join office → notify enter_office
- get_tools / tool_call 的转发与 ack
- update_desktop 广播与 Agent 拉取
- **端到端（e2e）**：对齐 python 版的测试思路。
#### 目录与文件组织（真实 Workspace 规范）
> **重要**：本仓库采用**真实 workspace**（同时有 `[workspace]` 和 `[package]` 段）。
> 根目录包 `a2c-smcp` 作为主入口，可以包含 `src/` 和 `tests/` 目录。
- **单元测试（unit tests）**
- 放置位置：各 crate 的 `src/**` 内 `#[cfg(test)] mod tests { ... }`。
- 适用范围：纯函数/结构体方法、序列化/反序列化、错误映射、事件名称与 payload 组装等。
- 组织规范：
- 每个模块自己带测试，避免依赖真实网络/真实进程。
- 使用“表驱动”测试（`cases: Vec<(input, expected)>`）来覆盖边界条件。
- 公共测试工具函数放到 `src/test_utils.rs` 或 `src/test_utils/mod.rs`（仅在 `cfg(test)` 下编译）。
- **集成测试（integration tests）**
- 放置位置：
- 根目录 `tests/`：跨 crate 联合测试（如 Agent + Computer + Server）
- 各 crate 的 `tests/` 目录：单个 crate 的 API 测试 - 文件名按场景：`join_leave.rs`、`tool_call_ack.rs`、`socketio_interop.rs`。
- 文件名按场景：`full_stack.rs`、`agent_computer.rs`、`socketio_interop.rs`。
- 测试函数按行为：`test_full_stack_integration()`。
- 约束建议：
- 网络端口使用 `127.0.0.1:0` 自动分配，避免 CI 冲突。
- 用超时（`tokio::time::timeout`）包裹等待，避免卡死。
- 共享 fixtures 放到 `tests/common/mod.rs`。
- 使用 `skip_if_no_feature!` 宏根据 features 跳过测试。 - 用超时（`tokio::time::timeout`）包裹等待，避免卡死。
- 共享 fixtures 放到 crate 内的 `tests/common/mod.rs`。
- **端到端测试（e2e tests）**
- 放置位置：根目录 `tests/e2e/`（如果需要更慢、更依赖环境的测试）。
- 适用范围：跨进程/跨组件的真实链路（例如启动 Computer 管理 MCP stdio server）。
- 组织规范：
- 依赖外部二进制（如 `npx`、真实 MCP server）要做可跳过策略。
- 产物（临时目录、日志）统一写到 `target/tmp/<test_name>/`。 ```
- 运行方式：`cargo test -p smcp-e2e-tests`
- 组织规范：
- 依赖外部二进制（如 `npx`、真实 MCP server）要做可跳过策略（例如环境变量开关）。
- 产物（临时目录、日志）统一写到 `target/tmp/<test_name>/`。
## 3. 已确定的技术约束（Design Decisions）
### 3.1 传输层：必须 Socket.IO
本 SDK 的实时通信层**固定使用 Socket.IO**（对齐 `python-sdk` 的语义：namespace/room/ack/notify）。不考虑替换为 WebSocket/gRPC 等其它传输。
### 3.2 HTTP 承载层：最小依赖 + 可插拔
Socket.IO 在工程实现上需要一个 HTTP 监听器作为承载（握手、升级、long-polling）。为了保证依赖最小并方便使用者集成：
- 默认使用 **Hyper** 作为承载层（最小依赖/最通用）。
- SDK 设计应将“承载层”抽象为可替换接口/适配层：
- 使用者可以在自己的项目中选择 Axum/Actix/Salvo 等框架，并把请求转发给 Socket.IO handler。
- 本 SDK 不强制绑定任何具体 Web 框架。
### 3.3 消息格式：仅支持 JSON
当前版本**只支持 JSON payload**（`serde_json`），不支持二进制消息与大对象流式传输。后续若要支持图片/资源流，应通过独立通道或资源接口设计，而非在本版本内扩展。
## 4. Rust 端实现路线
路线按“先互通、再补齐”，避免一开始就把 Computer/CLI/Desktop 全部做完。
### 4.1 Milestone 1：协议与类型层（smcp）
- 定义 `SMCP_NAMESPACE` 与全部事件常量（与 `smcp.py` 对齐）
- 定义核心 payload：
- `AgentCallData`、`ToolCallReq`、`GetToolsReq/Ret`
- `EnterOfficeReq`、`LeaveOfficeReq`
- `Update*Notification`、`ListRoomReq/Ret`
- 统一 `req_id` 生成策略（UUID）
### 4.2 Milestone 2：Server 最小实现（转发 + 广播）
- **核心原则：Socket.IO 层紧绑定 socketioxide，HTTP 承载层可插拔**
- Server 核心逻辑依赖 Tokio + `socketioxide` + 协议类型；`socketioxide` 是唯一的 Socket.IO 实现，不可替换。
- `socketioxide` 通过 Tower Layer/Service 模式工作，天然支持与 Axum/Salvo/Hyper 等框架集成。
- 提供一个最小默认承载实现（Hyper），并将其作为“示例/默认 adapter”。使用者可以选择其他 Tower 兼容框架。
- 会话管理：sid ↔ name ↔ role ↔ office_id（类似 python `BaseNamespace`）
- 事件与语义：
- `server:join_office` / `server:leave_office` → 广播 `notify:*`
- `client:get_tools` / `client:get_desktop` / `client:tool_call` → 转发到指定 Computer 并等待 ack
- `server:update_desktop` / `server:update_config` / `server:update_tool_list` → 广播 `notify:update_*`
- 鉴权：先实现 header api-key（对齐 Python `DefaultAuthenticationProvider`），后续再扩展。
- 工程化约束：
- 统一对 ack/转发等待加 timeout，避免请求悬挂。
- handler 内只处理 JSON payload（`serde_json`），不引入二进制分支。
### 4.3 Milestone 3：Agent 客户端最小实现
- connect（headers/auth）
- join_office
- emit_tool_call（带 timeout + cancel）
- 订阅 `notify:*` 并提供回调接口
### 4.4 Milestone 4：Computer 客户端最小实现
- 提供 get_tools、tool_call、get_desktop 的事件处理（被 Server call）
- 支持上报 update_desktop/tool_list/config
## 5. 与 MCP 的关系（对齐 python-sdk）
Python 版在 Agent 侧返回 `mcp.types::CallToolResult` 风格的数据结构，并在 Computer 侧管理多种 MCP Server（stdio/sse/streamable）。
Rust 端先把 SMCP 的“信令与工具调用转发”跑通；MCP Server 管理（stdio/sse）按分层实现：
- `computer::mcp_manager`：进程管理、连接管理
- `computer::tool_registry`：工具聚合与去重（解决 tool name 冲突，可对齐 `ToolMeta.alias` 思路）
- `computer::desktop`：window:// 资源聚合（后续迭代）
---
## 当前实现状态（截至 2025-12-25）
### ✅ 已完成的 Milestone
**Milestone 1：协议与类型层（smcp）** - 100% 完成
- ✅ 定义 `SMCP_NAMESPACE` 与全部事件常量（与 `smcp.py` 对齐）
- ✅ 定义核心 payload 类型（`AgentCallData`、`ToolCallReq/Ret`、`GetToolsReq/Ret` 等）
- ✅ 统一 `req_id` 生成策略（UUID v4 hex 格式）
- ✅ 完整的序列化/反序列化测试覆盖
**Milestone 2：Server 最小实现（转发 + 广播）** - 100% 完成
- ✅ `smcp-server-core`：核心逻辑实现（会话/路由/鉴权）
- ✅ `smcp-server-hyper`：默认 Hyper 承载适配器
- ✅ Socket.IO 层紧绑定 `socketioxide`
- ✅ HTTP 承载层可插拔设计（Tower Layer/Service 模式）
- ✅ 会话管理（sid ↔ name ↔ role ↔ office_id）
- ✅ 事件处理：`join_office`/`leave_office` → 广播 `notify:*`
- ✅ 事件转发：`get_tools`/`get_desktop`/`tool_call` → 转发到指定 Computer 并等待 ack
- ✅ 鉴权：header api-key（`DefaultAuthenticationProvider`）
- ✅ 完整的超时与错误处理
**Milestone 3：Agent 客户端最小实现** - 100% 完成
- ✅ `smcp-agent` crate：完整实现
- ✅ 支持 async 和 sync 两种模式（`AsyncSmcpAgent`、`SyncSmcpAgent`）
- ✅ connect（headers/auth）
- ✅ join_office/leave_office
- ✅ emit_tool_call（带 timeout + cancel）
- ✅ 订阅 `notify:*` 事件并提供回调接口
- ✅ 完整的配置、认证、事件处理系统
- ✅ 基于 `tf-rust-socketio` 的传输层实现
**Milestone 4：Computer 客户端最小实现** - 100% 完成
- ✅ `smcp-computer` crate：完整实现
- ✅ get_tools/tool_call/get_desktop 事件处理
- ✅ update_desktop/tool_list/config 上报
- ✅ Socket.IO 客户端连接与会话管理
### ✅ 额外已完成的功能
**MCP Server 管理** - 90% 完成
- ✅ `mcp_clients/manager`：进程管理与连接管理
- ✅ MCP 客户端实现：HTTP、SSE、Stdio 三种传输方式
- ✅ 工具聚合与去重（`tool_registry`）
- ✅ 配置管理（`MCPServerConfig`，支持 stdio/sse/http）
- ✅ 输入系统：CLI、Environment、Command 三种输入提供者
- ✅ VRL runtime 支持（可选特性）
- ✅ 缓存机制
**Desktop 管理与资源聚合** - 80% 完成
- ✅ `desktop/` 模块：window:// 资源解析与聚合
- ✅ `WindowURI` 解析器（priority/fullscreen/路径）
- ✅ 桌面组织算法（按 priority、fullscreen、history 排序）
- ✅ 窗口详情获取
- ⚠️ 实时订阅更新机制（部分完成）
**CLI 工具** - 85% 完成
- ✅ 基于 `clap` 的命令行参数解析
- ✅ 交互式 shell（基于 `expectrl`）
- ✅ 核心命令：add/remove/list servers, start/stop client, status
- ✅ 配置管理（load/save/show）
- ✅ 工具调用历史记录
- ⚠️ 完整的 PTY 交互控制（进行中）
**测试覆盖** - 95% 完成
- ✅ 341 个测试用例全部通过
- ✅ 单元测试：各 crate 内部的 `#[cfg(test)]` 模块
- ✅ 集成测试：`tests/full_stack.rs`（Agent + Computer + Server）
- ✅ Socket.IO 互通性测试
- ✅ MCP 客户端测试（HTTP/SSE/Stdio）
- ✅ Desktop 组织算法测试
- ✅ CLI 命令测试
- ⚠️ E2E 测试（需要外部依赖，部分跳过）
- ✅ Clippy lint 检查通过（无警告）
- ✅ 代码格式化完成（`cargo fmt`）
**代码统计**
- 总代码量：约 15,000+ 行 Rust 代码
- Crates 结构：5 个核心 crates（`smcp`, `smcp-agent`, `smcp-computer`, `smcp-server-core`, `smcp-server-hyper`）
- 测试覆盖：单元测试 + 集成测试 + E2E 测试
---
## 下一步（2025 Q1）
### 优先级 1：核心功能完善
1. **完善 Desktop 资源订阅与实时更新**
- 实现 `resources/subscribe` 和 `resources/unsubscribe` 的完整流程
- 处理 SSE 长轮询的实时更新
- 优化缓存失效策略
2. **工具调用取消机制**
- 实现 `server:tool_call_cancel` 的完整处理流程
- 支持超时自动取消
- 支持客户端主动取消请求
3. **错误处理与恢复增强**
- 完善 MCP Server 断线重连机制
- 增强错误恢复策略（exponential backoff）
- 添加更详细的错误上下文信息
4. **性能优化**
- 优化工具调用并发处理
- 减少不必要的序列化/反序列化开销
- 优化大量 window:// 资源的组织算法
### 优先级 2：生产就绪
5. **文档完善**
- API 文档（rustdoc）完善
- 使用指南与最佳实践
- 故障排查文档
- 示例代码（examples/）
6. **可观测性增强**
- 结构化日志（tracing）完善
- Metrics 收集（prometheus/client）
- 分布式追踪支持（可选 opentelemetry）
7. **安全性增强**
- Secret 管理（避免硬编码 api-key）
- TLS/SSL 支持
- 输入验证增强
- Rate limiting 机制
### 优先级 3：生态扩展
8. **额外框架适配器（按需）**
- 评估并提供 `server-axum` adapter
- 评估并提供 `server-actix-web` adapter
- 保持核心依赖最小与承载层可替换原则
9. **高级 Desktop 特性**
- 跨进程 window:// 资源共享
- Desktop 快照与恢复
- 窗口状态持久化
10. **部署与运维**
- Docker 镜像构建
- Kubernetes 部署示例
- 健康检查与就绪探针
- 配置管理最佳实践