@nicnocquee/dataqueue 1.33.0 → 1.35.0-beta.20260224075710

package/dist/mcp-server.cjs

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+'use strict';
+
+var mcp_js = require('@modelcontextprotocol/sdk/server/mcp.js');
+var stdio_js = require('@modelcontextprotocol/sdk/server/stdio.js');
+var zod = require('zod');
+var fs = require('fs');
+var path = require('path');
+var url = require('url');
+
+var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var fs__default = /*#__PURE__*/_interopDefault(fs);
+var path__default = /*#__PURE__*/_interopDefault(path);
+
+var __filename$1 = url.fileURLToPath((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('mcp-server.cjs', document.baseURI).href)));
+var __dirname$1 = path__default.default.dirname(__filename$1);
+function loadDocsContent(docsPath = path__default.default.join(__dirname$1, "../ai/docs-content.json")) {
+  const raw = fs__default.default.readFileSync(docsPath, "utf-8");
+  return JSON.parse(raw);
+}
+function scorePageForQuery(page, queryTerms) {
+  const titleLower = page.title.toLowerCase();
+  const descLower = page.description.toLowerCase();
+  const contentLower = page.content.toLowerCase();
+  let score = 0;
+  for (const term of queryTerms) {
+    if (titleLower.includes(term)) score += 10;
+    if (descLower.includes(term)) score += 5;
+    const contentMatches = contentLower.split(term).length - 1;
+    score += Math.min(contentMatches, 10);
+  }
+  return score;
+}
+function extractExcerpt(content, queryTerms, maxLength = 500) {
+  const lower = content.toLowerCase();
+  let earliestIndex = -1;
+  for (const term of queryTerms) {
+    const idx = lower.indexOf(term);
+    if (idx !== -1 && (earliestIndex === -1 || idx < earliestIndex)) {
+      earliestIndex = idx;
+    }
+  }
+  if (earliestIndex === -1) {
+    return content.slice(0, maxLength);
+  }
+  const start = Math.max(0, earliestIndex - 100);
+  const end = Math.min(content.length, start + maxLength);
+  let excerpt = content.slice(start, end);
+  if (start > 0) excerpt = "..." + excerpt;
+  if (end < content.length) excerpt = excerpt + "...";
+  return excerpt;
+}
+async function startMcpServer(deps = {}) {
+  const pages = loadDocsContent(deps.docsPath);
+  const server = new mcp_js.McpServer({
+    name: "dataqueue-docs",
+    version: "1.0.0"
+  });
+  server.resource("llms-txt", "dataqueue://llms.txt", async () => {
+    const llmsPath = path__default.default.join(
+      __dirname$1,
+      "../ai/skills/dataqueue-core/SKILL.md"
+    );
+    let content;
+    try {
+      content = fs__default.default.readFileSync(llmsPath, "utf-8");
+    } catch {
+      content = pages.map((p) => `## ${p.title}
+
+Slug: ${p.slug}
+
+${p.description}`).join("\n\n");
+    }
+    return { contents: [{ uri: "dataqueue://llms.txt", text: content }] };
+  });
+  server.tool(
+    "list-doc-pages",
+    "List all available DataQueue documentation pages with titles and descriptions.",
+    {},
+    async () => {
+      const listing = pages.map((p) => ({
+        slug: p.slug,
+        title: p.title,
+        description: p.description
+      }));
+      return {
+        content: [
+          { type: "text", text: JSON.stringify(listing, null, 2) }
+        ]
+      };
+    }
+  );
+  server.tool(
+    "get-doc-page",
+    "Fetch a specific DataQueue doc page by slug. Returns full page content as markdown.",
+    {
+      slug: zod.z.string().describe('The doc page slug, e.g. "usage/add-job" or "api/job-queue"')
+    },
+    async ({ slug }) => {
+      const page = pages.find((p) => p.slug === slug);
+      if (!page) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Page not found: "${slug}". Use list-doc-pages to see available slugs.`
+            }
+          ],
+          isError: true
+        };
+      }
+      const header = page.description ? `# ${page.title}
+
+> ${page.description}
+
+` : `# ${page.title}
+
+`;
+      return {
+        content: [{ type: "text", text: header + page.content }]
+      };
+    }
+  );
+  server.tool(
+    "search-docs",
+    "Full-text search across all DataQueue documentation pages. Returns matching sections with page titles and content excerpts.",
+    {
+      query: zod.z.string().describe('Search query, e.g. "cron scheduling" or "waitForToken"')
+    },
+    async ({ query }) => {
+      const queryTerms = query.toLowerCase().split(/\s+/).filter((t) => t.length > 1);
+      if (queryTerms.length === 0) {
+        return {
+          content: [
+            { type: "text", text: "Please provide a search query." }
+          ],
+          isError: true
+        };
+      }
+      const scored = pages.map((page) => ({
+        page,
+        score: scorePageForQuery(page, queryTerms)
+      })).filter((r) => r.score > 0).sort((a, b) => b.score - a.score).slice(0, 5);
+      if (scored.length === 0) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `No results for "${query}". Try different keywords or use list-doc-pages to browse.`
+            }
+          ]
+        };
+      }
+      const results = scored.map((r) => {
+        const excerpt = extractExcerpt(r.page.content, queryTerms);
+        return `## ${r.page.title} (${r.page.slug})
+
+${r.page.description}
+
+${excerpt}`;
+      });
+      return {
+        content: [{ type: "text", text: results.join("\n\n---\n\n") }]
+      };
+    }
+  );
+  const transport = deps.transport ?? new stdio_js.StdioServerTransport();
+  await server.connect(transport);
+  return server;
+}
+var isDirectRun = process.argv[1] && (process.argv[1].endsWith("/mcp-server.js") || process.argv[1].endsWith("/mcp-server.cjs"));
+if (isDirectRun) {
+  startMcpServer().catch((err) => {
+    console.error("Failed to start MCP server:", err);
+    process.exit(1);
+  });
+}
+
+exports.extractExcerpt = extractExcerpt;
+exports.loadDocsContent = loadDocsContent;
+exports.scorePageForQuery = scorePageForQuery;
+exports.startMcpServer = startMcpServer;
+//# sourceMappingURL=mcp-server.cjs.map
+//# sourceMappingURL=mcp-server.cjs.map

package/dist/mcp-server.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/mcp-server.ts"],"names":["__filename","fileURLToPath","__dirname","path","fs","McpServer","z","StdioServerTransport"],"mappings":"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","file":"mcp-server.cjs","sourcesContent":["#!/usr/bin/env node\n\n/**\n * DataQueue MCP Server — exposes documentation search over stdio.\n * Run via: dataqueue-cli mcp\n */\n\nimport { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';\nimport { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';\nimport { z } from 'zod';\nimport fs from 'fs';\nimport path from 'path';\nimport { fileURLToPath } from 'url';\n\nconst __filename = fileURLToPath(import.meta.url);\nconst __dirname = path.dirname(__filename);\n\ninterface DocPage {\n  slug: string;\n  title: string;\n  description: string;\n  content: string;\n}\n\n/** @internal Loads docs-content.json from the ai/ directory bundled with the package. */\nexport function loadDocsContent(\n  docsPath: string = path.join(__dirname, '../ai/docs-content.json'),\n): DocPage[] {\n  const raw = fs.readFileSync(docsPath, 'utf-8');\n  return JSON.parse(raw) as DocPage[];\n}\n\n/** @internal Scores a doc page against a search query using simple term matching. */\nexport function scorePageForQuery(page: DocPage, queryTerms: string[]): number {\n  const titleLower = page.title.toLowerCase();\n  const descLower = page.description.toLowerCase();\n  const contentLower = page.content.toLowerCase();\n\n  let score = 0;\n  for (const term of queryTerms) {\n    if (titleLower.includes(term)) score += 10;\n    if (descLower.includes(term)) score += 5;\n\n    const contentMatches = contentLower.split(term).length - 1;\n    score += Math.min(contentMatches, 10);\n  }\n  return score;\n}\n\n/** @internal Extracts a relevant excerpt around the first match of any query term. */\nexport function extractExcerpt(\n  content: string,\n  queryTerms: string[],\n  maxLength = 500,\n): string {\n  const lower = content.toLowerCase();\n  let earliestIndex = -1;\n\n  for (const term of queryTerms) {\n    const idx = lower.indexOf(term);\n    if (idx !== -1 && (earliestIndex === -1 || idx < earliestIndex)) {\n      earliestIndex = idx;\n    }\n  }\n\n  if (earliestIndex === -1) {\n    return content.slice(0, maxLength);\n  }\n\n  const start = Math.max(0, earliestIndex - 100);\n  const end = Math.min(content.length, start + maxLength);\n  let excerpt = content.slice(start, end);\n\n  if (start > 0) excerpt = '...' + excerpt;\n  if (end < content.length) excerpt = excerpt + '...';\n\n  return excerpt;\n}\n\n/**\n * Creates and starts the DataQueue MCP server over stdio.\n *\n * @param deps - Injectable dependencies for testing.\n */\nexport async function startMcpServer(\n  deps: {\n    docsPath?: string;\n    transport?: InstanceType<typeof StdioServerTransport>;\n  } = {},\n): Promise<McpServer> {\n  const pages = loadDocsContent(deps.docsPath);\n\n  const server = new McpServer({\n    name: 'dataqueue-docs',\n    version: '1.0.0',\n  });\n\n  server.resource('llms-txt', 'dataqueue://llms.txt', async () => {\n    const llmsPath = path.join(\n      __dirname,\n      '../ai/skills/dataqueue-core/SKILL.md',\n    );\n    let content: string;\n    try {\n      content = fs.readFileSync(llmsPath, 'utf-8');\n    } catch {\n      content = pages\n        .map((p) => `## ${p.title}\\n\\nSlug: ${p.slug}\\n\\n${p.description}`)\n        .join('\\n\\n');\n    }\n    return { contents: [{ uri: 'dataqueue://llms.txt', text: content }] };\n  });\n\n  server.tool(\n    'list-doc-pages',\n    'List all available DataQueue documentation pages with titles and descriptions.',\n    {},\n    async () => {\n      const listing = pages.map((p) => ({\n        slug: p.slug,\n        title: p.title,\n        description: p.description,\n      }));\n      return {\n        content: [\n          { type: 'text' as const, text: JSON.stringify(listing, null, 2) },\n        ],\n      };\n    },\n  );\n\n  server.tool(\n    'get-doc-page',\n    'Fetch a specific DataQueue doc page by slug. Returns full page content as markdown.',\n    {\n      slug: z\n        .string()\n        .describe('The doc page slug, e.g. \"usage/add-job\" or \"api/job-queue\"'),\n    },\n    async ({ slug }) => {\n      const page = pages.find((p) => p.slug === slug);\n      if (!page) {\n        return {\n          content: [\n            {\n              type: 'text' as const,\n              text: `Page not found: \"${slug}\". Use list-doc-pages to see available slugs.`,\n            },\n          ],\n          isError: true,\n        };\n      }\n      const header = page.description\n        ? `# ${page.title}\\n\\n> ${page.description}\\n\\n`\n        : `# ${page.title}\\n\\n`;\n      return {\n        content: [{ type: 'text' as const, text: header + page.content }],\n      };\n    },\n  );\n\n  server.tool(\n    'search-docs',\n    'Full-text search across all DataQueue documentation pages. Returns matching sections with page titles and content excerpts.',\n    {\n      query: z\n        .string()\n        .describe('Search query, e.g. \"cron scheduling\" or \"waitForToken\"'),\n    },\n    async ({ query }) => {\n      const queryTerms = query\n        .toLowerCase()\n        .split(/\\s+/)\n        .filter((t) => t.length > 1);\n\n      if (queryTerms.length === 0) {\n        return {\n          content: [\n            { type: 'text' as const, text: 'Please provide a search query.' },\n          ],\n          isError: true,\n        };\n      }\n\n      const scored = pages\n        .map((page) => ({\n          page,\n          score: scorePageForQuery(page, queryTerms),\n        }))\n        .filter((r) => r.score > 0)\n        .sort((a, b) => b.score - a.score)\n        .slice(0, 5);\n\n      if (scored.length === 0) {\n        return {\n          content: [\n            {\n              type: 'text' as const,\n              text: `No results for \"${query}\". Try different keywords or use list-doc-pages to browse.`,\n            },\n          ],\n        };\n      }\n\n      const results = scored.map((r) => {\n        const excerpt = extractExcerpt(r.page.content, queryTerms);\n        return `## ${r.page.title} (${r.page.slug})\\n\\n${r.page.description}\\n\\n${excerpt}`;\n      });\n\n      return {\n        content: [{ type: 'text' as const, text: results.join('\\n\\n---\\n\\n') }],\n      };\n    },\n  );\n\n  const transport = deps.transport ?? new StdioServerTransport();\n  await server.connect(transport);\n  return server;\n}\n\nconst isDirectRun =\n  process.argv[1] &&\n  (process.argv[1].endsWith('/mcp-server.js') ||\n    process.argv[1].endsWith('/mcp-server.cjs'));\n\nif (isDirectRun) {\n  startMcpServer().catch((err) => {\n    console.error('Failed to start MCP server:', err);\n    process.exit(1);\n  });\n}\n"]}

package/dist/mcp-server.d.cts

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+
+/**
+ * DataQueue MCP Server — exposes documentation search over stdio.
+ * Run via: dataqueue-cli mcp
+ */
+
+interface DocPage {
+    slug: string;
+    title: string;
+    description: string;
+    content: string;
+}
+/** @internal Loads docs-content.json from the ai/ directory bundled with the package. */
+declare function loadDocsContent(docsPath?: string): DocPage[];
+/** @internal Scores a doc page against a search query using simple term matching. */
+declare function scorePageForQuery(page: DocPage, queryTerms: string[]): number;
+/** @internal Extracts a relevant excerpt around the first match of any query term. */
+declare function extractExcerpt(content: string, queryTerms: string[], maxLength?: number): string;
+/**
+ * Creates and starts the DataQueue MCP server over stdio.
+ *
+ * @param deps - Injectable dependencies for testing.
+ */
+declare function startMcpServer(deps?: {
+    docsPath?: string;
+    transport?: InstanceType<typeof StdioServerTransport>;
+}): Promise<McpServer>;
+
+export { extractExcerpt, loadDocsContent, scorePageForQuery, startMcpServer };

package/dist/mcp-server.d.ts

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+
+/**
+ * DataQueue MCP Server — exposes documentation search over stdio.
+ * Run via: dataqueue-cli mcp
+ */
+
+interface DocPage {
+    slug: string;
+    title: string;
+    description: string;
+    content: string;
+}
+/** @internal Loads docs-content.json from the ai/ directory bundled with the package. */
+declare function loadDocsContent(docsPath?: string): DocPage[];
+/** @internal Scores a doc page against a search query using simple term matching. */
+declare function scorePageForQuery(page: DocPage, queryTerms: string[]): number;
+/** @internal Extracts a relevant excerpt around the first match of any query term. */
+declare function extractExcerpt(content: string, queryTerms: string[], maxLength?: number): string;
+/**
+ * Creates and starts the DataQueue MCP server over stdio.
+ *
+ * @param deps - Injectable dependencies for testing.
+ */
+declare function startMcpServer(deps?: {
+    docsPath?: string;
+    transport?: InstanceType<typeof StdioServerTransport>;
+}): Promise<McpServer>;
+
+export { extractExcerpt, loadDocsContent, scorePageForQuery, startMcpServer };

package/dist/mcp-server.js

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+var __filename = fileURLToPath(import.meta.url);
+var __dirname = path.dirname(__filename);
+function loadDocsContent(docsPath = path.join(__dirname, "../ai/docs-content.json")) {
+  const raw = fs.readFileSync(docsPath, "utf-8");
+  return JSON.parse(raw);
+}
+function scorePageForQuery(page, queryTerms) {
+  const titleLower = page.title.toLowerCase();
+  const descLower = page.description.toLowerCase();
+  const contentLower = page.content.toLowerCase();
+  let score = 0;
+  for (const term of queryTerms) {
+    if (titleLower.includes(term)) score += 10;
+    if (descLower.includes(term)) score += 5;
+    const contentMatches = contentLower.split(term).length - 1;
+    score += Math.min(contentMatches, 10);
+  }
+  return score;
+}
+function extractExcerpt(content, queryTerms, maxLength = 500) {
+  const lower = content.toLowerCase();
+  let earliestIndex = -1;
+  for (const term of queryTerms) {
+    const idx = lower.indexOf(term);
+    if (idx !== -1 && (earliestIndex === -1 || idx < earliestIndex)) {
+      earliestIndex = idx;
+    }
+  }
+  if (earliestIndex === -1) {
+    return content.slice(0, maxLength);
+  }
+  const start = Math.max(0, earliestIndex - 100);
+  const end = Math.min(content.length, start + maxLength);
+  let excerpt = content.slice(start, end);
+  if (start > 0) excerpt = "..." + excerpt;
+  if (end < content.length) excerpt = excerpt + "...";
+  return excerpt;
+}
+async function startMcpServer(deps = {}) {
+  const pages = loadDocsContent(deps.docsPath);
+  const server = new McpServer({
+    name: "dataqueue-docs",
+    version: "1.0.0"
+  });
+  server.resource("llms-txt", "dataqueue://llms.txt", async () => {
+    const llmsPath = path.join(
+      __dirname,
+      "../ai/skills/dataqueue-core/SKILL.md"
+    );
+    let content;
+    try {
+      content = fs.readFileSync(llmsPath, "utf-8");
+    } catch {
+      content = pages.map((p) => `## ${p.title}
+
+Slug: ${p.slug}
+
+${p.description}`).join("\n\n");
+    }
+    return { contents: [{ uri: "dataqueue://llms.txt", text: content }] };
+  });
+  server.tool(
+    "list-doc-pages",
+    "List all available DataQueue documentation pages with titles and descriptions.",
+    {},
+    async () => {
+      const listing = pages.map((p) => ({
+        slug: p.slug,
+        title: p.title,
+        description: p.description
+      }));
+      return {
+        content: [
+          { type: "text", text: JSON.stringify(listing, null, 2) }
+        ]
+      };
+    }
+  );
+  server.tool(
+    "get-doc-page",
+    "Fetch a specific DataQueue doc page by slug. Returns full page content as markdown.",
+    {
+      slug: z.string().describe('The doc page slug, e.g. "usage/add-job" or "api/job-queue"')
+    },
+    async ({ slug }) => {
+      const page = pages.find((p) => p.slug === slug);
+      if (!page) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Page not found: "${slug}". Use list-doc-pages to see available slugs.`
+            }
+          ],
+          isError: true
+        };
+      }
+      const header = page.description ? `# ${page.title}
+
+> ${page.description}
+
+` : `# ${page.title}
+
+`;
+      return {
+        content: [{ type: "text", text: header + page.content }]
+      };
+    }
+  );
+  server.tool(
+    "search-docs",
+    "Full-text search across all DataQueue documentation pages. Returns matching sections with page titles and content excerpts.",
+    {
+      query: z.string().describe('Search query, e.g. "cron scheduling" or "waitForToken"')
+    },
+    async ({ query }) => {
+      const queryTerms = query.toLowerCase().split(/\s+/).filter((t) => t.length > 1);
+      if (queryTerms.length === 0) {
+        return {
+          content: [
+            { type: "text", text: "Please provide a search query." }
+          ],
+          isError: true
+        };
+      }
+      const scored = pages.map((page) => ({
+        page,
+        score: scorePageForQuery(page, queryTerms)
+      })).filter((r) => r.score > 0).sort((a, b) => b.score - a.score).slice(0, 5);
+      if (scored.length === 0) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `No results for "${query}". Try different keywords or use list-doc-pages to browse.`
+            }
+          ]
+        };
+      }
+      const results = scored.map((r) => {
+        const excerpt = extractExcerpt(r.page.content, queryTerms);
+        return `## ${r.page.title} (${r.page.slug})
+
+${r.page.description}
+
+${excerpt}`;
+      });
+      return {
+        content: [{ type: "text", text: results.join("\n\n---\n\n") }]
+      };
+    }
+  );
+  const transport = deps.transport ?? new StdioServerTransport();
+  await server.connect(transport);
+  return server;
+}
+var isDirectRun = process.argv[1] && (process.argv[1].endsWith("/mcp-server.js") || process.argv[1].endsWith("/mcp-server.cjs"));
+if (isDirectRun) {
+  startMcpServer().catch((err) => {
+    console.error("Failed to start MCP server:", err);
+    process.exit(1);
+  });
+}
+
+export { extractExcerpt, loadDocsContent, scorePageForQuery, startMcpServer };
+//# sourceMappingURL=mcp-server.js.map
+//# sourceMappingURL=mcp-server.js.map

package/dist/mcp-server.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/mcp-server.ts"],"names":[],"mappings":";;;;;;;;AAcA,IAAM,UAAA,GAAa,aAAA,CAAc,MAAA,CAAA,IAAA,CAAY,GAAG,CAAA;AAChD,IAAM,SAAA,GAAY,IAAA,CAAK,OAAA,CAAQ,UAAU,CAAA;AAUlC,SAAS,gBACd,QAAA,GAAmB,IAAA,CAAK,IAAA,CAAK,SAAA,EAAW,yBAAyB,CAAA,EACtD;AACX,EAAA,MAAM,GAAA,GAAM,EAAA,CAAG,YAAA,CAAa,QAAA,EAAU,OAAO,CAAA;AAC7C,EAAA,OAAO,IAAA,CAAK,MAAM,GAAG,CAAA;AACvB;AAGO,SAAS,iBAAA,CAAkB,MAAe,UAAA,EAA8B;AAC7E,EAAA,MAAM,UAAA,GAAa,IAAA,CAAK,KAAA,CAAM,WAAA,EAAY;AAC1C,EAAA,MAAM,SAAA,GAAY,IAAA,CAAK,WAAA,CAAY,WAAA,EAAY;AAC/C,EAAA,MAAM,YAAA,GAAe,IAAA,CAAK,OAAA,CAAQ,WAAA,EAAY;AAE9C,EAAA,IAAI,KAAA,GAAQ,CAAA;AACZ,EAAA,KAAA,MAAW,QAAQ,UAAA,EAAY;AAC7B,IAAA,IAAI,UAAA,CAAW,QAAA,CAAS,IAAI,CAAA,EAAG,KAAA,IAAS,EAAA;AACxC,IAAA,IAAI,SAAA,CAAU,QAAA,CAAS,IAAI,CAAA,EAAG,KAAA,IAAS,CAAA;AAEvC,IAAA,MAAM,cAAA,GAAiB,YAAA,CAAa,KAAA,CAAM,IAAI,EAAE,MAAA,GAAS,CAAA;AACzD,IAAA,KAAA,IAAS,IAAA,CAAK,GAAA,CAAI,cAAA,EAAgB,EAAE,CAAA;AAAA;AAEtC,EAAA,OAAO,KAAA;AACT;AAGO,SAAS,cAAA,CACd,OAAA,EACA,UAAA,EACA,SAAA,GAAY,GAAA,EACJ;AACR,EAAA,MAAM,KAAA,GAAQ,QAAQ,WAAA,EAAY;AAClC,EAAA,IAAI,aAAA,GAAgB,EAAA;AAEpB,EAAA,KAAA,MAAW,QAAQ,UAAA,EAAY;AAC7B,IAAA,MAAM,GAAA,GAAM,KAAA,CAAM,OAAA,CAAQ,IAAI,CAAA;AAC9B,IAAA,IAAI,GAAA,KAAQ,EAAA,KAAO,aAAA,KAAkB,EAAA,IAAM,MAAM,aAAA,CAAA,EAAgB;AAC/D,MAAA,aAAA,GAAgB,GAAA;AAAA;AAClB;AAGF,EAAA,IAAI,kBAAkB,EAAA,EAAI;AACxB,IAAA,OAAO,OAAA,CAAQ,KAAA,CAAM,CAAA,EAAG,SAAS,CAAA;AAAA;AAGnC,EAAA,MAAM,KAAA,GAAQ,IAAA,CAAK,GAAA,CAAI,CAAA,EAAG,gBAAgB,GAAG,CAAA;AAC7C,EAAA,MAAM,MAAM,IAAA,CAAK,GAAA,CAAI,OAAA,CAAQ,MAAA,EAAQ,QAAQ,SAAS,CAAA;AACtD,EAAA,IAAI,OAAA,GAAU,OAAA,CAAQ,KAAA,CAAM,KAAA,EAAO,GAAG,CAAA;AAEtC,EAAA,IAAI,KAAA,GAAQ,CAAA,EAAG,OAAA,GAAU,KAAA,GAAQ,OAAA;AACjC,EAAA,IAAI,GAAA,GAAM,OAAA,CAAQ,MAAA,EAAQ,OAAA,GAAU,OAAA,GAAU,KAAA;AAE9C,EAAA,OAAO,OAAA;AACT;AAOA,eAAsB,cAAA,CACpB,IAAA,GAGI,EAAC,EACe;AACpB,EAAA,MAAM,KAAA,GAAQ,eAAA,CAAgB,IAAA,CAAK,QAAQ,CAAA;AAE3C,EAAA,MAAM,MAAA,GAAS,IAAI,SAAA,CAAU;AAAA,IAC3B,IAAA,EAAM,gBAAA;AAAA,IACN,OAAA,EAAS;AAAA,GACV,CAAA;AAED,EAAA,MAAA,CAAO,QAAA,CAAS,UAAA,EAAY,sBAAA,EAAwB,YAAY;AAC9D,IAAA,MAAM,WAAW,IAAA,CAAK,IAAA;AAAA,MACpB,SAAA;AAAA,MACA;AAAA,KACF;AACA,IAAA,IAAI,OAAA;AACJ,IAAA,IAAI;AACF,MAAA,OAAA,GAAU,EAAA,CAAG,YAAA,CAAa,QAAA,EAAU,OAAO,CAAA;AAAA,KAC7C,CAAA,MAAQ;AACN,MAAA,OAAA,GAAU,MACP,GAAA,CAAI,CAAC,CAAA,KAAM,CAAA,GAAA,EAAM,EAAE,KAAK;;AAAA,MAAA,EAAa,EAAE,IAAI;;AAAA,EAAO,CAAA,CAAE,WAAW,CAAA,CAAE,CAAA,CACjE,KAAK,MAAM,CAAA;AAAA;AAEhB,IAAA,OAAO,EAAE,UAAU,CAAC,EAAE,KAAK,sBAAA,EAAwB,IAAA,EAAM,OAAA,EAAS,CAAA,EAAE;AAAA,GACrE,CAAA;AAED,EAAA,MAAA,CAAO,IAAA;AAAA,IACL,gBAAA;AAAA,IACA,gFAAA;AAAA,IACA,EAAC;AAAA,IACD,YAAY;AACV,MAAA,MAAM,OAAA,GAAU,KAAA,CAAM,GAAA,CAAI,CAAC,CAAA,MAAO;AAAA,QAChC,MAAM,CAAA,CAAE,IAAA;AAAA,QACR,OAAO,CAAA,CAAE,KAAA;AAAA,QACT,aAAa,CAAA,CAAE;AAAA,OACjB,CAAE,CAAA;AACF,MAAA,OAAO;AAAA,QACL,OAAA,EAAS;AAAA,UACP,EAAE,MAAM,MAAA,EAAiB,IAAA,EAAM,KAAK,SAAA,CAAU,OAAA,EAAS,IAAA,EAAM,CAAC,CAAA;AAAE;AAClE,OACF;AAAA;AACF,GACF;AAEA,EAAA,MAAA,CAAO,IAAA;AAAA,IACL,cAAA;AAAA,IACA,qFAAA;AAAA,IACA;AAAA,MACE,IAAA,EAAM,CAAA,CACH,MAAA,EAAO,CACP,SAAS,4DAA4D;AAAA,KAC1E;AAAA,IACA,OAAO,EAAE,IAAA,EAAK,KAAM;AAClB,MAAA,MAAM,OAAO,KAAA,CAAM,IAAA,CAAK,CAAC,CAAA,KAAM,CAAA,CAAE,SAAS,IAAI,CAAA;AAC9C,MAAA,IAAI,CAAC,IAAA,EAAM;AACT,QAAA,OAAO;AAAA,UACL,OAAA,EAAS;AAAA,YACP;AAAA,cACE,IAAA,EAAM,MAAA;AAAA,cACN,IAAA,EAAM,oBAAoB,IAAI,CAAA,6CAAA;AAAA;AAChC,WACF;AAAA,UACA,OAAA,EAAS;AAAA,SACX;AAAA;AAEF,MAAA,MAAM,MAAA,GAAS,IAAA,CAAK,WAAA,GAChB,CAAA,EAAA,EAAK,KAAK,KAAK;;AAAA,EAAA,EAAS,KAAK,WAAW;;AAAA,CAAA,GACxC,CAAA,EAAA,EAAK,KAAK,KAAK;;AAAA,CAAA;AACnB,MAAA,OAAO;AAAA,QACL,OAAA,EAAS,CAAC,EAAE,IAAA,EAAM,QAAiB,IAAA,EAAM,MAAA,GAAS,IAAA,CAAK,OAAA,EAAS;AAAA,OAClE;AAAA;AACF,GACF;AAEA,EAAA,MAAA,CAAO,IAAA;AAAA,IACL,aAAA;AAAA,IACA,6HAAA;AAAA,IACA;AAAA,MACE,KAAA,EAAO,CAAA,CACJ,MAAA,EAAO,CACP,SAAS,wDAAwD;AAAA,KACtE;AAAA,IACA,OAAO,EAAE,KAAA,EAAM,KAAM;AACnB,MAAA,MAAM,UAAA,GAAa,KAAA,CAChB,WAAA,EAAY,CACZ,KAAA,CAAM,KAAK,CAAA,CACX,MAAA,CAAO,CAAC,CAAA,KAAM,CAAA,CAAE,MAAA,GAAS,CAAC,CAAA;AAE7B,MAAA,IAAI,UAAA,CAAW,WAAW,CAAA,EAAG;AAC3B,QAAA,OAAO;AAAA,UACL,OAAA,EAAS;AAAA,YACP,EAAE,IAAA,EAAM,MAAA,EAAiB,IAAA,EAAM,gCAAA;AAAiC,WAClE;AAAA,UACA,OAAA,EAAS;AAAA,SACX;AAAA;AAGF,MAAA,MAAM,MAAA,GAAS,KAAA,CACZ,GAAA,CAAI,CAAC,IAAA,MAAU;AAAA,QACd,IAAA;AAAA,QACA,KAAA,EAAO,iBAAA,CAAkB,IAAA,EAAM,UAAU;AAAA,OAC3C,CAAE,EACD,MAAA,CAAO,CAAC,MAAM,CAAA,CAAE,KAAA,GAAQ,CAAC,CAAA,CACzB,IAAA,CAAK,CAAC,CAAA,EAAG,CAAA,KAAM,EAAE,KAAA,GAAQ,CAAA,CAAE,KAAK,CAAA,CAChC,KAAA,CAAM,GAAG,CAAC,CAAA;AAEb,MAAA,IAAI,MAAA,CAAO,WAAW,CAAA,EAAG;AACvB,QAAA,OAAO;AAAA,UACL,OAAA,EAAS;AAAA,YACP;AAAA,cACE,IAAA,EAAM,MAAA;AAAA,cACN,IAAA,EAAM,mBAAmB,KAAK,CAAA,0DAAA;AAAA;AAChC;AACF,SACF;AAAA;AAGF,MAAA,MAAM,OAAA,GAAU,MAAA,CAAO,GAAA,CAAI,CAAC,CAAA,KAAM;AAChC,QAAA,MAAM,OAAA,GAAU,cAAA,CAAe,CAAA,CAAE,IAAA,CAAK,SAAS,UAAU,CAAA;AACzD,QAAA,OAAO,MAAM,CAAA,CAAE,IAAA,CAAK,KAAK,CAAA,EAAA,EAAK,CAAA,CAAE,KAAK,IAAI,CAAA;;AAAA,EAAQ,CAAA,CAAE,KAAK,WAAW;;AAAA,EAAO,OAAO,CAAA,CAAA;AAAA,OAClF,CAAA;AAED,MAAA,OAAO;AAAA,QACL,OAAA,EAAS,CAAC,EAAE,IAAA,EAAM,MAAA,EAAiB,MAAM,OAAA,CAAQ,IAAA,CAAK,aAAa,CAAA,EAAG;AAAA,OACxE;AAAA;AACF,GACF;AAEA,EAAA,MAAM,SAAA,GAAY,IAAA,CAAK,SAAA,IAAa,IAAI,oBAAA,EAAqB;AAC7D,EAAA,MAAM,MAAA,CAAO,QAAQ,SAAS,CAAA;AAC9B,EAAA,OAAO,MAAA;AACT;AAEA,IAAM,cACJ,OAAA,CAAQ,IAAA,CAAK,CAAC,CAAA,KACb,QAAQ,IAAA,CAAK,CAAC,CAAA,CAAE,QAAA,CAAS,gBAAgB,CAAA,IACxC,OAAA,CAAQ,KAAK,CAAC,CAAA,CAAE,SAAS,iBAAiB,CAAA,CAAA;AAE9C,IAAI,WAAA,EAAa;AACf,EAAA,cAAA,EAAe,CAAE,KAAA,CAAM,CAAC,GAAA,KAAQ;AAC9B,IAAA,OAAA,CAAQ,KAAA,CAAM,+BAA+B,GAAG,CAAA;AAChD,IAAA,OAAA,CAAQ,KAAK,CAAC,CAAA;AAAA,GACf,CAAA;AACH","file":"mcp-server.js","sourcesContent":["#!/usr/bin/env node\n\n/**\n * DataQueue MCP Server — exposes documentation search over stdio.\n * Run via: dataqueue-cli mcp\n */\n\nimport { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';\nimport { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';\nimport { z } from 'zod';\nimport fs from 'fs';\nimport path from 'path';\nimport { fileURLToPath } from 'url';\n\nconst __filename = fileURLToPath(import.meta.url);\nconst __dirname = path.dirname(__filename);\n\ninterface DocPage {\n  slug: string;\n  title: string;\n  description: string;\n  content: string;\n}\n\n/** @internal Loads docs-content.json from the ai/ directory bundled with the package. */\nexport function loadDocsContent(\n  docsPath: string = path.join(__dirname, '../ai/docs-content.json'),\n): DocPage[] {\n  const raw = fs.readFileSync(docsPath, 'utf-8');\n  return JSON.parse(raw) as DocPage[];\n}\n\n/** @internal Scores a doc page against a search query using simple term matching. */\nexport function scorePageForQuery(page: DocPage, queryTerms: string[]): number {\n  const titleLower = page.title.toLowerCase();\n  const descLower = page.description.toLowerCase();\n  const contentLower = page.content.toLowerCase();\n\n  let score = 0;\n  for (const term of queryTerms) {\n    if (titleLower.includes(term)) score += 10;\n    if (descLower.includes(term)) score += 5;\n\n    const contentMatches = contentLower.split(term).length - 1;\n    score += Math.min(contentMatches, 10);\n  }\n  return score;\n}\n\n/** @internal Extracts a relevant excerpt around the first match of any query term. */\nexport function extractExcerpt(\n  content: string,\n  queryTerms: string[],\n  maxLength = 500,\n): string {\n  const lower = content.toLowerCase();\n  let earliestIndex = -1;\n\n  for (const term of queryTerms) {\n    const idx = lower.indexOf(term);\n    if (idx !== -1 && (earliestIndex === -1 || idx < earliestIndex)) {\n      earliestIndex = idx;\n    }\n  }\n\n  if (earliestIndex === -1) {\n    return content.slice(0, maxLength);\n  }\n\n  const start = Math.max(0, earliestIndex - 100);\n  const end = Math.min(content.length, start + maxLength);\n  let excerpt = content.slice(start, end);\n\n  if (start > 0) excerpt = '...' + excerpt;\n  if (end < content.length) excerpt = excerpt + '...';\n\n  return excerpt;\n}\n\n/**\n * Creates and starts the DataQueue MCP server over stdio.\n *\n * @param deps - Injectable dependencies for testing.\n */\nexport async function startMcpServer(\n  deps: {\n    docsPath?: string;\n    transport?: InstanceType<typeof StdioServerTransport>;\n  } = {},\n): Promise<McpServer> {\n  const pages = loadDocsContent(deps.docsPath);\n\n  const server = new McpServer({\n    name: 'dataqueue-docs',\n    version: '1.0.0',\n  });\n\n  server.resource('llms-txt', 'dataqueue://llms.txt', async () => {\n    const llmsPath = path.join(\n      __dirname,\n      '../ai/skills/dataqueue-core/SKILL.md',\n    );\n    let content: string;\n    try {\n      content = fs.readFileSync(llmsPath, 'utf-8');\n    } catch {\n      content = pages\n        .map((p) => `## ${p.title}\\n\\nSlug: ${p.slug}\\n\\n${p.description}`)\n        .join('\\n\\n');\n    }\n    return { contents: [{ uri: 'dataqueue://llms.txt', text: content }] };\n  });\n\n  server.tool(\n    'list-doc-pages',\n    'List all available DataQueue documentation pages with titles and descriptions.',\n    {},\n    async () => {\n      const listing = pages.map((p) => ({\n        slug: p.slug,\n        title: p.title,\n        description: p.description,\n      }));\n      return {\n        content: [\n          { type: 'text' as const, text: JSON.stringify(listing, null, 2) },\n        ],\n      };\n    },\n  );\n\n  server.tool(\n    'get-doc-page',\n    'Fetch a specific DataQueue doc page by slug. Returns full page content as markdown.',\n    {\n      slug: z\n        .string()\n        .describe('The doc page slug, e.g. \"usage/add-job\" or \"api/job-queue\"'),\n    },\n    async ({ slug }) => {\n      const page = pages.find((p) => p.slug === slug);\n      if (!page) {\n        return {\n          content: [\n            {\n              type: 'text' as const,\n              text: `Page not found: \"${slug}\". Use list-doc-pages to see available slugs.`,\n            },\n          ],\n          isError: true,\n        };\n      }\n      const header = page.description\n        ? `# ${page.title}\\n\\n> ${page.description}\\n\\n`\n        : `# ${page.title}\\n\\n`;\n      return {\n        content: [{ type: 'text' as const, text: header + page.content }],\n      };\n    },\n  );\n\n  server.tool(\n    'search-docs',\n    'Full-text search across all DataQueue documentation pages. Returns matching sections with page titles and content excerpts.',\n    {\n      query: z\n        .string()\n        .describe('Search query, e.g. \"cron scheduling\" or \"waitForToken\"'),\n    },\n    async ({ query }) => {\n      const queryTerms = query\n        .toLowerCase()\n        .split(/\\s+/)\n        .filter((t) => t.length > 1);\n\n      if (queryTerms.length === 0) {\n        return {\n          content: [\n            { type: 'text' as const, text: 'Please provide a search query.' },\n          ],\n          isError: true,\n        };\n      }\n\n      const scored = pages\n        .map((page) => ({\n          page,\n          score: scorePageForQuery(page, queryTerms),\n        }))\n        .filter((r) => r.score > 0)\n        .sort((a, b) => b.score - a.score)\n        .slice(0, 5);\n\n      if (scored.length === 0) {\n        return {\n          content: [\n            {\n              type: 'text' as const,\n              text: `No results for \"${query}\". Try different keywords or use list-doc-pages to browse.`,\n            },\n          ],\n        };\n      }\n\n      const results = scored.map((r) => {\n        const excerpt = extractExcerpt(r.page.content, queryTerms);\n        return `## ${r.page.title} (${r.page.slug})\\n\\n${r.page.description}\\n\\n${excerpt}`;\n      });\n\n      return {\n        content: [{ type: 'text' as const, text: results.join('\\n\\n---\\n\\n') }],\n      };\n    },\n  );\n\n  const transport = deps.transport ?? new StdioServerTransport();\n  await server.connect(transport);\n  return server;\n}\n\nconst isDirectRun =\n  process.argv[1] &&\n  (process.argv[1].endsWith('/mcp-server.js') ||\n    process.argv[1].endsWith('/mcp-server.cjs'));\n\nif (isDirectRun) {\n  startMcpServer().catch((err) => {\n    console.error('Failed to start MCP server:', err);\n    process.exit(1);\n  });\n}\n"]}

package/migrations/1781200000005_add_retry_config_to_job_queue.sql

@@ -0,0 +1,17 @@
+-- Up Migration
+ALTER TABLE job_queue ADD COLUMN IF NOT EXISTS retry_delay INT;
+ALTER TABLE job_queue ADD COLUMN IF NOT EXISTS retry_backoff BOOLEAN;
+ALTER TABLE job_queue ADD COLUMN IF NOT EXISTS retry_delay_max INT;
+
+ALTER TABLE cron_schedules ADD COLUMN IF NOT EXISTS retry_delay INT;
+ALTER TABLE cron_schedules ADD COLUMN IF NOT EXISTS retry_backoff BOOLEAN;
+ALTER TABLE cron_schedules ADD COLUMN IF NOT EXISTS retry_delay_max INT;
+
+-- Down Migration
+ALTER TABLE job_queue DROP COLUMN IF EXISTS retry_delay;
+ALTER TABLE job_queue DROP COLUMN IF EXISTS retry_backoff;
+ALTER TABLE job_queue DROP COLUMN IF EXISTS retry_delay_max;
+
+ALTER TABLE cron_schedules DROP COLUMN IF EXISTS retry_delay;
+ALTER TABLE cron_schedules DROP COLUMN IF EXISTS retry_backoff;
+ALTER TABLE cron_schedules DROP COLUMN IF EXISTS retry_delay_max;

package/migrations/1781200000006_add_output_to_job_queue.sql

@@ -0,0 +1,3 @@
+-- Add output column to job_queue for storing handler results as JSONB.
+-- Up Migration
+ALTER TABLE job_queue ADD COLUMN IF NOT EXISTS output JSONB DEFAULT NULL;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nicnocquee/dataqueue",
-  "version": "1.33.0",
+  "version": "1.35.0-beta.20260224075710",
   "description": "PostgreSQL or Redis-backed job queue for Node.js applications with support for serverless environments",
   "type": "module",
   "main": "dist/index.js",
@@ -14,9 +14,11 @@
   "files": [
     "dist/",
     "src/",
-    "migrations/"
+    "migrations/",
+    "ai/"
   ],
   "scripts": {
+    "prebuild": "npx tsx ai/build-docs-content.ts && npx tsx ai/build-llms-full.ts",
     "build": "tsup",
     "ci": "npm run build && npm run check-format && npm run check-exports && npm run lint && npm run test",
     "lint": "tsc",
@@ -24,6 +26,7 @@
     "format": "prettier --write .",
     "check-format": "prettier --check .",
     "check-exports": "attw --pack .",
+    "build:docs-content": "npx tsx ai/build-docs-content.ts && npx tsx ai/build-llms-full.ts",
     "dev": "tsup --watch",
     "migrate": "node-pg-migrate -d $PG_DATAQUEUE_DATABASE -m ./migrations"
   },
@@ -43,9 +46,11 @@
     "directory": "packages/dataqueue"
   },
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
     "croner": "^10.0.1",
     "pg": "^8.0.0",
-    "pg-connection-string": "^2.9.1"
+    "pg-connection-string": "^2.9.1",
+    "zod": "^3.25.67"
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.2",
@@ -76,6 +81,7 @@
     }
   },
   "bin": {
-    "dataqueue-cli": "./cli.cjs"
+    "dataqueue-cli": "./cli.cjs",
+    "dataqueue-mcp": "./dist/mcp-server.js"
   }
 }

package/src/backend.ts

@@ -11,6 +11,7 @@ import {
   EditCronScheduleOptions,
   WaitpointRecord,
   CreateTokenOptions,
+  AddJobOptions,
 } from './types.js';
 
 /**
@@ -39,6 +40,9 @@ export interface JobUpdates {
   runAt?: Date | null;
   timeoutMs?: number | null;
   tags?: string[] | null;
+  retryDelay?: number | null;
+  retryBackoff?: boolean | null;
+  retryDelayMax?: number | null;
 }
 
 /**
@@ -58,6 +62,9 @@ export interface CronScheduleInput {
   timezone: string;
   allowOverlap: boolean;
   nextRunAt: Date | null;
+  retryDelay: number | null;
+  retryBackoff: boolean | null;
+  retryDelayMax: number | null;
 }
 
 /**
@@ -68,11 +75,34 @@ export interface CronScheduleInput {
 export interface QueueBackend {
   // ── Job CRUD ──────────────────────────────────────────────────────────
 
-  /** Add a job and return its numeric ID. */
+  /**
+   * Add a job and return its numeric ID.
+   *
+   * @param job - Job configuration.
+   * @param options - Optional. Pass `{ db }` to run the INSERT on an external
+   *   client (e.g., inside a transaction). PostgreSQL only.
+   */
   addJob<PayloadMap, T extends JobType<PayloadMap>>(
     job: JobOptions<PayloadMap, T>,
+    options?: AddJobOptions,
   ): Promise<number>;
 
+  /**
+   * Add multiple jobs in a single operation and return their IDs.
+   *
+   * IDs are returned in the same order as the input array.
+   * Each job may independently have an `idempotencyKey`; duplicates
+   * resolve to the existing job's ID without creating a new row.
+   *
+   * @param jobs - Array of job configurations.
+   * @param options - Optional. Pass `{ db }` to run the INSERTs on an external
+   *   client (e.g., inside a transaction). PostgreSQL only.
+   */
+  addJobs<PayloadMap, T extends JobType<PayloadMap>>(
+    jobs: JobOptions<PayloadMap, T>[],
+    options?: AddJobOptions,
+  ): Promise<number[]>;
+
   /** Get a single job by ID, or null if not found. */
   getJob<PayloadMap, T extends JobType<PayloadMap>>(
     id: number,
@@ -118,8 +148,8 @@ export interface QueueBackend {
     jobType?: string | string[],
   ): Promise<JobRecord<PayloadMap, T>[]>;
 
-  /** Mark a job as completed. */
-  completeJob(jobId: number): Promise<void>;
+  /** Mark a job as completed, optionally storing output data. */
+  completeJob(jobId: number, output?: unknown): Promise<void>;
 
   /** Mark a job as failed with error info and schedule retry. */
   failJob(
@@ -165,6 +195,9 @@ export interface QueueBackend {
   /** Update the progress percentage (0-100) for a job. */
   updateProgress(jobId: number, progress: number): Promise<void>;
 
+  /** Update the output data for a job. Best-effort: should not throw. */
+  updateOutput(jobId: number, output: unknown): Promise<void>;
+
   // ── Events ────────────────────────────────────────────────────────────
 
   /** Record a job event. Should not throw. */