Background Tasks

{
  "capabilities": {
    "tasks": {
      "cancel": {},
      "list": {},
      "requests": { "tools": { "call": {} } }
    }
  }
}

// Task-augmented tools/call → returns CreateTaskResult
const createResponse = await mcp.raw.request({
  jsonrpc: '2.0',
  id: 1,
  method: 'tools/call',
  params: {
    name: 'big-report',
    arguments: { topic: 'Q4 revenue' },
    task: { ttl: 60_000 },
  },
});
// { result: { task: { taskId: '...', status: 'working', ttl: 60000, ... } } }

const taskId = createResponse.result.task.taskId;

// Poll until terminal
while (true) {
  const r = await mcp.raw.request({
    jsonrpc: '2.0', id: 2, method: 'tasks/get', params: { taskId },
  });
  if (['completed', 'failed', 'cancelled'].includes(r.result.status)) break;
  await sleep(r.result.pollInterval ?? 2000);
}

// Retrieve the actual CallToolResult
const result = await mcp.raw.request({
  jsonrpc: '2.0', id: 3, method: 'tasks/result', params: { taskId },
});
// result.result.structuredContent = { topic: 'Q4 revenue', pages: 42 }
// result.result._meta['io.modelcontextprotocol/related-task'] = { taskId }

          ┌──────────────┐
   create │   working    │ → completed
 ─────────┤              │ → failed
          │              │ → cancelled
          └──────┬───────┘
                 │ ↕
          ┌──────▼───────┐
          │input_required│ (tool emits elicitation)
          └──────────────┘

await mcp.raw.request({
  jsonrpc: '2.0', id: 4, method: 'tasks/cancel', params: { taskId },
});

@Tool({
  name: 'cancellable-wait',
  inputSchema: { maxMs: z.number() },
  outputSchema: z.object({ cancelled: z.boolean() }),
  execution: { taskSupport: 'optional' },
})
export default class CancellableWaitTool extends ToolContext {
  async execute(input) {
    return await new Promise((resolve) => {
      const timer = setTimeout(() => resolve({ cancelled: false }), input.maxMs);
      this.signal?.addEventListener('abort', () => {
        clearTimeout(timer);
        resolve({ cancelled: true });
      });
    });
  }
}

const response = await mcp.raw.request({
  jsonrpc: '2.0', id: 5, method: 'tasks/result', params: { taskId },
});
// response.result matches CallToolResult (or response.error if the task failed).
// response.result._meta['io.modelcontextprotocol/related-task'] carries the taskId.

const page = await mcp.raw.request({
  jsonrpc: '2.0', id: 6, method: 'tasks/list', params: { cursor: undefined },
});
// { tasks: [...], nextCursor: '...' }

{
  "method": "notifications/tasks/status",
  "params": {
    "taskId": "786512e2-9e0d-44bd-8f29-789f320fe840",
    "status": "completed",
    "createdAt": "2025-11-25T10:30:00Z",
    "lastUpdatedAt": "2025-11-25T10:50:00Z",
    "ttl": 60000,
    "pollInterval": 5000
  }
}

@FrontMcp({
  tasks: {
    enabled: true,
    redis: {
      provider: 'redis',
      host: process.env.REDIS_HOST!,
      port: 6379,
    },
    keyPrefix: 'my-app:task:',
  },
})

@FrontMcp({
  tasks: {
    enabled: true,
    runner: 'cli',                        // required for cross-invocation CLI use
    sqlite: { path: '/var/lib/myapp/tasks.db', walMode: true },
  },
})

CREATE TABLE mcp_tasks (
  task_id       TEXT PRIMARY KEY,
  session_id    TEXT NOT NULL,
  status        TEXT NOT NULL,
  expires_at    INTEGER NOT NULL,     -- epoch ms, enforces TTL
  created_at    INTEGER NOT NULL,
  updated_at    INTEGER NOT NULL,
  executor_pid  INTEGER,              -- populated by CliTaskRunner
  record_json   TEXT NOT NULL         -- full TaskRecord as JSON
);
CREATE INDEX idx_mcp_tasks_session ON mcp_tasks (session_id);
CREATE INDEX idx_mcp_tasks_status  ON mcp_tasks (status);
CREATE INDEX idx_mcp_tasks_expires ON mcp_tasks (expires_at);

interface TasksConfig {
  /** Explicitly disable with `false`. Auto-enabled when any tool declares taskSupport. */
  enabled?: boolean;

  /** Redis backend (for multi-node deployments). */
  redis?: RedisOptionsInput;

  /** SQLite backend (single-file, local, cross-invocation). Required for `runner: 'cli'`. */
  sqlite?: {
    path: string;
    encryption?: { secret: string };
    walMode?: boolean;
    ttlCleanupIntervalMs?: number;
  };

  /**
   * Runner selection.
   *  - `'in-process'` (default) — tasks run on the current event loop.
   *  - `'cli'` — each task runs in a detached child process (see CLI runner section).
   */
  runner?: 'in-process' | 'cli';

  /** Override the command used to spawn detached task workers (CLI runner only). */
  cliRunnerCommand?: { exe: string; args?: string[] };

  /** Throw at startup when the runtime cannot run tasks reliably. Default `false`. */
  strict?: boolean;

  /** Store key prefix. Default `'mcp:task:'`. */
  keyPrefix?: string;

  /** Default TTL applied when the client doesn't request one. Default `3_600_000` (1h). */
  defaultTtlMs?: number;

  /** Hard cap on client-requested TTL. Default `86_400_000` (24h). */
  maxTtlMs?: number;

  /** Suggested poll interval advertised to clients. Default `2_000` (2s). */
  defaultPollIntervalMs?: number;

  /** Maximum concurrent `working` tasks per session. Default `16`. */
  maxConcurrentPerSession?: number;
}

┌────────────────────────────────┐                      ┌──────────────────────────────┐
│ CLI host (parent)              │                      │ Detached worker (child)      │
│                                │                      │                              │
│  tools/call { task: {ttl} }    │                      │  reads task from SQLite      │
│   └ createTaskIfRequested      │                      │  re-dispatches tools/call    │
│      └ SqliteTaskStore.create  │                      │  writes outcome + status     │
│      └ CliTaskRunner.run       │──spawn detached────▶│  process.exit(0)             │
│         (pid, FRONTMCP_RUN_*)  │   stdio: 'ignore'    │                              │
│      └ respond CreateTaskResult│   FRONTMCP_RUN_TASK_ID=…                           │
│  (parent may exit / move on)   │                      │                              │
└──────────────┬─────────────────┘                      └──────────────┬───────────────┘
               │             shared SQLite database                     │
               └─────────────────────────────────────────────────────────┘

Later: tasks/get / tasks/result / tasks/cancel on ANY subsequent process — parent
or a future sibling — reads the SQLite file. tasks/cancel sends SIGTERM to the
worker's PID (persisted on the record).

import { join } from 'node:path';
import { homedir } from 'node:os';

@FrontMcp({
  info: { name: 'My CLI Host', version: '1.0.0' },
  apps: [MyApp],
  tasks: {
    enabled: true,
    runner: 'cli',                                              // switch from in-process
    sqlite: { path: join(homedir(), '.myapp', 'tasks.db') },    // REQUIRED for cli runner — resolve `~` yourself; better-sqlite3 does not expand it.
    // Optional — override the spawn command (default: re-invoke argv[0]+argv[1];
    // auto-wraps with `npx tsx` when the entrypoint is a .ts/.tsx file).
    cliRunnerCommand: { exe: 'node', args: ['./dist/server.js'] },
  },
})
export default class Server {}

@FrontMcp({
  tasks: { enabled: true, strict: true },  // bail out instead of silently half-working
})