ssyubix 跨设备 MCP 服务端实现

使用说明

• 项目简介

  • 目标：实现一个 MCP 服务器端，向 LLM 客户端提供资源、工具与提示模板，以及房间/会话管理能力，使用 JSON-RPC 风格的请求和响应，支持多种传输通道。
  • 技术栈要点：Python 实现的 MCP 服务器，结合 Cloudflare Workers + Durable Objects 做房间中继，定义资源、工具、提示模板，并实现会话管理、能力声明与本地缓存。

• 主要功能点

  • 资源 (Resources)：提供可读取的能力资源，例如跨房间能力注册表、技能等的只读接口。
  • 工具 (Tools)：实现诸如 agent_register、room_create、room_join、room_leave、agent_send、agent_read_inbox 等 MCP 工具，供 LLM 客户端调用以执行操作。
  • 提示模板 (Prompts)：定义并渲染促使 LLM 的模板，例如 onboarding 提示。
  • JSON-RPC 风格通信：通过 MCP 风格的请求/响应格式进行交互，支持错误处理与结果返回。
  • 会话与房间管理：支持房间创建、加入、离开、房间信息查询，以及对话队列、重试队列和本地缓存的管理。
  • 多传输协议支持：本地运行通过 STDIO，亦可扩展为 WebSocket/SSE 等传输通道，适配不同客户端。
  • 本地缓存与持久化：对房间状态、消息、摘要等进行本地缓存、恢复与清理，提升离线能力。

• 安装步骤

  1. 确保系统已安装 Python 3.x 环境。
  2. 将源码中的 Python 部分安装为可运行的包（本仓库以 pin 为例，目录为 python/，包名为 ssyubix）。在该目录内执行可编辑安装，以便本地开发。
  3. 安装完成后即可运行服务。

• 服务器配置（供 MCP 客户端参考的启动信息） 说明：MCP 客户端需要知道如何启动并连接到 MCP 服务器。以下为示例配置（以文本形式给出，需替换为实际运行环境参数）。 { "server_name": "ssyubix-agentlink", "command": "python", "args": ["-m", "ssyubix"], "transport": "stdio", "notes": "默认通过标准输入/输出进行通信，可根据需要改为 WebSocket/SSE 等传输。环境变量可覆盖服务器端的端点配置，如 AGENTLINK_URL、AGENT_NAME。" } 注释：

  • server_name：用于在 MCP 客户端侧标识的服务器名称，便于日志与追踪。
  • command 与 args：启动服务器的命令及参数，实际启动命令应与部署方式一致。仓库中提供了 Python 实现入口，若以包形式部署，通常为 python -m ssyubix。
  • transport：客户端与服务器之间的传输协议，MCP 客户端通常支持 STDIO、WebSocket、SSE 等。此处以 STDIO 为示例。
  • notes：补充说明和环境变量信息，帮助客户端正确连接，例如 AGENTLINK_URL、AGENT_NAME 以及本地/远程部署时的注意事项。

• 基本使用方法

  1. 部署并启动 MCP 服务器（以本仓库 Python 实现为例）；
  2. 使用 MCP 客户端通过配置的启动信息连接服务器，读取资源、执行工具、获取提示模板；
  3. 客户端在房间内注册自我信息，查询房间信息，及从资源/工具/提示模板中获取所需能力；
  4. 当网络断开时，本地缓存会回落并在网络恢复后进行重放与重试；
  5. 客户端可通过资源接口读取房间内的能力信息、技能、成员等，或调用工具完成任务。

• 备注

  • 服务器实现包含了完整的资源、工具、提示模板，以及房间/会话管理、状态持久化与缓存、能力矩阵的维护等核心 MCP 功能，非单纯示例或测试代码。
  • 运行与部署方式可以结合 Cloudflare Workers 的中继能力进行分布式部署，具体环境请参考仓库中的 Cloudflare 相关配置与文档。