mcp-longjobs

MCP를 위한 내구성 있고 재개 가능한 작업 — 타임아웃, 연결 끊김, 클라이언트 재시작을 견디는 장기 실행 작업과 대용량 파일. 오늘날의 모든 클라이언트에서.

中文文档

문제

실제 작업을 수행하는 모든 MCP 서버를 망가뜨리는 세 가지 문제가 있습니다:

• 장기 실행 도구 호출이 타임아웃됩니다. 클라이언트는 호출별 타임아웃(보통 10~60초)을 적용합니다. 크롤링, 빌드, 배치 작업이 실패하고 — 모델의 "재시도"는 전체 작업을 처음부터 다시 시작합니다.

• 실패는 복구할 수 없습니다. 실패한 호출은 자유 형식 오류를 반환하므로 모델은 추측만 할 뿐입니다: 무작정 재시도하거나 포기하거나. 하나의 매개변수를 고치고 재개할 수 없습니다.

• 대용량 파일에는 전송 방안이 없습니다. 바이너리 콘텐츠는 JSON에 base64로 넣거나(33% 오버헤드, 엄격한 메시지 크기 제한) 아무 규약 없는 URL일 뿐입니다 — 청크 분할도, 재개도, 무결성 검사도 없습니다.

2026-07-28 MCP 사양은 Tasks를 추가했습니다 — 실행 중 입력과 내구성 있는 핸들을 지원하는 비동기 실행. 하지만 아직 이를 지원하는 클라이언트는 없으며, 사양은 서버가 옵트인하지 않은 클라이언트의 작업을 거부하도록 요구합니다. 따라서 모든 장기 실행 서버에는 오늘날의 클라이언트에서 작동하는 폴백 경로가 필요합니다. 그것이 바로 이 패키지입니다.

Related MCP server: Simple Streamable HTTP MCP Server

제공 기능

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" });

오늘날의 클라이언트에서 모델이 경험하는 것(Tasks 지원 불필요):

1. crawl-site는 taskId와 durable_task_get을 폴링하라는 안내와 함께 즉시 반환됩니다 — 더 이상 타임아웃이 없습니다.

2. 폴링은 실시간 진행 상황을 보여줍니다: { "status": "working", "progress": { "message": "Crawled /pricing", "fraction": 0.4 } }.

3. 실행 중 질문이 있으면 작업이 input_required로 일시 중지됩니다. 모델은 durable_task_respond로 답하고 작업은 중단된 지점에서 계속됩니다.

4. 클라이언트가 다운됐나요? 새 세션인가요? 동일한 taskId로 durable_task_get을 호출해도 여전히 작동합니다 — 상태는 연결이 아닌 저장소에 있기 때문입니다.

5. durable_task_cancel은 다음 체크포인트에서 협력적으로 작업을 중단합니다.

실패는 프로토콜 오류가 아니라 데이터입니다 — 모델이 한 번의 왕복으로 수리할 수 있는 구조화된 봉투입니다:

{
  "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 }
  }
}

패키지 (하위 경로 내보내기)

설계 노트

• 바이트는 결코 모델을 통과하지 않습니다. 모델은 핸들, 크기, sha256, 진행 상황 같은 메타데이터만 봅니다. 도구 호출을 통한 청크는 소형~중형 페이로드용이며, 대용량 파일은 대역 외로 이동해야 합니다(TUS 엔드포인트 예정) — 모델이 무결성을 검증하는 방식으로.

• 모델은 전달자가 아니라 감독자입니다. 퍼사드 도구 결과에는 자체 지침("이 id로 durable_task_get 호출", "오프셋 N에서 재개")이 포함되어 있으므로, 유능한 모델이라면 호스트 측 지원 없이도 프로토콜을 구동할 수 있습니다.

• 실패는 수리 가능한 데이터입니다. 모든 실패에는 code, retryable, recoveryHint, partial.cursor가 포함됩니다 — 무엇이 잘못되었는지, 재시도가 가능한지, 대신 무엇을 해야 하는지, 이미 무엇이 성공했는지.

• 수명 주기 용어는 사양과 일치합니다. working / input_required / completed / failed / cancelled — 따라서 네이티브 어댑터는 호환성을 깨지 않고 나중에 끼워 넣을 수 있습니다.

상태

빠른 시작

git clone https://github.com/ljppanda/mcp-longjobs
cd mcp-longjobs
npm install && npm run build
node dist/examples/report-generator.js

(npm에 게시되면 동일한 서버가 단일 명령으로 실행됩니다: npx mcp-longjobs.)

클라이언트를 이 서버에 연결하세요 (stdio):

{
  "mcpServers": {
    "report-generator": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-longjobs/dist/examples/report-generator.js"]
    }
  }
}

그런 다음 요청하세요: "전기차 배터리에 관한 3개 섹션으로 구성된 보고서를 생성해 줘." 모델이 작업을 시작하고, durable_task_get을 폴링하고, 결과를 가져오는 것을 지켜보세요. 실행 중에 클라이언트를 종료하고, 다시 시작한 다음, 동일한 taskId를 요청하면 — 작업이 재개됩니다.

개발

npm install
npm test         # vitest
npm run build    # tsc -> dist/
npm run example  # build + run the demo server

기여

PR 환영합니다 — 특히: 저장소 백엔드(SQLite/Redis), 네이티브 ext-tasks 어댑터, TUS 엔드포인트. 더 큰 변경 사항은 먼저 이슈를 열어 주세요.

라이선스

MIT