Skip to main content
Glama

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.

CI npm license

中文文档

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):

  1. crawl-site gibt sofort eine taskId und Anweisungen zurück, durable_task_get abzufragen – keine Timeouts mehr.

  2. Die Abfragen zeigen Live-Fortschritt: { "status": "working", "progress": { "message": "Crawled /pricing", "fraction": 0.4 } }.

  3. Fragen während des Laufs pausieren die Aufgabe als input_required; das Modell antwortet über durable_task_respond, und die Aufgabe wird an der Stelle fortgesetzt, an der sie gestoppt wurde.

  4. Client abgestürzt? Neue Sitzung? durable_task_get mit derselben taskId funktioniert weiterhin – der Zustand lebt im Store, nicht in der Verbindung.

  5. durable_task_cancel bricht 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

mcp-longjobs/tasks

withTasks() + die durable_task_*-Fassade: Hintergrundausführung, Fortschritt, Eingaben während des Laufs, kooperativer Abbruch

mcp-longjobs/files

withFileTransfer(): Chunk-Upload/-Download, Fortsetzungs-Cursor, sha256-Verifizierung, pfadsichere Wurzelverzeichnisse

mcp-longjobs/core

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_get mit 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, recoveryHint und partial.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 (CreateTaskResult / tasks/get)

🔜 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 server

Mitwirken

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

MIT

Available Tools

9 tools
durable_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

    A3.9/5.0

    Scored across 9 tools

    Disambiguation5/5

    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.

    Naming Consistency3/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityStale
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A 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.
      7
      MIT
    • F
      license
      Not graded
      quality
      B
      maintenance
      Remote MCP server that launches user-supplied scripts inside disposable Docker containers, returning task IDs for async tracking and bounded output tails.
      -