mcp-longjobs 是一个面向 MCP 服务器的持久化与可恢复操作实现，旨在解决长时任务和大文件传输在现有客户端上容易失败的问题。
用途
MCP 服务器在执行真实工作时常遇到三类问题：长时间工具调用超时（客户端通常限制每次调用 10–60 秒），失败后无法修复（模型只能盲目重试或放弃），以及大文件缺少传输规范（base64 嵌入 JSON 有 33% 开销且受消息大小限制，裸 URL 则没有分块、续传和完整性校验约定）。2026-07-28 的 MCP 规范新增了 Tasks 异步执行能力，但目前没有客户端支持，且规范要求服务器对未选择加入的客户端拒绝任务。因此每个长时服务器都需要一个能在当前客户端上工作的回退方案，mcp-longjobs 正是为此设计。
主要能力
- 即时返回：如 crawl-site 等工具调用立即返回 taskId 和轮询指令，避免超时。
- 实时进度：轮询 durable_task_get 可获取类似 { "status": "working", "progress": { "message": "Crawled /pricing", "fraction": 0.4 } } 的进度信息。
- 中途输入：任务可暂停为 input_required 状态，模型通过 durable_task_respond 回答后，任务从中断处继续。
- 持久化句柄：客户端崩溃或新会话后，使用相同 taskId 调用 durable_task_get 仍可恢复，状态存储在存储层而非连接中。
- 协作式取消：durable_task_cancel 在下一个检查点中止工作。
- 结构化失败：失败以数据形式返回，包含 code、retryable、recoveryHint 和 partial.cursor，说明出错原因、是否可重试、替代做法以及已成功的部分，模型可在一轮往返中修复。
- 文件传输：模型只看到元数据（句柄、大小、sha256、进度），不传输字节；中小载荷可通过工具调用分块传输，大文件建议带外传输（TUS 端点计划中），由模型校验完整性。
使用方式
仓库提供子路径导出的包（packages），具体安装命令、stdio 配置示例及 API 细节在官方文档中给出，本资料中未完整提供。资料提到，一旦发布到 npm，同一服务器可用单条命令 npx mcp-longjobs 运行。使用示例：将客户端指向该服务器（stdio），然后要求“生成一份关于 EV 电池的报告，包含 3 个部分”，模型会启动任务、轮询 durable_task_get 并获取结果；中途终止客户端再重启，用相同 taskId 请求即可恢复。
设计理念
- 字节不经过模型：模型只处理元数据，分块工具调用用于中小载荷，大文件走带外通道。
- 模型是指挥者而非搬运工：门面工具结果自带指令（如“用此 id 调用 durable_task_get”“从偏移 N 恢复”），因此任何有能力的模型都能驱动协议，无需宿主端支持。
- 失败是可修复的数据：每个失败都携带 code、retryable、recoveryHint 和 partial.cursor。
- 生命周期词汇与规范一致：working / input_required / completed / failed / cancelled，便于未来原生适配器无缝接入。
适用场景
适用于需要执行长时间运行任务（爬取、构建、批处理等）或传输大文件的 MCP 服务器，尤其是在当前不支持 Tasks 的客户端上，需要稳定、可恢复、可取消的异步操作。
限制
资料未提供具体的收费、价格、支持的客户端列表、存储后端默认配置、TUS 端点的发布时间、npm 发布状态及完整安装命令等细节，这些内容暂未提供。项目欢迎贡献，特别是存储后端（SQLite/Redis）、原生 ext-tasks 适配器和 TUS 端点，较大改动建议先开 issue 讨论。
