mcp-longjobs
mcp-longjobs
Dauerhafte, fortsetzbare Vorgänge für MCP – langlaufende Aufgaben und große Dateien, die Timeouts, Verbindungsabbrüche und Client-Neustarts überleben. Auf jedem Client, heute.
Das Problem
Drei Dinge lassen jeden MCP-Server scheitern, der echte Arbeit leistet:
Langlaufende Tool-Aufrufe laufen in einen Timeout. Clients setzen Timeouts pro Aufruf (oft 10–60 s). Ein Crawl, ein Build, ein Batch-Job schlägt fehl – und der „Retry“ des Modells startet die gesamte Operation von vorn.
Fehler sind nicht reparierbar. Ein fehlgeschlagener Aufruf gibt einen frei formulierten Fehler zurück, also rät das Modell: blind wiederholen oder aufgeben. Es kann nicht einen Parameter korrigieren und fortsetzen.
Große Dateien haben kein Übertragungskonzept. Binärinhalte sind base64-in-JSON (33 % Overhead, harte Nachrichtengrößen-Grenzen) oder eine nackte URL ohne Konventionen – kein Chunking, kein Fortsetzen, keine Integritätsprüfungen.
Die MCP-Spezifikation vom 2026-07-28 hat Tasks hinzugefügt – asynchrone Ausführung mit Eingaben während des Laufs und dauerhaften Handles. Aber noch unterstützt kein Client das, und die Spezifikation verlangt, dass Server Tasks für Clients ablehnen, die nicht zugestimmt haben. Jeder langlaufende Server braucht daher einen Fallback-Pfad, der auf heutigen Clients funktioniert. Das ist dieses Paket.
Related MCP server: Simple Streamable HTTP MCP Server
Was Sie bekommen
import { z } from "zod";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { JsonFileSessionStore, withTasks, withFileTransfer, asToolRegistrar } from "mcp-longjobs";
const mcp = new McpServer({ name: "my-server", version: "1.0.0" });
const registrar = asToolRegistrar(mcp);
const store = new JsonFileSessionStore("./state/sessions.json");
const tasks = withTasks(registrar, { store });
tasks.taskTool("crawl-site", {
description: "Crawl a site and produce a report (takes minutes)",
inputSchema: { url: z.string(), maxPages: z.number().default(50) },
}, async (args, ctx) => {
for (const page of pages) {
if (ctx.signal.aborted) throw new Error("cancelled");
await ctx.progress(`Crawled ${page.url}`, done / total);
if (needsConfirmation(page)) {
const answer = await ctx.needInput({ prompt: `Include ${page.url}?`, choices: ["yes", "no"] });
if (answer === "no") continue;
}
}
return { summary, reportPath }; // small result for the model; big artifacts go through file transfer
});
withFileTransfer(registrar, { store, storageDir: "./state/blobs" });Was das Modell auf heutigen Clients erlebt (keine Tasks-Unterstützung erforderlich):
crawl-sitegibt sofort einetaskIdund Anweisungen zurück,durable_task_getabzufragen – keine Timeouts mehr.Die Abfragen zeigen Live-Fortschritt:
{ "status": "working", "progress": { "message": "Crawled /pricing", "fraction": 0.4 } }.Fragen während des Laufs pausieren die Aufgabe als
input_required; das Modell antwortet überdurable_task_respond, und die Aufgabe wird an der Stelle fortgesetzt, an der sie gestoppt wurde.Client abgestürzt? Neue Sitzung?
durable_task_getmit derselbentaskIdfunktioniert weiterhin – der Zustand lebt im Store, nicht in der Verbindung.durable_task_cancelbricht die Arbeit kooperativ am nächsten Checkpoint ab.
Fehler sind Daten, keine Protokollfehler – eine strukturierte Hülle, die das Modell in einem einzigen Round-Trip reparieren kann:
{
"status": "failed",
"error": {
"code": "offset_mismatch",
"message": "Expected offset 131072, got 0.",
"retryable": true,
"recoveryHint": "Do NOT resend the whole file. Re-send this chunk starting at offset 131072.",
"partial": { "cursor": 131072 }
}
}Pakete (Subpath-Exporte)
Import | Zweck |
|
|
|
|
| Sitzungsmodell, austauschbare Stores (In-Memory, JSON-Datei), strukturierte Fehlerhülle |
Designhinweise
Bytes fließen nie durch das Modell. Das Modell sieht nur Metadaten: Handle, Größe, sha256, Fortschritt. Chunks über Tool-Aufrufe sind für kleine bis mittlere Nutzlasten gedacht; große Dateien sollten out-of-band übertragen werden (TUS-Endpunkt geplant), wobei das Modell die Integrität prüft.
Das Modell ist der Regisseur, nicht der Kurier. Die Ergebnisse der Fassaden-Tools enthalten ihre eigenen Anweisungen („Rufen Sie
durable_task_getmit dieser ID auf“, „Setzen Sie bei Offset N fort“), sodass jedes fähige Modell das Protokoll ohne jegliche Host-Unterstützung steuern kann.Fehler sind reparierbare Daten. Jeder Fehler enthält
code,retryable,recoveryHintundpartial.cursor– was schiefging, ob ein erneuter Versuch funktionieren kann, was stattdessen zu tun ist und was bereits erfolgreich war.Das Lebenszyklus-Vokabular entspricht der Spezifikation.
working / input_required / completed / failed / cancelled, sodass der native Adapter später ohne Breaking Changes eingefügt werden kann.
Status
Komponente | Status |
Tasks-Fallback-Fassade (Fortschritt / Eingabe / Abbruch) | ✅ implementiert |
Dauerhafte Sitzungs-Stores (In-Memory, JSON-Datei) | ✅ implementiert |
Chunk-Dateiübertragung mit Fortsetzen + Prüfsummen | ✅ implementiert |
Nativer ext-tasks-Adapter ( | 🔜 orientiert sich an der experimentellen Tasks-API des SDKs |
TUS-1.0-Out-of-Band-Endpunkt für große Dateien | 🔜 geplant – siehe mcp#189 |
Redis-/SQLite-Stores, Python-Port | 🔜 geplant |
Schnellstart
git clone https://github.com/ljppanda/mcp-longjobs
cd mcp-longjobs
npm install && npm run build
node dist/examples/report-generator.js(Sobald es auf npm veröffentlicht ist, läuft derselbe Server mit einem einzigen Befehl: npx mcp-longjobs.)
Richten Sie Ihren Client darauf aus (stdio):
{
"mcpServers": {
"report-generator": {
"command": "node",
"args": ["/absolute/path/to/mcp-longjobs/dist/examples/report-generator.js"]
}
}
}Fragen Sie dann: „Erstelle einen Bericht über EV-Batterien mit 3 Abschnitten.“ Beobachten Sie, wie das Modell den Auftrag startet, durable_task_get abfragt und das Ergebnis abholt. Beenden Sie den Client während des Laufs, starten Sie ihn neu und fragen Sie nach derselben taskId – der Vorgang wird fortgesetzt.
Entwicklung
npm install
npm test # vitest
npm run build # tsc -> dist/
npm run example # build + run the demo serverMitwirken
PRs sind willkommen – insbesondere: Store-Backends (SQLite/Redis), der native ext-tasks-Adapter und der TUS-Endpunkt. Bitte eröffnen Sie für größere Änderungen zuerst ein Issue.
Lizenz
Available Tools
9 toolsdurable_task_cancelCancel a durable taskA
Cooperatively cancel a running task. The task stops at its next checkpoint.
Inputs: taskId (required).
durable_task_getGet durable task statusA
Poll a long-running task created by this server. Repeat until status is "completed" or "failed".
Inputs: taskId (required).
durable_task_respondAnswer a durable task's questionA
Deliver input that a paused task (status input_required) asked for.
Inputs: taskId (required), response (required).
file_transfer_commitFinalize an upload sessionA
Verify size and sha256 (when declared), then move the staged file to its destination.
Inputs: handle (required).
file_transfer_openOpen a resumable file transferA
Open a chunked upload or download session. Upload: send chunks with file_transfer_write starting at offset 0, then file_transfer_commit. Download: fetch chunks with file_transfer_read until eof. Sessions survive server restarts — resume at the reported nextOffset.
Inputs: path (required), direction (required), size, sha256.
file_transfer_readRead one chunk from a download sessionA
Fetch a byte range as base64. Repeat with nextOffset until eof; the final response carries the whole-file sha256.
Inputs: handle (required), length, offset.
file_transfer_statusInspect a transfer sessionA
Report direction, status, bytes received so far, and destination — useful after a restart.
Inputs: handle (required).
file_transfer_writeWrite one chunk to an upload sessionA
Append a base64 chunk at the session's expected offset. A wrong offset returns a repairable error with the correct cursor instead of failing the transfer.
Inputs: data (required), handle (required), offset (required).
generate-reportGenerate a market reportA
Simulates a slow job (~2s per section). Demonstrates background execution, progress polling, restart-safe state, and cooperative cancellation.
Inputs: topic (required), sections.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Each tool maps to a distinct action within its domain: durable_task_get/respond/cancel are clearly separate task lifecycle operations, and file_transfer_open/write/read/commit/status cover distinct phases of a transfer. generate-report is the only job-creation tool and does not overlap with the polling or transfer tools.
Most tools follow a clear prefix_verb snake_case pattern, such as durable_task_get and file_transfer_open, but generate-report breaks this by using a hyphenated verb-noun style. The group prefixes help readability, but the mixed conventions prevent a higher score.
Nine tools is well within the ideal range, and each appears to serve a specific necessity for either durable task coordination or chunked file transfer. The count feels focused and purposeful rather than bloated.
The task lifecycle is well covered with get, respond, and cancel, and the file transfer flow covers open, read/write, commit, and status. Minor gaps exist: there is no explicit file transfer cancellation/abort tool, and task creation is only demonstrated through generate-report rather than a generic create tool.
Maintenance
Related MCP Connectors
MCP server for the FFmpeg Micro video transcoding API — create, monitor, download transcodes.
Public MCP server for discovering open jobs. Search, filter, and get application links.
Hosted MCP server for task-first delegation to remote workstations and workers.
QuLab MCP remote server (Streamable HTTP) for computational science and lab tools.
Related MCP Servers
- AlicenseAqualityCmaintenanceAsync MCP server for running long-running AI tasks with real-time progress monitoring, enabling users to start, monitor, and manage complex AI workflows across multiple models.623 npm5MIT
- AlicenseNot gradedqualityDmaintenanceA reference implementation demonstrating proper MCP server patterns with HTTP transport, featuring session management, progress notifications, and example tools for testing server functionality. Serves as a clean template for building MCP servers with streamable responses and comprehensive error handling.7MIT
- AlicenseAqualityBmaintenanceA fire-and-poll MCP server that lets Claude Code run long background jobs without hitting tool-call timeouts.3MIT
- FlicenseNot gradedqualityBmaintenanceRemote MCP server that launches user-supplied scripts inside disposable Docker containers, returning task IDs for async tracking and bounded output tails.-