Sayou MCP 服务器

使用说明（Markdown 格式）

• 项目简介
  • Sayou 是一个面向 AI 代理的持久化知识工作区后端，提供对资源（文件）、工具（可供 LLM 调用的外部功能）以及提示模板的统一管理与访问，采用 MCP（Model Context Protocol）实现客户端与服务端的对话式、结构化交互。
  • MCP 服务器通过 JSON-RPC 与 LLM 客户端通信，具备会话绑定、能力声明、以及对多传输协议的支持（如 stdio 和 HTTP 流式传输），并提供多租户/权限控制和文件版本历史等特性。
• 主要功能点
  • 提供 17 个 MCP 工具，覆盖文件写读/列表/搜索/历史/差异、KV 存储、文件移动/复制等能力，供 LLM 动态调用。
  • 资源管理：对工作区内的文件进行版本化存储、前端元数据（frontmatter）解析、分层索引与目录树生成。
  • 工具注册与执行：通过 MCP 服务器公共接口注册、列出和执行工具，响应以文本格式返回结果，便于 LLM 直接理解与继续对话。
  • Prompts 与渲染：对话中可渲染并返回摘要、章节指针等，用于高效的上下文传递与 drill-down。
  • 会话与权限：基于工作区/组织的 RBAC（reader/writer/admin）权限检查，支持组织间隔离与用户绑定。
  • 多传输协议：支持标准输入输出（stdio）和基于 HTTP 的流式传输，便于本地开发和云端部署。
• 安装与运行
  • 直接从仓库运行：本仓库实现了一个可运行的 MCP 服务器与一组工具，开发者或集成方可直接运行并接入 MCP 客户端。
  • 运行方式示例（简述，非代码片段）
    • 通过命令行启动成 MCP 服务器，默认使用 stdio 传输；也可指定 HTTP 传输与端口进行网络访问。
    • MCP 客户端配置需指定服务器名称、启动命令及参数（参见下方的配置示例）。
• 服务器配置（MCP 客户端连接配置示例，JSON 格式）
  • 服务器名称: sayou
  • 启动命令: sayou
  • 参数/环境示例（注释性描述，不是代码块）
    • command: "sayou"
    • env: { "SAYOU_ORG_ID": "my-org", "SAYOU_USER_ID": "alice" }
  • 说明: 该配置用于 MCP 客户端连接 Sayou MCP 服务器。客户端需要的仅是正确的启动命令与必要的标识信息；实际的 MCP 客户端将通过该配置启动并与服务器建立对话。
• 基本使用方法
  • 启动服务器
    • 以默认 stdio 模式启动，服务器将输出到当前进程的标准输入/输出，便于与本地代理/工具直接对话。
    • 也可使用 HTTP 流式传输模式，将对外暴露为一个 REST/流式接口，支持远程客户端接入。
  • 进行一次简单的写入与读取
    • 向工作区写入一个文件，包含 YAML frontmatter 以测试元数据解析与版本历史。
    • 读取同一路径的文件，验证版本号、内容和 frontmatter 信息。
  • 使用 MCP 客户端调用工具
    • 客户端通过 MCP 协议请求调用 workspace_write、workspace_read、workspace_list 等工具，服务端返回结构化响应。
  • 高级用法
    • 使用 workspace_read 的 token_budget 控制返回内容规模（以便提供给 LLM 进行进一步推理）。
    • 通过 history、diff、move、copy 等工具实现完整的版本控制与变更对比。
• 备注
  • 代码已经实现完整的 MCP 服务端逻辑、工具注册与执行、RBAC 与工作区隔离、以及多种存储后端的支持（本地存储或 S3）。
  • 服务端还提供 REST API 入口用于外部系统集成，并附带前端式的路由与对象模型，便于测试与扩展。