关键词

AI协作智能体编程代码项目管理上下文服务文件协作协议

项目简介 Watercooler Cloud旨在为AI代理（如Claude, Codex）提供一个标准化的文件协作后端，特别适用于智能编程项目。它通过Model Context Protocol (MCP) 协议，允许LLM客户端访问和管理“对话线程”（以Markdown文件形式存储），调用工具来创建、更新、查询这些线程，从而实现上下文共享、任务交接和决策记录。项目强调无依赖、文件存储和Git友好。

主要功能点

  • 会话线程管理: 创建、读取、更新以Markdown文件形式存储的协作线程。
  • 结构化条目: 支持添加包含代理、角色、类型、标题和正文的结构化条目。
  • 智能体协作: 自动管理“球权”（ball ownership），支持“说”（say）、“确认”（ack）、“交接”（handoff）等操作。
  • 状态与球权跟踪: 线程可设为OPEN、IN_REVIEW、CLOSED等状态，并明确追踪当前处理任务的代理。
  • Git同步: 支持将本地线程目录与远程Git仓库同步，实现多用户/多代理协作。
  • 索引与搜索: 生成线程摘要索引，并支持对线程内容进行搜索。
  • 诊断工具: 提供健康检查和身份验证工具，帮助排查服务器问题。

安装步骤

  1. 克隆仓库: 
    git clone https://github.com/mostlyharmless-ai/watercooler-cloud.git
cd watercooler-cloud
  2. 安装Python依赖: 
    pip install -e .[mcp]
    注意: 在Windows上，可能需要将'python'替换为'py -3'或'python3'。

服务器配置 Watercooler Cloud MCP服务器的启动命令是 'python -m watercooler_mcp'。MCP客户端需要使用此命令来连接服务器并发现其提供的工具和资源。

MCP客户端配置关键信息: MCP客户端通常需要一个JSON格式的配置，其中包含服务器的启动命令、参数和环境变量。以下是关键配置项及说明：

  • 'name': 服务器的名称，例如 '"watercooler-cloud"'。客户端会使用此名称引用该服务器。
  • 'command': 一个字符串数组，指定启动MCP服务器的可执行文件和模块。例如：'["python", "-m", "watercooler_mcp"]'。
    • '"python"': Python解释器。
    • '"-m"': 作为模块运行。
    • '"watercooler_mcp"': Watercooler Cloud的MCP服务器模块。
  • 'args': 一个字符串数组，包含传递给'command'的额外命令行参数，本服务器通常无需额外参数。
  • 'env': 一个JSON对象，包含服务器运行时所需的环境变量。
    • '"WATERCOOLER_AGENT"': （可选）定义AI代理的名称，例如'"Claude@Code"'。这将影响线程条目中的署名和球权流转。
    • '"WATERCOOLER_THREADS_PATTERN"': （可选）定义线程Git仓库的URL模式，例如'"https://github.com/{org}/{repo}-threads.git"'。这是实现多用户协作的关键。
    • '"WATERCOOLER_AUTO_BRANCH"': （可选）设置为'"1"'以启用基于代码仓库分支的自动线程分支管理。
  • 'scope': 客户端注册服务器的范围，例如'"user"'（用户级）。
  • 'transport': 客户端与服务器通信的协议，例如'"stdio"'（标准输入输出）。

您的MCP客户端（如Claude CLI或Codex CLI）在添加服务器时，会引导您输入或自动生成此类配置。

基本使用方法 配置完成后，您的MCP客户端（如Claude Code或Codex CLI）将能够自动发现并使用Watercooler Cloud提供的工具。

以下是一些客户端可以调用的核心工具示例：

  1. 列出所有线程 (List Threads): 获取当前所有协作线程的摘要，包括球权和新消息标记。 客户端请求示例: 调用 'watercooler_v1_list_threads' 工具，参数可以包含 'open_only: true'。

  2. 阅读线程内容 (Read Thread): 获取特定线程的完整内容，包括所有历史条目。 客户端请求示例: 调用 'watercooler_v1_read_thread' 工具，参数 'topic: "feature-auth"'。

  3. 发表评论/更新 (Say): 向线程添加一条新条目，并自动将“球权”转交给您的对话伙伴。 客户端请求示例: 调用 'watercooler_v1_say' 工具，参数 'topic: "feature-auth"', 'title: "完成认证模块"', 'body: "所有单元测试通过，等待审查。"', 'agent_func: "Claude:implementer"'。

  4. 确认消息 (Ack): 确认已阅读线程更新，但不会改变“球权”。 客户端请求示例: 调用 'watercooler_v1_ack' 工具，参数 'topic: "feature-auth"', 'title: "已收到"', 'body: "感谢更新。"', 'agent_func: "Claude:pm"'。

  5. 交接任务 (Handoff): 明确将“球权”转交给特定代理或您的默认对话伙伴。 客户端请求示例: 调用 'watercooler_v1_handoff' 工具，参数 'topic: "feature-auth"', 'note: "请代码审查"', 'target_agent: "Codex"', 'agent_func: "Claude:pm"'。

  6. 更新线程状态 (Set Status): 更改线程的状态，例如从“OPEN”更改为“IN_REVIEW”或“CLOSED”。 客户端请求示例: 调用 'watercooler_v1_set_status' 工具，参数 'topic: "feature-auth"', 'status: "IN_REVIEW"', 'agent_func: "Claude:pm"'。

这些工具让AI代理能够以结构化和可追踪的方式参与到编码项目中。

信息

分类

开发者工具

访问项目