一、用途 conversation-handoff-mcp 是一个 MCP 服务器，用于在 AI 聊天之间、或同一 AI 内不同项目之间传递对话上下文。它被设计为一种轻量的临时剪贴板：数据只存在内存中，不写入磁盘，适合在活跃会话期间共享上下文。
二、主要能力
- 交接保存与加载：handoff_save 保存对话上下文，key 和标题可省略并自动生成（v0.4.0+）。conversation 字段存储完整逐字内容，AI 被要求不要总结或缩写消息（v0.6.1+）。handoff_load 加载指定交接的完整内容。
- 列表与检索：handoff_list 仅返回摘要以节省上下文，并附带消息数、大小、状态和下一步动作等元数据（v0.11.0+）。handoff_search（v0.12.0+）支持用结构化标签（如 project:foo、issue:176）以及文本、项目、AI、状态、日期范围进行多条件过滤。
- 合并与删除：handoff_merge（v0.6.0+）将多个相关交接合并为一个统一上下文；支持删除交接记录。
- 标签与评论：可用结构化标签标记交接（v0.12.0+）；可添加注释/批注用于跨会话上下文（v0.10.0+）。
- 发送方元数据（v0.14.0+）：可选的 from_project / spawner_dispatch_id / sender_agent_id 让编排器记录是谁发送了交接，服务器对格式不作要求，未设置时不输出。合并时仅当所有来源交接在该字段上一致才保留。
- 提示注入防护（v0.14.0+）：handoff_load 将存储内容放在不可信内容标记中返回，包括警告横幅、一次性边界令牌（内容无法伪造结束标记）以及扩宽到超过正文中最长反引号串的代码围栏；结构化内容字段保持原始未包裹。
- 其他：服务器重启（v0.9.0+）、审计日志（v0.7.0+，可选 JSONL，--audit 开启）、MCP Apps UI（v0.5.0+）提供浏览和管理交接的交互界面、自动连接（v0.4.0+）、自动重连（v0.4.0+）。
三、使用方式 通过 npm 使用（推荐）：无需预安装，通过 npx 运行。配置文件中填写 MCP 配置（Codex CLI 使用 TOML 格式）。提供三种 MCP 客户端配置：标准配置（推荐，自动连接即可工作）、指定自定义服务器、强制独立模式（无服务器）。
四、存储与运行模式
- 内存存储：数据仅存于内存，通过 HTTP 服务器在全部已连接 MCP 客户端间共享；服务器进程停止即丢失；不写文件。达到上限时按 FIFO 自动删除最旧交接且不报错。
- 自动连接：v0.4.0+ 起，MCP 客户端连接时服务器自动在后台启动，无需手动设置。
- 自动重连：服务器中断时按 HANDOFF_RETRY_COUNT 重试（默认 30），最终失败时输出待处理内容供手动恢复；其他客户端下次请求时自动发现新服务器。
- 服务器自动关闭（TTL）：默认 24 小时无请求后关闭，可用 HANDOFF_SERVER_TTL 配置，设为 0 禁用。
- 也支持手动启动服务器（可选）。
五、适用场景与限制 适用场景：Claude Desktop 内不同项目之间的交接（Claude Desktop 默认无法在项目之间转移对话，但作为单一应用共享内存空间，借助该服务器可实现项目间交接）；在不同 MCP 客户端之间交接，例如在 Claude Desktop 做设计讨论、在 Claude Code 加载并继续实现。示例流程：保存时为 handoff_save 生成 key（如 auth-design-20241208），加载时用 handoff_load 载入完整上下文，包含代码片段和决策，无需手动复制粘贴。
限制：数据仅存于内存，服务器进程停止即丢失，不适合长期持久化。Claude Code 和 CLI 工具按每个标签页/会话作为独立进程运行，此模式下交接不生效。关于 MCP Apps 规范中的 sendMessage，规范要求应直接把消息加入对话并触发模型响应，但 Claude Desktop 当前实现是插入到聊天输入框，需用户按回车发送；官方预期未来 Claude Desktop 更新会改进此行为。提示注入防护是缓解而非保证，模型仍可能被足够有说服力的文本影响，对来自不可信发送方的交接应谨慎处理。
