@nicnocquee/dataqueue 1.33.0 → 1.34.0

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nicnocquee/dataqueue",
-  "version": "1.33.0",
+  "version": "1.34.0",
   "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/cli.test.ts

@@ -23,6 +23,10 @@ function makeDeps() {
     spawnSyncImpl: vi.fn(() => makeSpawnSyncReturns(0)),
     migrationsDir: '/migrations',
     runInitImpl: vi.fn(),
+    runInstallSkillsImpl: vi.fn(),
+    runInstallRulesImpl: vi.fn(async () => {}),
+    runInstallMcpImpl: vi.fn(async () => {}),
+    startMcpServerImpl: vi.fn(async () => ({}) as any),
   } satisfies CliDeps;
 }
 
@@ -138,4 +142,65 @@ describe('runCli', () => {
     runCli(['node', 'cli.js', 'migrate'], deps);
     expect(deps.exit).toHaveBeenCalledWith(1);
   });
+
+  it('routes install-skills command to runInstallSkillsImpl', () => {
+    // Act
+    runCli(['node', 'cli.js', 'install-skills'], deps);
+
+    // Assert
+    expect(deps.runInstallSkillsImpl).toHaveBeenCalledWith(
+      expect.objectContaining({
+        log: deps.log,
+        error: deps.error,
+        exit: deps.exit,
+      }),
+    );
+  });
+
+  it('routes install-rules command to runInstallRulesImpl', () => {
+    // Act
+    runCli(['node', 'cli.js', 'install-rules'], deps);
+
+    // Assert
+    expect(deps.runInstallRulesImpl).toHaveBeenCalledWith(
+      expect.objectContaining({
+        log: deps.log,
+        error: deps.error,
+        exit: deps.exit,
+      }),
+    );
+  });
+
+  it('routes install-mcp command to runInstallMcpImpl', () => {
+    // Act
+    runCli(['node', 'cli.js', 'install-mcp'], deps);
+
+    // Assert
+    expect(deps.runInstallMcpImpl).toHaveBeenCalledWith(
+      expect.objectContaining({
+        log: deps.log,
+        error: deps.error,
+        exit: deps.exit,
+      }),
+    );
+  });
+
+  it('routes mcp command to startMcpServerImpl', () => {
+    // Act
+    runCli(['node', 'cli.js', 'mcp'], deps);
+
+    // Assert
+    expect(deps.startMcpServerImpl).toHaveBeenCalled();
+  });
+
+  it('shows new commands in usage output', () => {
+    // Act
+    runCli(['node', 'cli.js'], deps);
+
+    // Assert
+    expect(deps.log).toHaveBeenCalledWith('  dataqueue-cli install-skills');
+    expect(deps.log).toHaveBeenCalledWith('  dataqueue-cli install-rules');
+    expect(deps.log).toHaveBeenCalledWith('  dataqueue-cli install-mcp');
+    expect(deps.log).toHaveBeenCalledWith('  dataqueue-cli mcp');
+  });
 });

package/src/cli.ts

@@ -3,6 +3,13 @@ import { spawnSync, SpawnSyncReturns } from 'child_process';
 import path from 'path';
 import { fileURLToPath } from 'url';
 import { InitDeps, runInit } from './init-command.js';
+import {
+  runInstallSkills,
+  InstallSkillsDeps,
+} from './install-skills-command.js';
+import { runInstallRules, InstallRulesDeps } from './install-rules-command.js';
+import { runInstallMcp, InstallMcpDeps } from './install-mcp-command.js';
+import { startMcpServer } from './mcp-server.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
@@ -15,6 +22,13 @@ export interface CliDeps {
   migrationsDir?: string;
   initDeps?: InitDeps;
   runInitImpl?: (deps?: InitDeps) => void;
+  installSkillsDeps?: InstallSkillsDeps;
+  runInstallSkillsImpl?: (deps?: InstallSkillsDeps) => void;
+  installRulesDeps?: InstallRulesDeps;
+  runInstallRulesImpl?: (deps?: InstallRulesDeps) => Promise<void>;
+  installMcpDeps?: InstallMcpDeps;
+  runInstallMcpImpl?: (deps?: InstallMcpDeps) => Promise<void>;
+  startMcpServerImpl?: typeof startMcpServer;
 }
 
 export function runCli(
@@ -27,19 +41,27 @@ export function runCli(
     migrationsDir = path.join(__dirname, '../migrations'),
     initDeps,
     runInitImpl = runInit,
+    installSkillsDeps,
+    runInstallSkillsImpl = runInstallSkills,
+    installRulesDeps,
+    runInstallRulesImpl = runInstallRules,
+    installMcpDeps,
+    runInstallMcpImpl = runInstallMcp,
+    startMcpServerImpl = startMcpServer,
   }: CliDeps = {},
 ): void {
   const [, , command, ...restArgs] = argv;
 
-  /**
-   * Prints CLI usage and exits with non-zero code.
-   */
   function printUsage() {
     log('Usage:');
     log(
       '  dataqueue-cli migrate [--envPath <path>] [-s <schema> | --schema <schema>]',
     );
     log('  dataqueue-cli init');
+    log('  dataqueue-cli install-skills');
+    log('  dataqueue-cli install-rules');
+    log('  dataqueue-cli install-mcp');
+    log('  dataqueue-cli mcp');
     log('');
     log('Options for migrate:');
     log(
@@ -49,24 +71,13 @@ export function runCli(
       '  -s, --schema <schema>  Set the schema to use (passed to node-pg-migrate)',
     );
     log('');
-    log('Notes:');
+    log('AI tooling commands:');
+    log('  install-skills     Install DataQueue skill files for AI assistants');
+    log('  install-rules      Install DataQueue agent rules for AI clients');
     log(
-      '  - The PG_DATAQUEUE_DATABASE environment variable must be set to your Postgres connection string.',
-    );
-    log(
-      '  - For managed Postgres (e.g., DigitalOcean) with SSL, set PGSSLMODE=require and PGSSLROOTCERT to your CA .crt file.',
-    );
-    log(
-      '    Example: PGSSLMODE=require NODE_EXTRA_CA_CERTS=/absolute/path/to/ca.crt PG_DATAQUEUE_DATABASE=... npx dataqueue-cli migrate',
-    );
-    log('');
-    log('Notes for init:');
-    log(
-      '  - Supports both Next.js App Router and Pages Router (prefers App Router if both exist).',
-    );
-    log(
-      '  - Scaffolds endpoint, cron.sh, queue placeholder, and package.json entries.',
+      '  install-mcp        Configure the DataQueue MCP server for AI clients',
     );
+    log('  mcp                Start the DataQueue MCP server (stdio)');
     exit(1);
   }
 
@@ -115,6 +126,32 @@ export function runCli(
       exit,
       ...initDeps,
     });
+  } else if (command === 'install-skills') {
+    runInstallSkillsImpl({
+      log,
+      error,
+      exit,
+      ...installSkillsDeps,
+    });
+  } else if (command === 'install-rules') {
+    runInstallRulesImpl({
+      log,
+      error,
+      exit,
+      ...installRulesDeps,
+    });
+  } else if (command === 'install-mcp') {
+    runInstallMcpImpl({
+      log,
+      error,
+      exit,
+      ...installMcpDeps,
+    });
+  } else if (command === 'mcp') {
+    startMcpServerImpl().catch((err) => {
+      error('Failed to start MCP server:', err);
+      exit(1);
+    });
   } else {
     printUsage();
   }

package/src/install-mcp-command.test.ts

@@ -0,0 +1,216 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import {
+  runInstallMcp,
+  upsertMcpConfig,
+  InstallMcpDeps,
+} from './install-mcp-command.js';
+
+describe('upsertMcpConfig', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('creates new config file when it does not exist', () => {
+    // Setup
+    const deps = {
+      existsSync: vi.fn(() => false),
+      readFileSync: vi.fn(),
+      writeFileSync: vi.fn(),
+    };
+
+    // Act
+    upsertMcpConfig(
+      '/path/mcp.json',
+      'dataqueue',
+      { command: 'npx', args: ['dataqueue-cli', 'mcp'] },
+      deps,
+    );
+
+    // Assert
+    const written = JSON.parse(deps.writeFileSync.mock.calls[0][1] as string);
+    expect(written.mcpServers.dataqueue).toEqual({
+      command: 'npx',
+      args: ['dataqueue-cli', 'mcp'],
+    });
+  });
+
+  it('adds to existing config without overwriting other servers', () => {
+    // Setup
+    const existing = JSON.stringify({
+      mcpServers: { other: { command: 'other' } },
+    });
+    const deps = {
+      existsSync: vi.fn(() => true),
+      readFileSync: vi.fn(() => existing),
+      writeFileSync: vi.fn(),
+    };
+
+    // Act
+    upsertMcpConfig(
+      '/path/mcp.json',
+      'dataqueue',
+      { command: 'npx', args: ['dataqueue-cli', 'mcp'] },
+      deps,
+    );
+
+    // Assert
+    const written = JSON.parse(deps.writeFileSync.mock.calls[0][1] as string);
+    expect(written.mcpServers.other).toEqual({ command: 'other' });
+    expect(written.mcpServers.dataqueue).toEqual({
+      command: 'npx',
+      args: ['dataqueue-cli', 'mcp'],
+    });
+  });
+
+  it('overwrites existing dataqueue entry', () => {
+    // Setup
+    const existing = JSON.stringify({
+      mcpServers: { dataqueue: { command: 'old' } },
+    });
+    const deps = {
+      existsSync: vi.fn(() => true),
+      readFileSync: vi.fn(() => existing),
+      writeFileSync: vi.fn(),
+    };
+
+    // Act
+    upsertMcpConfig('/path/mcp.json', 'dataqueue', { command: 'new' }, deps);
+
+    // Assert
+    const written = JSON.parse(deps.writeFileSync.mock.calls[0][1] as string);
+    expect(written.mcpServers.dataqueue).toEqual({ command: 'new' });
+  });
+
+  it('handles malformed JSON in existing file', () => {
+    // Setup
+    const deps = {
+      existsSync: vi.fn(() => true),
+      readFileSync: vi.fn(() => 'not json'),
+      writeFileSync: vi.fn(),
+    };
+
+    // Act
+    upsertMcpConfig('/path/mcp.json', 'dataqueue', { command: 'npx' }, deps);
+
+    // Assert
+    const written = JSON.parse(deps.writeFileSync.mock.calls[0][1] as string);
+    expect(written.mcpServers.dataqueue).toEqual({ command: 'npx' });
+  });
+});
+
+describe('runInstallMcp', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  function makeDeps(overrides: Partial<InstallMcpDeps> = {}): InstallMcpDeps {
+    return {
+      log: vi.fn(),
+      error: vi.fn(),
+      exit: vi.fn(),
+      cwd: '/project',
+      readFileSync: vi.fn(() => '{}'),
+      writeFileSync: vi.fn(),
+      mkdirSync: vi.fn(),
+      existsSync: vi.fn(() => false),
+      ...overrides,
+    };
+  }
+
+  it('installs MCP config for Cursor (option 1)', async () => {
+    // Setup
+    const deps = makeDeps({ selectedClient: '1' });
+
+    // Act
+    await runInstallMcp(deps);
+
+    // Assert
+    expect(deps.mkdirSync).toHaveBeenCalledWith('/project/.cursor', {
+      recursive: true,
+    });
+    const written = JSON.parse(
+      (deps.writeFileSync as ReturnType<typeof vi.fn>).mock
+        .calls[0][1] as string,
+    );
+    expect(written.mcpServers.dataqueue.command).toBe('npx');
+    expect(written.mcpServers.dataqueue.args).toEqual(['dataqueue-cli', 'mcp']);
+  });
+
+  it('installs MCP config for Claude Code (option 2)', async () => {
+    // Setup
+    const deps = makeDeps({ selectedClient: '2' });
+
+    // Act
+    await runInstallMcp(deps);
+
+    // Assert
+    expect(deps.writeFileSync).toHaveBeenCalledWith(
+      '/project/.mcp.json',
+      expect.any(String),
+    );
+  });
+
+  it('installs MCP config for VS Code (option 3)', async () => {
+    // Setup
+    const deps = makeDeps({ selectedClient: '3' });
+
+    // Act
+    await runInstallMcp(deps);
+
+    // Assert
+    expect(deps.mkdirSync).toHaveBeenCalledWith('/project/.vscode', {
+      recursive: true,
+    });
+    expect(deps.writeFileSync).toHaveBeenCalledWith(
+      expect.stringContaining('.vscode/mcp.json'),
+      expect.any(String),
+    );
+  });
+
+  it('exits with error for invalid choice', async () => {
+    // Setup
+    const deps = makeDeps({ selectedClient: '99' });
+
+    // Act
+    await runInstallMcp(deps);
+
+    // Assert
+    expect(deps.error).toHaveBeenCalledWith(
+      expect.stringContaining('Invalid choice'),
+    );
+    expect(deps.exit).toHaveBeenCalledWith(1);
+  });
+
+  it('handles install errors', async () => {
+    // Setup
+    const deps = makeDeps({
+      selectedClient: '1',
+      writeFileSync: vi.fn(() => {
+        throw new Error('permission denied');
+      }),
+    });
+
+    // Act
+    await runInstallMcp(deps);
+
+    // Assert
+    expect(deps.error).toHaveBeenCalledWith(
+      'Failed to install MCP config:',
+      expect.any(Error),
+    );
+    expect(deps.exit).toHaveBeenCalledWith(1);
+  });
+
+  it('logs done message on success', async () => {
+    // Setup
+    const deps = makeDeps({ selectedClient: '1' });
+
+    // Act
+    await runInstallMcp(deps);
+
+    // Assert
+    expect(deps.log).toHaveBeenCalledWith(
+      expect.stringContaining('npx dataqueue-cli mcp'),
+    );
+  });
+});