workmatic 1.1.2 → 1.2.0

package/dist/cli.js

@@ -22,6 +22,11 @@ function createDatabase(options = {}) {
   sqliteDb.pragma("journal_mode = WAL");
   sqliteDb.pragma("synchronous = NORMAL");
   sqliteDb.pragma("busy_timeout = 5000");
+  sqliteDb.pragma("cache_size = -64000");
+  sqliteDb.pragma("temp_store = MEMORY");
+  sqliteDb.pragma("mmap_size = 268435456");
+  const cacheSize = options.statementCacheSize ?? 1e3;
+  enableStatementCache(sqliteDb, cacheSize);
   const db = new Kysely({
     dialect: new SqliteDialect({
       database: sqliteDb
@@ -49,13 +54,23 @@ function createSchema(db) {
       last_error TEXT
     )
   `);
+  ensurePartialIndex(
+    db,
+    "idx_workmatic_jobs_claim",
+    `CREATE INDEX IF NOT EXISTS idx_workmatic_jobs_claim 
+     ON workmatic_jobs (queue, status, run_at, priority, id)
+     WHERE status = 'ready'`
+  );
+  ensurePartialIndex(
+    db,
+    "idx_workmatic_jobs_lease",
+    `CREATE INDEX IF NOT EXISTS idx_workmatic_jobs_lease 
+     ON workmatic_jobs (status, lease_until)
+     WHERE status = 'running'`
+  );
   db.exec(`
-    CREATE INDEX IF NOT EXISTS idx_workmatic_jobs_claim 
-    ON workmatic_jobs (queue, status, run_at, priority, id)
-  `);
-  db.exec(`
-    CREATE INDEX IF NOT EXISTS idx_workmatic_jobs_lease 
-    ON workmatic_jobs (status, lease_until)
+    CREATE INDEX IF NOT EXISTS idx_workmatic_jobs_queue_status 
+    ON workmatic_jobs (queue, status)
   `);
   db.exec(`
     CREATE TABLE IF NOT EXISTS workmatic_settings (
@@ -68,13 +83,53 @@ function createSchema(db) {
     UPDATE workmatic_jobs SET status = 'dead' WHERE status = 'failed'
   `);
 }
+function ensurePartialIndex(db, indexName, createSql) {
+  const row = db.prepare(
+    "SELECT sql FROM sqlite_master WHERE type = 'index' AND name = ?"
+  ).get(indexName);
+  if (row?.sql && !row.sql.toUpperCase().includes("WHERE")) {
+    db.exec(`DROP INDEX IF EXISTS ${indexName}`);
+  }
+  db.exec(createSql);
+}
+function enableStatementCache(db, maxStatements = 1e3) {
+  if (maxStatements <= 0) {
+    return db;
+  }
+  const originalPrepare = db.prepare.bind(db);
+  const cache = /* @__PURE__ */ new Map();
+  db.prepare = function(sql4) {
+    const cached = cache.get(sql4);
+    if (cached) {
+      cache.delete(sql4);
+      cache.set(sql4, cached);
+      if (!cached.busy) {
+        return cached;
+      }
+      return originalPrepare(sql4);
+    }
+    const stmt = originalPrepare(sql4);
+    if (cache.size >= maxStatements) {
+      const oldestKey = cache.keys().next().value;
+      cache.delete(oldestKey);
+    }
+    cache.set(sql4, stmt);
+    return stmt;
+  };
+  const originalClose = db.close.bind(db);
+  db.close = function() {
+    cache.clear();
+    return originalClose();
+  };
+  return db;
+}
 
 // src/orchestrator.ts
-import { sql as sql3 } from "kysely";
+import { sql as sql2 } from "kysely";
 
 // src/client.ts
 import { nanoid } from "nanoid";
-import { sql } from "kysely";
+import { CompiledQuery } from "kysely";
 
 // src/utils.ts
 var defaultBackoff = (attempts) => {
@@ -104,10 +159,16 @@ function now() {
 
 // src/client.ts
 function createClient(options) {
-  const { db, queue = "default" } = options;
+  const { db, queue = "default", onJobAdded, worker } = options;
   if (!db) {
     throw new Error("Database instance is required");
   }
+  function notifyJobAdded(delayMs) {
+    if (delayMs <= 0) {
+      worker?.wakeUp();
+      onJobAdded?.();
+    }
+  }
   return {
     /**
      * Add a job to the queue
@@ -122,20 +183,13 @@ function createClient(options) {
       const publicId = nanoid();
       const timestamp = now();
       const runAt = timestamp + delayMs;
-      await db.insertInto("workmatic_jobs").values({
-        public_id: publicId,
-        queue,
-        payload: payloadJson,
-        status: "ready",
-        priority,
-        run_at: runAt,
-        attempts: 0,
-        max_attempts: maxAttempts,
-        lease_until: 0,
-        created_at: timestamp,
-        updated_at: timestamp,
-        last_error: null
-      }).execute();
+      await db.executeQuery(
+        CompiledQuery.raw(
+          `INSERT INTO workmatic_jobs (public_id, queue, payload, status, priority, run_at, attempts, max_attempts, lease_until, created_at, updated_at, last_error) VALUES (?, ?, ?, 'ready', ?, ?, 0, ?, 0, ?, ?, null)`,
+          [publicId, queue, payloadJson, priority, runAt, maxAttempts, timestamp, timestamp]
+        )
+      );
+      notifyJobAdded(delayMs);
       return { ok: true, id: publicId };
     },
     async addMany(payloads, opts = {}) {
@@ -149,7 +203,7 @@ function createClient(options) {
       }
       const timestamp = now();
       const runAt = timestamp + delayMs;
-      return await db.transaction().execute(async (trx) => {
+      const result = await db.transaction().execute(async (trx) => {
         const ids = [];
         const rows = payloads.map((payload) => {
           const payloadJson = validatePayload(payload);
@@ -173,15 +227,19 @@ function createClient(options) {
         await trx.insertInto("workmatic_jobs").values(rows).execute();
         return { ok: true, ids };
       });
+      notifyJobAdded(delayMs);
+      return result;
     },
     /**
      * Get job statistics for the queue
      */
     async stats() {
-      const result = await db.selectFrom("workmatic_jobs").select([
-        "status",
-        sql`count(*)`.as("count")
-      ]).where("queue", "=", queue).groupBy("status").execute();
+      const result = await db.executeQuery(
+        CompiledQuery.raw(
+          "SELECT status, count(*) AS count FROM workmatic_jobs WHERE queue = ? GROUP BY status",
+          [queue]
+        )
+      );
       const stats = {
         ready: 0,
         running: 0,
@@ -189,7 +247,7 @@ function createClient(options) {
         dead: 0,
         total: 0
       };
-      for (const row of result) {
+      for (const row of result.rows) {
         const status = row.status;
         const count = Number(row.count);
         if (status in stats) {
@@ -215,7 +273,77 @@ function createClient(options) {
 
 // src/worker.ts
 import fastq from "fastq";
-import { sql as sql2 } from "kysely";
+import { sql, CompiledQuery as CompiledQuery2 } from "kysely";
+
+// src/shutdown.ts
+function attachGracefulShutdown(target, options = {}) {
+  const {
+    signals = ["SIGINT", "SIGTERM"],
+    timeoutMs = 3e4,
+    exitOnComplete = true,
+    exitCode = 0,
+    timeoutExitCode = 1,
+    onShutdownStart,
+    onShutdownComplete,
+    onShutdownError
+  } = options;
+  let shuttingDown = false;
+  async function stopTarget() {
+    if (Array.isArray(target)) {
+      await Promise.all(target.map((w) => w.stop()));
+    } else if ("stopAll" in target) {
+      await target.stopAll();
+    } else {
+      await target.stop();
+    }
+  }
+  const handler = async (signal) => {
+    if (shuttingDown) {
+      return;
+    }
+    shuttingDown = true;
+    onShutdownStart?.(signal);
+    let timer = null;
+    if (timeoutMs > 0) {
+      timer = setTimeout(() => {
+        const err = new Error(`Graceful shutdown timed out after ${timeoutMs}ms`);
+        onShutdownError?.(err);
+        if (exitOnComplete) {
+          process.exit(timeoutExitCode);
+        }
+      }, timeoutMs);
+      timer.unref();
+    }
+    try {
+      await stopTarget();
+      if (timer) {
+        clearTimeout(timer);
+      }
+      onShutdownComplete?.();
+      if (exitOnComplete) {
+        process.exit(exitCode);
+      }
+    } catch (err) {
+      if (timer) {
+        clearTimeout(timer);
+      }
+      onShutdownError?.(err);
+      if (exitOnComplete) {
+        process.exit(timeoutExitCode);
+      }
+    }
+  };
+  for (const sig of signals) {
+    process.on(sig, handler);
+  }
+  return function detach() {
+    for (const sig of signals) {
+      process.removeListener(sig, handler);
+    }
+  };
+}
+
+// src/worker.ts
 var DEFAULT_WORKER_TIMEOUT_MS = 6e4;
 function parseClaimedRows(result) {
   const rows = result.rows;
@@ -253,7 +381,8 @@ function createWorker(options) {
     autoRestore = true,
     pauseCheckIntervalMs = 300,
     requeueExpiredIntervalMs = 0,
-    onPumpError
+    onPumpError,
+    completionBatchSize = 50
   } = options;
   if (!db) {
     throw new Error("Database instance is required");
@@ -266,6 +395,8 @@ function createWorker(options) {
   let lastPauseCheckAt = 0;
   let cachedDbPaused = false;
   let lastRequeueAt = 0;
+  let pendingDone = [];
+  let flushTimeout = null;
   function notifyPumpError(error) {
     console.error("[workmatic] Pump error:", error);
     onPumpError?.(error);
@@ -277,13 +408,16 @@ function createWorker(options) {
     if (!persistState) return;
     const timestamp = now();
     const key = getStateKey();
-    await sql2`
-      INSERT INTO workmatic_settings (queue, paused, updated_at)
-      VALUES (${key}, ${state === "paused" ? 1 : state === "running" ? 2 : 0}, ${timestamp})
-      ON CONFLICT(queue) DO UPDATE SET 
-        paused = ${state === "paused" ? 1 : state === "running" ? 2 : 0},
-        updated_at = ${timestamp}
-    `.execute(db);
+    try {
+      await sql`
+        INSERT INTO workmatic_settings (queue, paused, updated_at)
+        VALUES (${key}, ${state === "paused" ? 1 : state === "running" ? 2 : 0}, ${timestamp})
+        ON CONFLICT(queue) DO UPDATE SET 
+          paused = ${state === "paused" ? 1 : state === "running" ? 2 : 0},
+          updated_at = ${timestamp}
+      `.execute(db);
+    } catch {
+    }
   }
   async function loadState() {
     if (!persistState) return null;
@@ -310,52 +444,104 @@ function createWorker(options) {
   async function claimBatch(limit) {
     const timestamp = now();
     const leaseUntil = timestamp + leaseMs;
-    return await db.transaction().execute(async (trx) => {
-      const result = await sql2`
-        UPDATE workmatic_jobs
-        SET status = 'running', lease_until = ${leaseUntil}, updated_at = ${timestamp}
-        WHERE rowid IN (
-          SELECT rowid FROM workmatic_jobs
-          WHERE queue = ${queue}
-            AND status = 'ready'
-            AND run_at <= ${timestamp}
-          ORDER BY priority ASC, id ASC
-          LIMIT ${limit}
+    const result = await sql`
+      UPDATE workmatic_jobs
+      SET status = 'running', lease_until = ${leaseUntil}, updated_at = ${timestamp}
+      WHERE rowid IN (
+        SELECT rowid FROM workmatic_jobs
+        WHERE queue = ${queue}
+          AND status = 'ready'
+          AND run_at <= ${timestamp}
+        ORDER BY priority ASC, id ASC
+        LIMIT ${limit}
+      )
+      RETURNING id, public_id, queue, payload, attempts, max_attempts, priority, created_at, last_error
+    `.execute(db);
+    return parseClaimedRows(result);
+  }
+  async function flushDoneBatch() {
+    if (flushTimeout !== null) {
+      clearImmediate(flushTimeout);
+      flushTimeout = null;
+    }
+    if (pendingDone.length === 0) {
+      return;
+    }
+    const current = pendingDone;
+    pendingDone = [];
+    const timestamp = now();
+    try {
+      if (current.length === 1) {
+        await db.executeQuery(
+          CompiledQuery2.raw(
+            "UPDATE workmatic_jobs SET status = 'done', lease_until = 0, updated_at = ? WHERE id = ?",
+            [timestamp, current[0].id]
+          )
+        );
+      } else {
+        const CHUNK_SIZE = 500;
+        for (let i = 0; i < current.length; i += CHUNK_SIZE) {
+          const chunk = current.slice(i, i + CHUNK_SIZE);
+          const placeholders = chunk.map(() => "?").join(", ");
+          const params = [timestamp, ...chunk.map((item) => item.id)];
+          await db.executeQuery(
+            CompiledQuery2.raw(
+              `UPDATE workmatic_jobs SET status = 'done', lease_until = 0, updated_at = ? WHERE id IN (${placeholders})`,
+              params
+            )
+          );
+        }
+      }
+      for (const item of current) {
+        item.resolve();
+      }
+    } catch (err) {
+      for (const item of current) {
+        item.reject(err);
+      }
+    }
+  }
+  function markDone(jobId) {
+    if (completionBatchSize <= 0) {
+      return db.executeQuery(
+        CompiledQuery2.raw(
+          "UPDATE workmatic_jobs SET status = 'done', lease_until = 0, updated_at = ? WHERE id = ?",
+          [now(), jobId]
         )
-        RETURNING id, public_id, queue, payload, attempts, max_attempts, priority, created_at, last_error
-      `.execute(trx);
-      return parseClaimedRows(result);
+      ).then(() => {
+      });
+    }
+    return new Promise((resolve, reject) => {
+      pendingDone.push({ id: jobId, resolve, reject });
+      if (pendingDone.length >= completionBatchSize) {
+        void flushDoneBatch();
+      } else if (!flushTimeout) {
+        flushTimeout = setImmediate(() => {
+          flushTimeout = null;
+          void flushDoneBatch();
+        });
+      }
     });
   }
-  async function markDone(jobId) {
-    await db.updateTable("workmatic_jobs").set({
-      status: "done",
-      lease_until: 0,
-      updated_at: now()
-    }).where("id", "=", jobId).execute();
-  }
   async function markFailed(jobId, attempts, maxAttempts, error) {
     const timestamp = now();
     const newAttempts = attempts + 1;
     const errorMessage = error.message || String(error);
     if (newAttempts < maxAttempts) {
       const runAt = timestamp + backoff(newAttempts);
-      await db.updateTable("workmatic_jobs").set({
-        status: "ready",
-        attempts: newAttempts,
-        run_at: runAt,
-        lease_until: 0,
-        last_error: errorMessage,
-        updated_at: timestamp
-      }).where("id", "=", jobId).execute();
+      await db.executeQuery(
+        CompiledQuery2.raw(
+          "UPDATE workmatic_jobs SET status = 'ready', attempts = ?, run_at = ?, lease_until = 0, last_error = ?, updated_at = ? WHERE id = ?",
+          [newAttempts, runAt, errorMessage, timestamp, jobId]
+        )
+      );
     } else {
-      await db.updateTable("workmatic_jobs").set({
-        status: "dead",
-        attempts: newAttempts,
-        lease_until: 0,
-        last_error: errorMessage,
-        updated_at: timestamp
-      }).where("id", "=", jobId).execute();
+      await db.executeQuery(
+        CompiledQuery2.raw(
+          "UPDATE workmatic_jobs SET status = 'dead', attempts = ?, lease_until = 0, last_error = ?, updated_at = ? WHERE id = ?",
+          [newAttempts, errorMessage, timestamp, jobId]
+        )
+      );
     }
   }
   async function withTimeout(promise, ms, jobId) {
@@ -402,8 +588,13 @@ function createWorker(options) {
     }
   }
   async function isQueuePausedInDb() {
-    const setting = await db.selectFrom("workmatic_settings").select("paused").where("queue", "=", queue).executeTakeFirst();
-    return setting?.paused === 1;
+    const result = await db.executeQuery(
+      CompiledQuery2.raw(
+        "SELECT paused FROM workmatic_settings WHERE queue = ? LIMIT 1",
+        [queue]
+      )
+    );
+    return result.rows[0]?.paused === 1;
   }
   async function pump() {
     if (!running) {
@@ -458,8 +649,7 @@ function createWorker(options) {
       running = true;
       paused = false;
       fastqQueue = fastq.promise(processJob, concurrency);
-      saveState("running").catch(() => {
-      });
+      void saveState("running");
       pump();
     },
     async stop() {
@@ -471,27 +661,28 @@ function createWorker(options) {
         clearTimeout(pumpTimeout);
         pumpTimeout = null;
       }
-      if (fastqQueue) {
-        await fastqQueue.drained();
-        fastqQueue = null;
-      }
+      await fastqQueue.drained();
+      fastqQueue = null;
+      await flushDoneBatch();
       await saveState("stopped");
     },
     pause() {
       paused = true;
-      saveState("paused").catch(() => {
-      });
+      void flushDoneBatch();
+      void saveState("paused");
     },
     resume() {
       paused = false;
-      saveState("running").catch(() => {
-      });
+      void saveState("running");
     },
     async stats() {
-      const result = await db.selectFrom("workmatic_jobs").select([
-        "status",
-        sql2`count(*)`.as("count")
-      ]).where("queue", "=", queue).groupBy("status").execute();
+      await flushDoneBatch();
+      const result = await db.executeQuery(
+        CompiledQuery2.raw(
+          "SELECT status, count(*) AS count FROM workmatic_jobs WHERE queue = ? GROUP BY status",
+          [queue]
+        )
+      );
       const stats = {
         ready: 0,
         running: 0,
@@ -499,7 +690,7 @@ function createWorker(options) {
         dead: 0,
         total: 0
       };
-      for (const row of result) {
+      for (const row of result.rows) {
         const status = row.status;
         const count = Number(row.count);
         if (status in stats) {
@@ -535,6 +726,22 @@ function createWorker(options) {
       }
       const result = await query.execute();
       return Number(result[0]?.numDeletedRows ?? 0);
+    },
+    wakeUp() {
+      if (!running || paused) {
+        return;
+      }
+      if (pumpTimeout) {
+        clearTimeout(pumpTimeout);
+        pumpTimeout = null;
+      }
+      pumpTimeout = setTimeout(pump, 0);
+    },
+    async flushCompletions() {
+      await flushDoneBatch();
+    },
+    attachSignalHandlers(options2) {
+      return attachGracefulShutdown(this, options2);
     }
   };
   if (persistState && autoRestore) {
@@ -567,7 +774,15 @@ function createOrchestrator(options) {
   function ensureEntry(queue) {
     let entry = registry.get(queue);
     if (!entry) {
-      entry = { client: createClient({ db, queue }) };
+      entry = {
+        client: createClient({
+          db,
+          queue,
+          onJobAdded: () => {
+            registry.get(queue)?.worker?.wakeUp();
+          }
+        })
+      };
       registry.set(queue, entry);
     }
     return entry;
@@ -575,7 +790,7 @@ function createOrchestrator(options) {
   async function setQueuePaused(queue, paused) {
     const timestamp = now();
     const value = paused ? 1 : 0;
-    await sql3`
+    await sql2`
       INSERT INTO workmatic_settings (queue, paused, updated_at)
       VALUES (${queue}, ${value}, ${timestamp})
       ON CONFLICT(queue) DO UPDATE SET
@@ -740,11 +955,750 @@ function createOrchestrator(options) {
         return;
       }
       await db.updateTable("workmatic_jobs").set({ queue: toQueue, updated_at: timestamp }).where("public_id", "=", publicId).execute();
+    },
+    attachSignalHandlers(options2) {
+      return attachGracefulShutdown(this, options2);
     }
   };
   return orchestrator;
 }
 
+// src/mcp/server.ts
+import readline from "readline";
+import { EventEmitter } from "events";
+
+// src/mcp/tools.ts
+import { sql as sql3 } from "kysely";
+var MCP_TOOL_DEFINITIONS = [
+  {
+    name: "workmatic_list_queues",
+    description: "List all queues present in the Workmatic database along with job counts",
+    inputSchema: {
+      type: "object",
+      properties: {}
+    }
+  },
+  {
+    name: "workmatic_get_stats",
+    description: "Get real-time job counts (ready, running, done, dead, total) for a specific queue or all queues",
+    inputSchema: {
+      type: "object",
+      properties: {
+        queue: {
+          type: "string",
+          description: "Optional queue name. If omitted, stats for all queues will be returned."
+        }
+      }
+    }
+  },
+  {
+    name: "workmatic_list_jobs",
+    description: "List jobs in the database filtered by queue, status, and limit",
+    inputSchema: {
+      type: "object",
+      properties: {
+        queue: {
+          type: "string",
+          description: "Filter by queue name"
+        },
+        status: {
+          type: "string",
+          enum: ["ready", "running", "done", "dead"],
+          description: "Filter by job status"
+        },
+        limit: {
+          type: "number",
+          description: "Maximum number of jobs to return (default: 20, max: 100)"
+        },
+        offset: {
+          type: "number",
+          description: "Number of jobs to skip for pagination (default: 0)"
+        }
+      }
+    }
+  },
+  {
+    name: "workmatic_get_dead_jobs",
+    description: "Retrieve failed/dead jobs with error details and payloads for debugging",
+    inputSchema: {
+      type: "object",
+      properties: {
+        queue: {
+          type: "string",
+          description: "Filter dead jobs by queue name"
+        },
+        limit: {
+          type: "number",
+          description: "Maximum number of dead jobs to return (default: 20)"
+        }
+      }
+    }
+  },
+  {
+    name: "workmatic_add_job",
+    description: "Enqueue a new background job into Workmatic",
+    inputSchema: {
+      type: "object",
+      properties: {
+        queue: {
+          type: "string",
+          description: 'Target queue name (default: "default")'
+        },
+        payload: {
+          description: "Job payload (JSON object, string, number, etc.)"
+        },
+        priority: {
+          type: "number",
+          description: "Job priority (lower number = higher priority, default: 0)"
+        },
+        delayMs: {
+          type: "number",
+          description: "Delay in milliseconds before job can run (default: 0)"
+        },
+        maxAttempts: {
+          type: "number",
+          description: "Maximum execution retry attempts (default: 3)"
+        }
+      },
+      required: ["payload"]
+    }
+  },
+  {
+    name: "workmatic_retry_job",
+    description: "Retry a specific dead or failed job by resetting it to ready status",
+    inputSchema: {
+      type: "object",
+      properties: {
+        publicId: {
+          type: "string",
+          description: "Public ID of the job to retry"
+        }
+      },
+      required: ["publicId"]
+    }
+  },
+  {
+    name: "workmatic_retry_all_dead",
+    description: "Retry all dead jobs (optionally in a specific queue) by resetting them to ready status",
+    inputSchema: {
+      type: "object",
+      properties: {
+        queue: {
+          type: "string",
+          description: "Optional queue name to restrict retrying"
+        }
+      }
+    }
+  },
+  {
+    name: "workmatic_pause_queue",
+    description: "Pause a queue so workers stop claiming new jobs from it",
+    inputSchema: {
+      type: "object",
+      properties: {
+        queue: {
+          type: "string",
+          description: "Queue name to pause"
+        }
+      },
+      required: ["queue"]
+    }
+  },
+  {
+    name: "workmatic_resume_queue",
+    description: "Resume a paused queue so workers resume claiming jobs",
+    inputSchema: {
+      type: "object",
+      properties: {
+        queue: {
+          type: "string",
+          description: "Queue name to resume"
+        }
+      },
+      required: ["queue"]
+    }
+  },
+  {
+    name: "workmatic_purge_jobs",
+    description: "Permanently remove done or dead jobs from the database",
+    inputSchema: {
+      type: "object",
+      properties: {
+        queue: {
+          type: "string",
+          description: "Queue name to purge jobs from (optional)"
+        },
+        status: {
+          type: "string",
+          enum: ["done", "dead", "all"],
+          description: 'Status of jobs to purge (default: "done")'
+        }
+      }
+    }
+  },
+  {
+    name: "workmatic_transfer_jobs",
+    description: "Move jobs from one queue to another (e.g. from dead-letter queue back to primary)",
+    inputSchema: {
+      type: "object",
+      properties: {
+        fromQueue: {
+          type: "string",
+          description: "Source queue name"
+        },
+        toQueue: {
+          type: "string",
+          description: "Destination queue name"
+        },
+        status: {
+          type: "string",
+          enum: ["ready", "dead"],
+          description: 'Status of jobs to transfer (default: "ready")'
+        },
+        limit: {
+          type: "number",
+          description: "Maximum number of jobs to transfer (default: 1000)"
+        },
+        resetForRetry: {
+          type: "boolean",
+          description: "If transferring dead jobs, reset their status to ready (default: false)"
+        }
+      },
+      required: ["fromQueue", "toQueue"]
+    }
+  },
+  {
+    name: "workmatic_update_job_status",
+    description: "Update the status of a specific job (ready, done, dead) and signal workers / listeners",
+    inputSchema: {
+      type: "object",
+      properties: {
+        publicId: {
+          type: "string",
+          description: "Public ID of the job to update"
+        },
+        status: {
+          type: "string",
+          enum: ["ready", "done", "dead"],
+          description: "New status for the job"
+        },
+        error: {
+          type: "string",
+          description: "Optional error message when marking as dead or recording failure details"
+        },
+        resetAttempts: {
+          type: "boolean",
+          description: "Whether to reset attempts to 0 (default: true if status is ready, false otherwise)"
+        },
+        delayMs: {
+          type: "number",
+          description: "Delay in milliseconds before the job becomes ready (default: 0)"
+        }
+      },
+      required: ["publicId", "status"]
+    }
+  }
+];
+async function executeTool(db, name, args2 = {}, context) {
+  switch (name) {
+    case "workmatic_list_queues": {
+      const qJobs = await db.selectFrom("workmatic_jobs").select("queue").distinct().execute();
+      const qSettings = await db.selectFrom("workmatic_settings").select("queue").distinct().execute();
+      const set = /* @__PURE__ */ new Set();
+      for (const r of qJobs) set.add(r.queue);
+      for (const r of qSettings) {
+        if (!r.queue.startsWith("worker_state_")) {
+          set.add(r.queue);
+        }
+      }
+      const queueList = Array.from(set).sort();
+      const result = [];
+      for (const q of queueList) {
+        const client = createClient({ db, queue: q });
+        const stats = await client.stats();
+        const setting = await db.selectFrom("workmatic_settings").select("paused").where("queue", "=", q).executeTakeFirst();
+        result.push({
+          queue: q,
+          stats: {
+            ready: stats.ready,
+            running: stats.running,
+            done: stats.done,
+            dead: stats.dead,
+            total: stats.total
+          },
+          isPaused: setting?.paused === 1
+        });
+      }
+      return { queues: result, totalQueues: result.length };
+    }
+    case "workmatic_get_stats": {
+      const queue = args2.queue;
+      if (queue) {
+        const client = createClient({ db, queue });
+        return { queue, stats: await client.stats() };
+      }
+      const listRes = await executeTool(db, "workmatic_list_queues");
+      const summary = {};
+      const grandTotal = { ready: 0, running: 0, done: 0, dead: 0, total: 0 };
+      for (const item of listRes.queues) {
+        summary[item.queue] = item.stats;
+        grandTotal.ready += item.stats.ready;
+        grandTotal.running += item.stats.running;
+        grandTotal.done += item.stats.done;
+        grandTotal.dead += item.stats.dead;
+        grandTotal.total += item.stats.total;
+      }
+      return { queues: summary, grandTotal };
+    }
+    case "workmatic_list_jobs": {
+      const queue = args2.queue;
+      const status = args2.status;
+      const limit = Math.min(Math.max(Number(args2.limit ?? 20), 1), 100);
+      const offset = Math.max(Number(args2.offset ?? 0), 0);
+      let query = db.selectFrom("workmatic_jobs").select([
+        "id",
+        "public_id",
+        "queue",
+        "status",
+        "priority",
+        "payload",
+        "attempts",
+        "max_attempts",
+        "run_at",
+        "created_at",
+        "updated_at",
+        "last_error"
+      ]);
+      if (queue) {
+        query = query.where("queue", "=", queue);
+      }
+      if (status) {
+        query = query.where("status", "=", status);
+      }
+      const rows = await query.orderBy("priority", "asc").orderBy("id", "asc").limit(limit).offset(offset).execute();
+      const jobs = rows.map((r) => {
+        let parsedPayload;
+        try {
+          parsedPayload = JSON.parse(r.payload);
+        } catch {
+          parsedPayload = r.payload;
+        }
+        return {
+          id: r.id,
+          publicId: r.public_id,
+          queue: r.queue,
+          status: r.status,
+          priority: r.priority,
+          attempts: r.attempts,
+          maxAttempts: r.max_attempts,
+          runAt: r.run_at,
+          createdAt: r.created_at,
+          updatedAt: r.updated_at,
+          lastError: r.last_error,
+          payload: parsedPayload
+        };
+      });
+      return { jobs, count: jobs.length, limit, offset };
+    }
+    case "workmatic_get_dead_jobs": {
+      const queue = args2.queue;
+      const limit = Math.min(Math.max(Number(args2.limit ?? 20), 1), 100);
+      return executeTool(db, "workmatic_list_jobs", {
+        queue,
+        status: "dead",
+        limit
+      });
+    }
+    case "workmatic_add_job": {
+      const queue = args2.queue || "default";
+      const payload = args2.payload;
+      const priority = args2.priority !== void 0 ? Number(args2.priority) : 0;
+      const delayMs = args2.delayMs !== void 0 ? Number(args2.delayMs) : 0;
+      const maxAttempts = args2.maxAttempts !== void 0 ? Number(args2.maxAttempts) : 3;
+      const client = createClient({ db, queue });
+      const result = await client.add(payload, { priority, delayMs, maxAttempts });
+      return { ok: true, id: result.id, queue };
+    }
+    case "workmatic_retry_job": {
+      const publicId = args2.publicId;
+      if (!publicId) {
+        throw new Error("publicId is required");
+      }
+      const job = await db.selectFrom("workmatic_jobs").select(["queue", "status"]).where("public_id", "=", publicId).executeTakeFirst();
+      if (!job) {
+        throw new Error(`Job not found: ${publicId}`);
+      }
+      const timestamp = now();
+      await db.updateTable("workmatic_jobs").set({
+        status: "ready",
+        attempts: 0,
+        lease_until: 0,
+        last_error: null,
+        run_at: timestamp,
+        updated_at: timestamp
+      }).where("public_id", "=", publicId).execute();
+      context?.onJobStatusChanged?.({
+        publicId,
+        queue: job.queue,
+        previousStatus: job.status,
+        status: "ready",
+        timestamp,
+        error: null
+      });
+      return { ok: true, id: publicId, message: `Job ${publicId} reset to ready` };
+    }
+    case "workmatic_retry_all_dead": {
+      const queue = args2.queue;
+      const timestamp = now();
+      let query = db.updateTable("workmatic_jobs").set({
+        status: "ready",
+        attempts: 0,
+        lease_until: 0,
+        last_error: null,
+        run_at: timestamp,
+        updated_at: timestamp
+      }).where("status", "=", "dead");
+      if (queue) {
+        query = query.where("queue", "=", queue);
+      }
+      const res = await query.execute();
+      const retriedCount = Number(res[0].numUpdatedRows);
+      if (retriedCount > 0) {
+        context?.onJobStatusChanged?.({
+          publicId: "*",
+          queue: queue ?? "*",
+          previousStatus: "dead",
+          status: "ready",
+          timestamp,
+          error: null
+        });
+      }
+      return { ok: true, retriedCount, queue: queue ?? "all" };
+    }
+    case "workmatic_update_job_status": {
+      const publicId = args2.publicId;
+      const status = args2.status;
+      if (!publicId) {
+        throw new Error("publicId is required");
+      }
+      if (!status || !["ready", "done", "dead"].includes(status)) {
+        throw new Error("status is required and must be 'ready', 'done', or 'dead'");
+      }
+      const job = await db.selectFrom("workmatic_jobs").select(["id", "public_id", "queue", "status", "attempts"]).where("public_id", "=", publicId).executeTakeFirst();
+      if (!job) {
+        throw new Error(`Job not found: ${publicId}`);
+      }
+      if (job.status === status) {
+        return {
+          ok: true,
+          id: publicId,
+          queue: job.queue,
+          status,
+          unchanged: true
+        };
+      }
+      const timestamp = now();
+      const previousStatus = job.status;
+      const delayMs = Math.max(Number(args2.delayMs ?? 0), 0);
+      const resetAttempts = args2.resetAttempts !== void 0 ? Boolean(args2.resetAttempts) : status === "ready";
+      const updateData = {
+        status,
+        updated_at: timestamp,
+        lease_until: 0
+      };
+      if (status === "ready") {
+        updateData.run_at = timestamp + delayMs;
+      }
+      if (resetAttempts) {
+        updateData.attempts = 0;
+      }
+      if (args2.error !== void 0) {
+        updateData.last_error = args2.error;
+      } else if (status === "ready") {
+        updateData.last_error = null;
+      }
+      await db.updateTable("workmatic_jobs").set(updateData).where("public_id", "=", publicId).execute();
+      const event = {
+        publicId,
+        queue: job.queue,
+        previousStatus,
+        status,
+        timestamp,
+        error: updateData.last_error ?? null
+      };
+      context?.onJobStatusChanged?.(event);
+      return {
+        ok: true,
+        id: publicId,
+        queue: job.queue,
+        previousStatus,
+        status,
+        signaled: true
+      };
+    }
+    case "workmatic_pause_queue": {
+      const queue = args2.queue;
+      if (!queue) {
+        throw new Error("queue is required");
+      }
+      const timestamp = now();
+      await sql3`
+        INSERT INTO workmatic_settings (queue, paused, updated_at)
+        VALUES (${queue}, 1, ${timestamp})
+        ON CONFLICT(queue) DO UPDATE SET
+          paused = 1,
+          updated_at = ${timestamp}
+      `.execute(db);
+      return { ok: true, queue, paused: true };
+    }
+    case "workmatic_resume_queue": {
+      const queue = args2.queue;
+      if (!queue) {
+        throw new Error("queue is required");
+      }
+      const timestamp = now();
+      await sql3`
+        INSERT INTO workmatic_settings (queue, paused, updated_at)
+        VALUES (${queue}, 0, ${timestamp})
+        ON CONFLICT(queue) DO UPDATE SET
+          paused = 0,
+          updated_at = ${timestamp}
+      `.execute(db);
+      return { ok: true, queue, paused: false };
+    }
+    case "workmatic_purge_jobs": {
+      const queue = args2.queue;
+      const status = args2.status || "done";
+      let query = db.deleteFrom("workmatic_jobs");
+      if (queue) {
+        query = query.where("queue", "=", queue);
+      }
+      if (status !== "all") {
+        query = query.where("status", "=", status);
+      }
+      const res = await query.execute();
+      const deletedCount = Number(res[0].numDeletedRows);
+      return { ok: true, deletedCount, queue: queue ?? "all", status };
+    }
+    case "workmatic_transfer_jobs": {
+      const fromQueue = args2.fromQueue;
+      const toQueue = args2.toQueue;
+      if (!fromQueue || !toQueue) {
+        throw new Error("fromQueue and toQueue are required");
+      }
+      if (fromQueue === toQueue) {
+        return { ok: true, moved: 0 };
+      }
+      const status = args2.status || "ready";
+      const limit = Math.max(Number(args2.limit ?? 1e3), 1);
+      const resetForRetry = Boolean(args2.resetForRetry);
+      const orch = createOrchestrator({ db });
+      const result = await orch.transfer({
+        from: fromQueue,
+        to: toQueue,
+        status,
+        limit,
+        resetForRetry
+      });
+      return {
+        ok: true,
+        moved: result.moved,
+        fromQueue,
+        toQueue,
+        status: resetForRetry && status === "dead" ? "ready" : status
+      };
+    }
+    default:
+      throw new Error(`Unknown tool: ${name}`);
+  }
+}
+
+// src/mcp/server.ts
+function createMcpServer(options) {
+  const db = options.db;
+  const input = options.input ?? process.stdin;
+  const output = options.output ?? process.stdout;
+  const emitter = new EventEmitter();
+  let rl = null;
+  let isRunning = false;
+  function notifyJobStatusChanged(event) {
+    if (options.onJobStatusChanged) {
+      options.onJobStatusChanged(event);
+    }
+    emitter.emit("jobStatusChanged", event);
+    if (event.status === "ready") {
+      if (options.orchestrator) {
+        if (event.queue === "*") {
+          for (const worker of options.orchestrator.workers()) {
+            worker.wakeUp();
+          }
+        } else {
+          try {
+            options.orchestrator.worker(event.queue).wakeUp();
+          } catch {
+          }
+        }
+      }
+      if (options.workers) {
+        for (const worker of options.workers) {
+          if (event.queue === "*" || worker.queue === event.queue) {
+            worker.wakeUp();
+          }
+        }
+      }
+    }
+    if (isRunning) {
+      output.write(
+        JSON.stringify({
+          jsonrpc: "2.0",
+          method: "notifications/workmatic/job_status_changed",
+          params: event
+        }) + "\n"
+      );
+    }
+  }
+  async function handleMessage(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed) {
+      return null;
+    }
+    let msg;
+    try {
+      msg = JSON.parse(trimmed);
+    } catch {
+      return JSON.stringify({
+        jsonrpc: "2.0",
+        id: null,
+        error: {
+          code: -32700,
+          message: "Parse error"
+        }
+      });
+    }
+    if (!msg || typeof msg !== "object" || msg.jsonrpc !== "2.0" || typeof msg.method !== "string") {
+      return JSON.stringify({
+        jsonrpc: "2.0",
+        id: msg?.id ?? null,
+        error: {
+          code: -32600,
+          message: "Invalid Request"
+        }
+      });
+    }
+    const isNotification = msg.id === void 0;
+    switch (msg.method) {
+      case "initialize": {
+        const result = {
+          protocolVersion: "2024-11-05",
+          capabilities: {
+            tools: {}
+          },
+          serverInfo: {
+            name: "workmatic-mcp",
+            version: "0.1.0"
+          }
+        };
+        return isNotification ? null : JSON.stringify({ jsonrpc: "2.0", id: msg.id, result });
+      }
+      case "notifications/initialized": {
+        return null;
+      }
+      case "ping": {
+        return isNotification ? null : JSON.stringify({ jsonrpc: "2.0", id: msg.id, result: {} });
+      }
+      case "tools/list": {
+        const result = {
+          tools: MCP_TOOL_DEFINITIONS
+        };
+        return isNotification ? null : JSON.stringify({ jsonrpc: "2.0", id: msg.id, result });
+      }
+      case "tools/call": {
+        if (!msg.params || typeof msg.params.name !== "string") {
+          return isNotification ? null : JSON.stringify({
+            jsonrpc: "2.0",
+            id: msg.id,
+            error: {
+              code: -32602,
+              message: 'Invalid params: tool "name" is required'
+            }
+          });
+        }
+        const toolName = msg.params.name;
+        const toolArgs = msg.params.arguments ?? {};
+        try {
+          const toolResult = await executeTool(db, toolName, toolArgs, {
+            onJobStatusChanged: notifyJobStatusChanged
+          });
+          const response = {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify(toolResult, null, 2)
+              }
+            ]
+          };
+          return isNotification ? null : JSON.stringify({ jsonrpc: "2.0", id: msg.id, result: response });
+        } catch (err) {
+          const errorMessage = err instanceof Error ? err.message : String(err);
+          const response = {
+            content: [
+              {
+                type: "text",
+                text: errorMessage
+              }
+            ],
+            isError: true
+          };
+          return isNotification ? null : JSON.stringify({ jsonrpc: "2.0", id: msg.id, result: response });
+        }
+      }
+      default: {
+        return isNotification ? null : JSON.stringify({
+          jsonrpc: "2.0",
+          id: msg.id,
+          error: {
+            code: -32601,
+            message: `Method not found: ${msg.method}`
+          }
+        });
+      }
+    }
+  }
+  const server = {
+    start() {
+      if (isRunning) return;
+      isRunning = true;
+      rl = readline.createInterface({
+        input,
+        terminal: false
+      });
+      rl.on("line", (line) => {
+        void handleMessage(line).then((response) => {
+          if (response && isRunning) {
+            output.write(response + "\n");
+          }
+        });
+      });
+    },
+    stop() {
+      if (!isRunning) return;
+      isRunning = false;
+      rl.close();
+      rl = null;
+    },
+    handleMessage,
+    on(event, listener) {
+      emitter.on(event, listener);
+      return server;
+    },
+    off(event, listener) {
+      emitter.off(event, listener);
+      return server;
+    }
+  };
+  return server;
+}
+
 // src/cli/handlers.ts
 function printUsage() {
   console.log(`
@@ -764,6 +1718,8 @@ Commands:
   pause <db> <queue>             Pause a queue (running workers stop claiming)
   resume <db> <queue>            Resume a paused queue
   transfer <db> <from> <to>      Move jobs between queues
+  mcp <db>                       Start Model Context Protocol (MCP) server
+
 
 Options:
   --status=<status>   Filter by status (ready|running|done|dead), comma-separated for transfer
@@ -1237,6 +2193,34 @@ async function cmdTransfer(dbPath, from, to, options) {
     await db.destroy();
   }
 }
+async function cmdMcp(dbPath, options = {}) {
+  const db = createDatabase({ filename: dbPath });
+  const server = createMcpServer({
+    db,
+    input: options.input,
+    output: options.output
+  });
+  server.start();
+  await new Promise((resolve) => {
+    const cleanup = () => {
+      server.stop();
+      if (!options.input) {
+        process.removeListener("SIGINT", cleanup);
+        process.removeListener("SIGTERM", cleanup);
+        process.stdin.removeListener("end", cleanup);
+      }
+      resolve();
+    };
+    if (options.input) {
+      options.input.once("end", cleanup);
+    } else {
+      process.stdin.once("end", cleanup);
+      process.once("SIGINT", cleanup);
+      process.once("SIGTERM", cleanup);
+    }
+  });
+  await db.destroy();
+}
 async function runCommand(command2, dbPath, positionalArgs, options) {
   switch (command2) {
     case "stats":
@@ -1281,6 +2265,9 @@ async function runCommand(command2, dbPath, positionalArgs, options) {
       }
       await cmdTransfer(dbPath, positionalArgs[1], positionalArgs[2], options);
       break;
+    case "mcp":
+      await cmdMcp(dbPath);
+      break;
     default:
       throw new Error(`Unknown command: ${command2}`);
   }
@@ -1299,7 +2286,8 @@ var KNOWN_COMMANDS = [
   "pause",
   "resume",
   "queues",
-  "transfer"
+  "transfer",
+  "mcp"
 ];
 function isCliCommand(value) {
   return KNOWN_COMMANDS.includes(value);