ljppanda/mcp-longjobs

**Durable, resumable operations for MCP — long-running tasks and large files that survive timeouts, disconnects, and client restarts. On every client, today.**
中文文档
The problem
Three things break every MCP server that does real work:
- **Long-running tool calls time out.** Clients impose per-call timeouts (often 10–60s). A crawl, a build, a batch job fails — and the model's "retry" restarts the whole operation from scratch.
- **Failures are unrepairable.** A failed call returns a freeform error, so the model guesses: retry blindly, or give up. It can't fix one parameter and resume.
- **Large files have no transfer story.** Binary content is base64-in-JSON (33% overhead, hard message-size caps) or a bare URL with zero conventions — no chunking, no resume, no integrity checks.
The 2026-07-28 MCP spec added Tasks — async execution with mid-flight input and durable handles. But no client supports it yet, and the spec requires servers to refuse tasks for clients that didn't opt in. **Every long-running server therefore needs a fallback path that works on today's clients. That is this package.**
What you get
What the model experiences on **today's clients** (no Tasks support required):
1. crawl-site returns **instantly** with a taskId and instructions to poll durable_task_get — no more timeouts.
2. Polls show live progress: { "status": "working", "progress": { "message": "Crawled /pricing", "fraction": 0.4 } }.
3. Mid-flight questions pause the task as input_required; the model answers via durable_task_respond and the task continues where it stopped.
4. **Client crash? New session?** durable_task_get with the same taskId still works — state lives in the store, not in the connection.
5. durable_task_cancel aborts the work cooperatively at its next checkpoint.
Failures are **data, not protocol errors** — a structured envelope the model can repair in one round-trip:
Packages (subpath exports)
| Import | Purpose |
| --- | --- |
| mcp-longjobs/tasks | withTasks() + the durable_task_* facade: background execution, progress, mid-flight input, cooperative cancellation |
| mcp-longjobs/files | withFileTransfer(): chunked upload/download, resume cursor, sha256 verification, path-safety roots |
| mcp-longjobs/core | Session model, pluggable stores (memory, JSON file), structured error envelope |
Design notes
- **Bytes never flow through the model.** The model sees metadata only: handle, size, sha256, progress. Chunks through tool calls are for small-to-medium payloads; large files should move out-of-band (TUS endpoint planned) with the model verifying integrity.
- **The model is the director, not the courier.** Facade tool results carry their own instructions ("call durable_task_get with this id", "resume at offset N"), so any capable model can drive the protocol with zero host-side support.
- **Failures are repairable data.** Every failure carries code, retryable, recoveryHint, and partial.cursor — what went wrong, whether a retry can work, what to do instead, and what already succeeded.