@nicnocquee/dataqueue 1.24.0 → 1.26.0-beta.20260223195940

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":"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","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/1751131910825_add_timeout_seconds_to_job_queue.sql

@@ -1,6 +1,6 @@
 -- Up Migration: Add timeout_ms and failure_reason to job_queue
-ALTER TABLE job_queue ADD COLUMN timeout_ms INT;
-ALTER TABLE job_queue ADD COLUMN failure_reason VARCHAR;
+ALTER TABLE job_queue ADD COLUMN IF NOT EXISTS timeout_ms INT;
+ALTER TABLE job_queue ADD COLUMN IF NOT EXISTS failure_reason VARCHAR;
 
 -- Down Migration: Remove timeout_ms and failure_reason from job_queue
 ALTER TABLE job_queue DROP COLUMN IF EXISTS timeout_ms;

package/migrations/1751186053000_add_job_events_table.sql

@@ -7,15 +7,19 @@ CREATE TABLE IF NOT EXISTS job_events (
   metadata JSONB
 );
 
-ALTER TABLE job_events ADD CONSTRAINT fk_job_events_job_queue FOREIGN KEY (job_id) REFERENCES job_queue(id) ON DELETE CASCADE;
-CREATE INDEX idx_job_events_job_id ON job_events(job_id);
-CREATE INDEX idx_job_events_event_type ON job_events(event_type);
+DO $$ BEGIN
+  IF NOT EXISTS (SELECT 1 FROM pg_constraint WHERE conname = 'fk_job_events_job_queue') THEN
+    ALTER TABLE job_events ADD CONSTRAINT fk_job_events_job_queue FOREIGN KEY (job_id) REFERENCES job_queue(id) ON DELETE CASCADE;
+  END IF;
+END $$;
+CREATE INDEX IF NOT EXISTS idx_job_events_job_id ON job_events(job_id);
+CREATE INDEX IF NOT EXISTS idx_job_events_event_type ON job_events(event_type);
 
-ALTER TABLE job_queue ADD COLUMN completed_at TIMESTAMPTZ;
-ALTER TABLE job_queue ADD COLUMN started_at TIMESTAMPTZ;
-ALTER TABLE job_queue ADD COLUMN last_retried_at TIMESTAMPTZ;
-ALTER TABLE job_queue ADD COLUMN last_failed_at TIMESTAMPTZ;
-ALTER TABLE job_queue ADD COLUMN last_cancelled_at TIMESTAMPTZ;
+ALTER TABLE job_queue ADD COLUMN IF NOT EXISTS completed_at TIMESTAMPTZ;
+ALTER TABLE job_queue ADD COLUMN IF NOT EXISTS started_at TIMESTAMPTZ;
+ALTER TABLE job_queue ADD COLUMN IF NOT EXISTS last_retried_at TIMESTAMPTZ;
+ALTER TABLE job_queue ADD COLUMN IF NOT EXISTS last_failed_at TIMESTAMPTZ;
+ALTER TABLE job_queue ADD COLUMN IF NOT EXISTS last_cancelled_at TIMESTAMPTZ;
 
 -- Down Migration
 DROP INDEX IF EXISTS idx_job_events_event_type;

package/migrations/1751984773000_add_tags_to_job_queue.sql

@@ -1,5 +1,5 @@
 -- Up Migration
-ALTER TABLE job_queue ADD COLUMN tags TEXT[];
+ALTER TABLE job_queue ADD COLUMN IF NOT EXISTS tags TEXT[];
 CREATE INDEX IF NOT EXISTS idx_job_queue_tags ON job_queue USING GIN (tags);
 
 -- Down Migration

package/migrations/1765809419000_add_force_kill_on_timeout_to_job_queue.sql

@@ -1,5 +1,5 @@
 -- Up Migration: Add force_kill_on_timeout to job_queue
-ALTER TABLE job_queue ADD COLUMN force_kill_on_timeout BOOLEAN DEFAULT FALSE;
+ALTER TABLE job_queue ADD COLUMN IF NOT EXISTS force_kill_on_timeout BOOLEAN DEFAULT FALSE;
 
 -- Down Migration: Remove force_kill_on_timeout from job_queue
 ALTER TABLE job_queue DROP COLUMN IF EXISTS force_kill_on_timeout;

package/migrations/1771100000000_add_idempotency_key_to_job_queue.sql

@@ -0,0 +1,7 @@
+-- Up Migration: Add idempotency_key to job_queue
+ALTER TABLE job_queue ADD COLUMN IF NOT EXISTS idempotency_key VARCHAR(255);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_job_queue_idempotency_key ON job_queue (idempotency_key) WHERE idempotency_key IS NOT NULL;
+
+-- Down Migration: Remove idempotency_key from job_queue
+DROP INDEX IF EXISTS idx_job_queue_idempotency_key;
+ALTER TABLE job_queue DROP COLUMN IF EXISTS idempotency_key;

package/migrations/1781200000000_add_wait_support.sql

@@ -0,0 +1,12 @@
+-- Up Migration: Add wait support columns to job_queue
+ALTER TABLE job_queue ADD COLUMN IF NOT EXISTS wait_until TIMESTAMPTZ DEFAULT NULL;
+ALTER TABLE job_queue ADD COLUMN IF NOT EXISTS wait_token_id VARCHAR(255) DEFAULT NULL;
+ALTER TABLE job_queue ADD COLUMN IF NOT EXISTS step_data JSONB DEFAULT '{}';
+
+CREATE INDEX IF NOT EXISTS idx_job_queue_wait_until ON job_queue (wait_until) WHERE status = 'waiting' AND wait_until IS NOT NULL;
+
+-- Down Migration: Remove wait support columns from job_queue
+DROP INDEX IF EXISTS idx_job_queue_wait_until;
+ALTER TABLE job_queue DROP COLUMN IF EXISTS wait_until;
+ALTER TABLE job_queue DROP COLUMN IF EXISTS wait_token_id;
+ALTER TABLE job_queue DROP COLUMN IF EXISTS step_data;

package/migrations/1781200000001_create_waitpoints_table.sql

@@ -0,0 +1,18 @@
+-- Up Migration: Create waitpoints table for token-based waits
+CREATE TABLE IF NOT EXISTS waitpoints (
+  id VARCHAR(255) PRIMARY KEY,
+  job_id INT REFERENCES job_queue(id) ON DELETE CASCADE,
+  status VARCHAR(20) NOT NULL DEFAULT 'waiting',
+  output JSONB DEFAULT NULL,
+  timeout_at TIMESTAMPTZ DEFAULT NULL,
+  created_at TIMESTAMPTZ DEFAULT NOW(),
+  completed_at TIMESTAMPTZ DEFAULT NULL,
+  tags TEXT[] DEFAULT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_waitpoints_job_id ON waitpoints(job_id);
+CREATE INDEX IF NOT EXISTS idx_waitpoints_status ON waitpoints(status);
+CREATE INDEX IF NOT EXISTS idx_waitpoints_timeout ON waitpoints(timeout_at) WHERE status = 'waiting';
+
+-- Down Migration: Drop waitpoints table
+DROP TABLE IF EXISTS waitpoints;

package/migrations/1781200000002_add_performance_indexes.sql

@@ -0,0 +1,34 @@
+-- Up Migration: Add composite and partial indexes for performance at scale
+
+-- Composite partial index for the getNextBatch claim query.
+-- Covers pending jobs ordered by priority then age.
+-- The run_at <= NOW() filter is applied at query time (NOW() is not IMMUTABLE).
+CREATE INDEX IF NOT EXISTS idx_job_queue_claimable
+  ON job_queue (priority DESC, created_at ASC)
+  WHERE status = 'pending';
+
+-- Partial index for failed jobs eligible for retry (used in getNextBatch).
+CREATE INDEX IF NOT EXISTS idx_job_queue_failed_retry
+  ON job_queue (next_attempt_at ASC)
+  WHERE status = 'failed' AND next_attempt_at IS NOT NULL;
+
+-- Index for reclaimStuckJobs: processing jobs ordered by lock age.
+CREATE INDEX IF NOT EXISTS idx_job_queue_stuck
+  ON job_queue (locked_at ASC)
+  WHERE status = 'processing';
+
+-- Index for cleanupOldJobs: completed jobs by update time.
+CREATE INDEX IF NOT EXISTS idx_job_queue_cleanup
+  ON job_queue (updated_at ASC)
+  WHERE status = 'completed';
+
+-- Index for job_events cleanup and time-based queries.
+CREATE INDEX IF NOT EXISTS idx_job_events_created_at
+  ON job_events (created_at ASC);
+
+-- Down Migration
+DROP INDEX IF EXISTS idx_job_queue_claimable;
+DROP INDEX IF EXISTS idx_job_queue_failed_retry;
+DROP INDEX IF EXISTS idx_job_queue_stuck;
+DROP INDEX IF EXISTS idx_job_queue_cleanup;
+DROP INDEX IF EXISTS idx_job_events_created_at;

package/migrations/1781200000003_add_progress_to_job_queue.sql

@@ -0,0 +1,7 @@
+-- Add progress column to job_queue for tracking job completion percentage (0-100).
+
+-- Up Migration
+ALTER TABLE job_queue ADD COLUMN IF NOT EXISTS progress INTEGER DEFAULT NULL;
+
+-- Down Migration
+ALTER TABLE job_queue DROP COLUMN IF EXISTS progress;

package/migrations/1781200000004_create_cron_schedules_table.sql

@@ -0,0 +1,33 @@
+-- Create cron_schedules table for recurring job definitions
+
+-- Up Migration
+CREATE TABLE IF NOT EXISTS cron_schedules (
+  id SERIAL PRIMARY KEY,
+  schedule_name VARCHAR(255) NOT NULL UNIQUE,
+  cron_expression VARCHAR(255) NOT NULL,
+  job_type VARCHAR(255) NOT NULL,
+  payload JSONB NOT NULL DEFAULT '{}',
+  max_attempts INT DEFAULT 3,
+  priority INT DEFAULT 0,
+  timeout_ms INT,
+  force_kill_on_timeout BOOLEAN DEFAULT FALSE,
+  tags TEXT[],
+  timezone VARCHAR(100) DEFAULT 'UTC',
+  allow_overlap BOOLEAN DEFAULT FALSE,
+  status VARCHAR(50) DEFAULT 'active',
+  last_enqueued_at TIMESTAMPTZ,
+  last_job_id INT,
+  next_run_at TIMESTAMPTZ,
+  created_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
+  updated_at TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX IF NOT EXISTS idx_cron_schedules_status ON cron_schedules(status);
+CREATE INDEX IF NOT EXISTS idx_cron_schedules_next_run_at ON cron_schedules(next_run_at);
+CREATE INDEX IF NOT EXISTS idx_cron_schedules_name ON cron_schedules(schedule_name);
+
+-- Down Migration
+DROP INDEX IF EXISTS idx_cron_schedules_name;
+DROP INDEX IF EXISTS idx_cron_schedules_next_run_at;
+DROP INDEX IF EXISTS idx_cron_schedules_status;
+DROP TABLE IF EXISTS cron_schedules;