regent-code 3.0.0

package/mcp/index.js

@@ -0,0 +1,805 @@
+import fs from 'fs';
+import path from 'path';
+import { pathToFileURL } from 'url';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ErrorCode,
+  GetPromptRequestSchema,
+  ListPromptsRequestSchema,
+  ListToolsRequestSchema,
+  McpError,
+} from '@modelcontextprotocol/sdk/types.js';
+import { OpenCode } from '@opencode-ai/client';
+import { Service } from '@opencode-ai/client/service';
+
+import {
+  MAX_DISPATCH_ITEMS,
+  MAX_STRING_LENGTH,
+  MAX_ID_LENGTH,
+  MAX_DISPATCHES_PER_WINDOW,
+  DISPATCH_WINDOW_MS,
+  withRetry,
+  evidenceFreshness,
+  recordEvidence,
+  markEvidenceVerified,
+  evidenceForScope,
+  redactSecrets,
+  isSensitiveFocusPath,
+  parseSubagentTextResponse,
+  unwrapData,
+  sessionFileChanges,
+  workerSessionIds,
+  dispatchRateLimit,
+  circuitIsOpen,
+  recordCircuitResult,
+  toContent,
+  structuredBlockedResult,
+  TOOL_INPUTS,
+} from './shared.js';
+
+import { readPackagePrompts, renderPrompt } from './prompts.js';
+
+const version = '3.0.0';
+
+// ── OpenCode client (lazy singleton) ─────────────────────────
+let clientPromise = null;
+
+/**
+ * Resolve a connection to the local OpenCode background service and wrap it as
+ * a client. Kept as a singleton for the lifetime of the MCP process.
+ * @returns {Promise<ReturnType<typeof OpenCode.make>>}
+ */
+async function getClient() {
+  if (clientPromise) return clientPromise;
+  clientPromise = (async () => {
+    try {
+      const endpoint = await Service.ensure();
+      return OpenCode.make({
+        baseUrl: endpoint.url,
+        headers: Service.headers(endpoint),
+      });
+    } catch (err) {
+      clientPromise = null;
+      const cause = /** @type {any} */ (err);
+      throw new Error(
+        `Cannot connect to local OpenCode service: ${cause?.message || String(cause)}`,
+        { cause: err },
+      );
+    }
+  })();
+  return clientPromise;
+}
+
+// ── Worker agent resolution (ported from the plugin) ─────────
+function normalizeAgents(result) {
+  const data = unwrapData(result);
+  if (Array.isArray(data)) return data;
+  if (Array.isArray(data?.agents)) return data.agents;
+  return null;
+}
+
+function agentMode(agent) {
+  return agent?.mode;
+}
+
+function isVisibleAgent(agent) {
+  return Boolean(agent?.id) && agent.hidden !== true && agent.disabled !== true;
+}
+
+function isChildCapableAgent(agent) {
+  return isVisibleAgent(agent) && ['subagent', 'all'].includes(agentMode(agent));
+}
+
+function isUnavailableAgentError(err) {
+  const message = (err?.message || String(err)).toLowerCase();
+  return (
+    message.includes('not found') ||
+    message.includes('unavailable') ||
+    message.includes('invalid agent') ||
+    message.includes('agent not')
+  );
+}
+
+/**
+ * @param {ReturnType<typeof OpenCode.make>} client
+ * @param {{ workerAgent?: string }} [options]
+ * @returns {Promise<(requestedAgent?: string) => Promise<{ ok: true, agents: string[], automatic: boolean } | { ok: false, error: string }>>}
+ */
+async function createWorkerResolver(client, options = {}) {
+  let catalog = null;
+  try {
+    catalog = normalizeAgents(await client.agent.list());
+  } catch {
+    catalog = null;
+  }
+
+  const findAgent = async (id) => {
+    const fromCatalog = catalog?.find((agent) => agent.id === id);
+    if (fromCatalog) return fromCatalog;
+    if (catalog !== null) return undefined;
+    try {
+      return unwrapData(await client.agent.get({ agentID: id }));
+    } catch {
+      return undefined;
+    }
+  };
+
+  /**
+   * @param {string} id
+   * @param {string} [label]
+   * @returns {Promise<{ ok: true, agents: string[], automatic: boolean } | { ok: false, error: string }>}
+   */
+  const validate = async (id, label = 'agent') => {
+    const agent = await findAgent(id);
+    if (!agent || !isVisibleAgent(agent)) {
+      return { ok: false, error: `${label} "${id}" is unavailable` };
+    }
+    if (!isChildCapableAgent(agent)) {
+      return {
+        ok: false,
+        error: `${label} "${id}" is primary-only and cannot be used for subagent dispatch`,
+      };
+    }
+    return { ok: true, agents: [id], automatic: false };
+  };
+
+  /** @type {(requestedAgent?: string) => Promise<{ ok: true, agents: string[], automatic: boolean } | { ok: false, error: string }>} */
+  const resolveWorker = async (requestedAgent = '') => {
+    const requested = typeof requestedAgent === 'string' ? requestedAgent.trim() : requestedAgent;
+    if (requested) return validate(requested);
+
+    const configuredWorker =
+      typeof options.workerAgent === 'string' ? options.workerAgent.trim() : '';
+    if (configuredWorker) return validate(configuredWorker, 'workerAgent');
+
+    if (catalog === null) {
+      // `general` is a documented built-in. It is the only safe fallback when
+      // the server cannot inspect project agent definitions.
+      return { ok: true, agents: ['general'], automatic: false };
+    }
+
+    const candidates = [];
+    if (isChildCapableAgent(catalog.find((agent) => agent.id === 'regent-general'))) {
+      candidates.push('regent-general');
+    }
+    const configuredGeneral = catalog.find((agent) => agent.id === 'general');
+    if (!configuredGeneral || isChildCapableAgent(configuredGeneral)) {
+      candidates.push('general');
+    }
+    for (const agent of catalog) {
+      if (isChildCapableAgent(agent) && !candidates.includes(agent.id)) {
+        candidates.push(agent.id);
+      }
+    }
+
+    if (candidates.length === 0) {
+      return { ok: false, error: 'No visible child-capable worker agent is available' };
+    }
+    return { ok: true, agents: candidates, automatic: true };
+  };
+
+  return resolveWorker;
+}
+
+// ── Shared subagent dispatch (ported from the plugin) ─────────
+/**
+ * @param {{ task: string, context: string, expected_output: string, id?: string, agent?: string }} args
+ * @param {ReturnType<typeof OpenCode.make>} client
+ * @param {(requestedAgent?: string) => Promise<{ ok: true, agents: string[], automatic: boolean } | { ok: false, error: string }>} resolveWorker
+ * @returns {Promise<{ status: string, output: string, concerns: string[], files_changed: string[], session_id?: string }>}
+ */
+async function dispatchSubagent(client, resolveWorker, args, taskId = '') {
+  /** @type {Array<[string, string, number]>} */
+  const inputChecks = [
+    [args.task, 'task', MAX_STRING_LENGTH],
+    [args.context, 'context', MAX_STRING_LENGTH],
+    [args.expected_output, 'expected_output', MAX_STRING_LENGTH],
+    [taskId, 'id', MAX_ID_LENGTH],
+  ];
+  for (const [value, label, limit] of inputChecks) {
+    if (typeof value !== 'string' || value.length > limit) {
+      return structuredBlockedResult(`${label} is too long (limit ${limit} characters)`);
+    }
+  }
+
+  if (args.agent !== undefined && typeof args.agent !== 'string') {
+    return structuredBlockedResult('agent must be a string');
+  }
+  if (typeof args.agent === 'string' && args.agent.length > MAX_ID_LENGTH) {
+    return structuredBlockedResult(`agent is too long (limit ${MAX_ID_LENGTH} characters)`);
+  }
+
+  const key = 'mcp';
+  const directory = process.cwd();
+  let session;
+
+  try {
+    const selection = await resolveWorker(args.agent);
+    if (!selection.ok) return structuredBlockedResult(selection.error);
+    if (!dispatchRateLimit(key)) {
+      return structuredBlockedResult(
+        `dispatch rate limit exceeded (${MAX_DISPATCHES_PER_WINDOW} dispatches per ${DISPATCH_WINDOW_MS / 1000}s)`,
+      );
+    }
+
+    const title = args.task;
+    for (let index = 0; index < selection.agents.length; index++) {
+      const agent = selection.agents[index];
+      try {
+        const createInput = { title, agent, location: { directory } };
+        const sessionResult = await withRetry(() => client.session.create(createInput));
+        session = unwrapData(sessionResult);
+        if (session?.id) break;
+      } catch (err) {
+        if (
+          !selection.automatic ||
+          index === selection.agents.length - 1 ||
+          !isUnavailableAgentError(err)
+        ) {
+          throw err;
+        }
+      }
+    }
+
+    if (!session?.id) throw new Error('session create returned no session');
+    workerSessionIds.add(session.id);
+
+    const prompt = [
+      '## Task',
+      args.task,
+      '',
+      '## Context',
+      args.context,
+      '',
+      '## Expected Output',
+      args.expected_output,
+      '',
+      'Complete the task. When you finish, provide:',
+      '- summary: What you did',
+      '- status: one of: done, blocked, needs_context, done_with_concerns',
+      '- concerns: Any issues encountered (if status is done_with_concerns)',
+      '- files_changed: List of files created or modified',
+      '',
+      'If you need more context, say NEEDS_CONTEXT and explain what you need.',
+      'If you cannot complete the task, say BLOCKED and explain why.',
+    ].join('\n');
+
+    const result = await withRetry(() =>
+      client.session.generate({ sessionID: session.id, prompt }),
+    );
+    const message = unwrapData(result);
+    const output = typeof message?.text === 'string' ? message.text : '';
+    const parsed = parseSubagentTextResponse(output);
+    const { status, concerns, filesChanged } = parsed;
+
+    if (filesChanged.length > 0) {
+      sessionFileChanges.set(session.id, {
+        taskId,
+        files: filesChanged,
+        timestamp: Date.now(),
+        verified: false,
+      });
+      recordEvidence(session.id, filesChanged, directory);
+    }
+
+    return { status, output, concerns, files_changed: filesChanged, session_id: session.id };
+  } catch (err) {
+    const message = redactSecrets(err instanceof Error ? err.message : String(err)).slice(0, 500);
+    return {
+      status: 'blocked',
+      output: `Subagent error: ${message}`,
+      concerns: [],
+      files_changed: [],
+      session_id: session?.id,
+    };
+  }
+}
+
+// ── Explore (ported from the plugin; directory from cwd) ─────
+function runExplore(query, focus) {
+  const worktree = process.cwd();
+  let result = `Codebase exploration for: ${query}\n\n`;
+
+  try {
+    const items = fs.readdirSync(worktree, { withFileTypes: true });
+    result += '## Top-level contents\n';
+    for (const item of items) {
+      if (item.name.startsWith('.') && item.name !== '.gitignore') continue;
+      result += `${item.isDirectory() ? '/' : ''} ${item.name}\n`;
+    }
+    result += '\n';
+  } catch {
+    /* ignore read errors */
+  }
+
+  try {
+    const srcDir = path.join(worktree, 'src');
+    if (fs.existsSync(srcDir)) {
+      result += '## src/ directory\n';
+      /** @param {string} dir @param {number} depth */
+      const walk = (dir, depth) => {
+        if (depth > 3) return;
+        const entries = fs.readdirSync(dir, { withFileTypes: true });
+        for (const entry of entries) {
+          if (entry.name.startsWith('.')) continue;
+          const full = path.join(dir, entry.name);
+          const indent = '  '.repeat(depth);
+          if (entry.isDirectory()) {
+            result += `${indent}${entry.name}/\n`;
+            walk(full, depth + 1);
+          } else {
+            result += `${indent}${entry.name}\n`;
+          }
+        }
+      };
+      walk(srcDir, 0);
+    }
+  } catch {
+    /* ignore read errors */
+  }
+
+  if (focus) {
+    const worktreeRoot = path.resolve(worktree);
+    const focusPath = path.resolve(worktree, focus);
+    const lexicalInside =
+      focusPath.startsWith(worktreeRoot + path.sep) || focusPath === worktreeRoot;
+    if (!lexicalInside) {
+      result += `\n## Focus: ${focus}\n(path outside project directory)\n`;
+    } else if (isSensitiveFocusPath(focusPath, worktreeRoot)) {
+      result += `\n## Focus: ${focus}\n(access denied: sensitive path)\n`;
+    } else {
+      let realRoot = worktreeRoot;
+      let realFocus = focusPath;
+      try {
+        realRoot = fs.realpathSync(worktreeRoot);
+        realFocus = fs.realpathSync(focusPath);
+      } catch {
+        /* fall back to lexical paths */
+      }
+      const inside =
+        (realFocus.startsWith(realRoot + path.sep) || realFocus === realRoot) &&
+        (focusPath.startsWith(worktreeRoot + path.sep) || focusPath === worktreeRoot);
+      if (!inside) {
+        result += `\n## Focus: ${focus}\n(path outside project directory)\n`;
+      } else if (isSensitiveFocusPath(realFocus, realRoot)) {
+        result += `\n## Focus: ${focus}\n(access denied: sensitive path)\n`;
+      } else if (fs.existsSync(focusPath)) {
+        const stat = fs.statSync(focusPath);
+        if (stat.isDirectory()) {
+          const items = fs.readdirSync(focusPath);
+          result += items.join('\n') + '\n';
+        } else {
+          try {
+            const content = redactSecrets(fs.readFileSync(focusPath, 'utf8').slice(0, 3000));
+            result += '```\n' + content + '\n```\n';
+          } catch {
+            result += '(path not found)\n';
+          }
+        }
+      } else {
+        result += '(path not found)\n';
+      }
+    }
+  }
+
+  return { structure: result, summary: `Explored ${query}` };
+}
+
+// ── Verify (ported from the plugin) ──────────────────────────
+function runVerify(requirements, implementationContext, sessionId) {
+  if (
+    requirements == null ||
+    implementationContext == null ||
+    typeof requirements !== 'string' ||
+    typeof implementationContext !== 'string'
+  ) {
+    const scopeEvidence = evidenceForScope();
+    return {
+      compliant: false,
+      requirements_met: [],
+      requirements_unmet: [],
+      extras_built: [],
+      evidence_gate: {
+        unverified_changes: scopeEvidence.filter((entry) => !entry.verified).length,
+        freshness: evidenceFreshness(scopeEvidence),
+      },
+      summary: 'Missing required arguments: provide "requirements" and "implementation_context"',
+    };
+  }
+
+  /** @param {string} s */
+  const getKeyBigrams = (s) => {
+    const words = s
+      .toLowerCase()
+      .split(/\s+/)
+      .filter((w) => w.length > 3);
+    const bigrams = /** @type {string[]} */ ([]);
+    for (let i = 0; i < words.length - 1; i++) {
+      bigrams.push(words[i] + ' ' + words[i + 1]);
+    }
+    return bigrams;
+  };
+
+  /** @param {string} s */
+  const getKeyUnigrams = (s) =>
+    s
+      .toLowerCase()
+      .split(/\s+/)
+      .filter((w) => w.length > 3);
+
+  /** @param {string} s */
+  const stripCheckbox = (s) =>
+    s
+      .replace(/^[-*]\s*\[\s*[x ]?\s*\]\s*/i, '')
+      .replace(/^[-*\d+.]\s+/, '')
+      .trim();
+
+  const reqs = requirements
+    .split('\n')
+    .map((r) => stripCheckbox(r))
+    .filter((r) => r.length > 2 && !r.startsWith('#') && !r.startsWith('```') && !r.endsWith(':'));
+
+  const impl = implementationContext.toLowerCase();
+
+  const met = [];
+  const unmet = [];
+
+  for (const req of reqs) {
+    const reqBigrams = getKeyBigrams(req);
+    const reqUnigrams = getKeyUnigrams(req);
+    let found;
+    if (reqBigrams.length > 0) {
+      found = reqBigrams.some((b) => impl.includes(b));
+    } else {
+      found = reqUnigrams.some((w) => impl.includes(w));
+    }
+    if (found) {
+      met.push(req);
+    } else {
+      unmet.push(req);
+    }
+  }
+
+  const implLines = implementationContext
+    .split('\n')
+    .map((l) => stripCheckbox(l))
+    .filter((l) => l.length > 3 && !l.startsWith('#') && !l.startsWith('```'));
+
+  const extras = implLines.filter((line) => {
+    const lineLower = line.toLowerCase();
+    return !reqs.some((req) => {
+      const reqBigrams = getKeyBigrams(req);
+      const reqUnigrams = getKeyUnigrams(req);
+      if (reqBigrams.length > 0) {
+        return reqBigrams.some((b) => lineLower.includes(b));
+      }
+      return reqUnigrams.some((w) => lineLower.includes(w));
+    });
+  });
+
+  // No session lineage in MCP: verify marks evidence verified if a session_id
+  // matches a worker session this process created and dispatched.
+  let verificationNote = null;
+  if (sessionId) {
+    if (sessionFileChanges.has(sessionId)) {
+      markEvidenceVerified(sessionId);
+    } else {
+      verificationNote =
+        'session_id does not match any worker session; evidence was not marked verified';
+    }
+  }
+
+  const scopeEvidence = evidenceForScope();
+  const unverifiedCount = scopeEvidence.filter((entry) => !entry.verified).length;
+  const freshness = evidenceFreshness(scopeEvidence);
+
+  const implWords = implementationContext.split(/\s+/).length;
+  const lowConfidence = unmet.length > 0 && implWords < 20;
+
+  const warningParts = [];
+  if (unverifiedCount > 0) {
+    warningParts.push(`${unverifiedCount} file change(s) not followed by verification command`);
+  }
+  if (freshness.stale > 0) {
+    warningParts.push(
+      `${freshness.stale} verified change(s) went stale (evidence no longer matches files on disk)`,
+    );
+  }
+
+  return {
+    compliant: unmet.length === 0 && unverifiedCount === 0 && freshness.stale === 0,
+    requirements_met: met,
+    requirements_unmet: unmet,
+    extras_built: extras,
+    verification_note: verificationNote,
+    evidence_gate: {
+      unverified_changes: unverifiedCount,
+      total_changes: scopeEvidence.length,
+      freshness,
+      warning: warningParts.length > 0 ? warningParts.join('; ') : null,
+    },
+    confidence_assessment: lowConfidence
+      ? 'low — sparse implementation context may hide unverified requirements'
+      : 'adequate',
+    recommend_delegation:
+      unmet.length > 0
+        ? 'Consider delegating each unmet requirement to a subagent for detailed verification'
+        : null,
+    summary: `${met.length}/${reqs.length} requirements met, ${extras.length} extras flagged, ${unverifiedCount} unverified changes`,
+  };
+}
+
+// ── Tool definitions ─────────────────────────────────────────
+const TOOL_DEFINITIONS = [
+  {
+    name: 'delegate',
+    description:
+      'Dispatch a single focused task to a subagent. Returns structured result with status (done, blocked, needs_context). Use when a task is well-defined and self-contained. Requires a local OpenCode service to be running.',
+    inputSchema: TOOL_INPUTS.delegate,
+  },
+  {
+    name: 'delegate_many',
+    description:
+      'Dispatch multiple independent tasks to subagents in PARALLEL. All tasks run simultaneously via Promise.all with work-stealing. Use for tasks that have no dependencies on each other. Requires a local OpenCode service.',
+    inputSchema: TOOL_INPUTS.delegate_many,
+  },
+  {
+    name: 'research',
+    description:
+      'Research multiple questions in parallel by dispatching independent research subagents. Each question gets a focused agent. Returns combined findings with synthesis. Requires a local OpenCode service.',
+    inputSchema: TOOL_INPUTS.research,
+  },
+  {
+    name: 'explore',
+    description:
+      'Analyze the project codebase to answer structural questions. Uses file operations to understand directory layout, key files, and patterns. Call this before planning to understand what exists. Operates relative to the MCP server working directory.',
+    inputSchema: TOOL_INPUTS.explore,
+  },
+  {
+    name: 'changed-files',
+    description:
+      'View files changed by subagent dispatches made through this MCP server. Returns a list of what each dispatched worker session touched.',
+    inputSchema: TOOL_INPUTS['changed-files'],
+  },
+  {
+    name: 'verify',
+    description:
+      'Compare implementation against requirements. Returns structured pass/fail per requirement, flags extras (YAGNI). Includes an evidence gate that reports unverified or stale file changes. Use after execution to check if work meets the plan.',
+    inputSchema: TOOL_INPUTS.verify,
+  },
+];
+
+// ── Server construction ──────────────────────────────────────
+let promptsCache = null;
+
+/**
+ * Build the Regent MCP server with tools and prompts registered.
+ * Exported for tests to drive over an in-memory transport.
+ * @returns {Server}
+ */
+export function createRegentServer() {
+  const server = new Server(
+    { name: 'regent-code', version },
+    { capabilities: { tools: {}, prompts: {} } },
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOL_DEFINITIONS }));
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args = {} } = request.params;
+    try {
+      switch (name) {
+        case 'delegate': {
+          const client = await getClient();
+          const resolveWorker = await createWorkerResolver(client, {
+            workerAgent: process.env.REGENT_WORKER_AGENT,
+          });
+          const result = await dispatchSubagent(client, resolveWorker, /** @type {any} */ (args));
+          return toContent(result);
+        }
+        case 'delegate_many': {
+          if (!Array.isArray(args.tasks) || args.tasks.length > MAX_DISPATCH_ITEMS) {
+            return toContent({
+              results: [],
+              summary: { total: 0, completed: 0, failed: 1, needs_context: 0 },
+              _error: `delegate_many supports at most ${MAX_DISPATCH_ITEMS} tasks`,
+            });
+          }
+          if (circuitIsOpen('mcp')) {
+            return toContent({
+              results: [],
+              summary: { total: 0, completed: 0, failed: 1, needs_context: 0 },
+              _circuit_open: true,
+              _warning:
+                'Circuit breaker open after repeated delegate_many failures. One half-open recovery attempt is allowed; escalate to Inspector if it fails.',
+            });
+          }
+          const client = await getClient();
+          const resolveWorker = await createWorkerResolver(client, {
+            workerAgent: process.env.REGENT_WORKER_AGENT,
+          });
+          const queue = [...args.tasks];
+          const results = [];
+          /** @returns {Promise<void>} */
+          async function worker() {
+            while (queue.length > 0) {
+              const t = queue.shift();
+              if (!t) break;
+              const result = await dispatchSubagent(
+                client,
+                resolveWorker,
+                /** @type {any} */ (t),
+                t.id,
+              );
+              results.push({ id: t.id, ...result });
+            }
+          }
+          const workerCount = Math.min(queue.length, 10);
+          await Promise.all(Array.from({ length: workerCount }, () => worker()));
+          const failed = results.filter((r) => r.status === 'blocked').length;
+          recordCircuitResult('mcp', results.length > 0 && failed === 0);
+          return toContent({
+            results,
+            summary: {
+              total: results.length,
+              completed: results.filter(
+                (r) => r.status === 'done' || r.status === 'done_with_concerns',
+              ).length,
+              failed,
+              needs_context: results.filter((r) => r.status === 'needs_context').length,
+            },
+          });
+        }
+        case 'research': {
+          if (!Array.isArray(args.questions) || args.questions.length > MAX_DISPATCH_ITEMS) {
+            return toContent({
+              findings: [],
+              synthesis: `research supports at most ${MAX_DISPATCH_ITEMS} questions per call`,
+              _error: `research supports at most ${MAX_DISPATCH_ITEMS} questions per call`,
+            });
+          }
+          const client = await getClient();
+          const resolveWorker = await createWorkerResolver(client, {
+            workerAgent: process.env.REGENT_WORKER_AGENT,
+          });
+          const results = await Promise.all(
+            args.questions.map(async (q) => {
+              const task = `Research this question thoroughly:\n${q.question}`;
+              const taskContext = q.scope
+                ? `Scope: ${q.scope}`
+                : 'Be thorough and concise. Return key findings, data points, and sources.';
+              const result = await dispatchSubagent(
+                client,
+                resolveWorker,
+                {
+                  task,
+                  context: taskContext,
+                  expected_output: 'Key findings, data points, sources, and recommendations',
+                },
+                q.id,
+              );
+              return { id: q.id, question: q.question, ...result };
+            }),
+          );
+          const completed = results.filter(
+            (r) => r.status === 'done' || r.status === 'done_with_concerns',
+          );
+          const blocked = results.filter((r) => r.status === 'blocked');
+          const needsContext = results.filter((r) => r.status === 'needs_context');
+          const allOutputs = completed.map((r) => r.output || '');
+          const commonThemes = [];
+          if (allOutputs.length >= 2) {
+            const words = {};
+            for (const output of allOutputs) {
+              const seen = new Set();
+              for (const w of output
+                .toLowerCase()
+                .split(/\s+/)
+                .filter((w) => w.length > 5)) {
+                if (!seen.has(w)) {
+                  seen.add(w);
+                  words[w] = (words[w] || 0) + 1;
+                }
+              }
+            }
+            for (const [word, count] of Object.entries(words)) {
+              if (count >= Math.ceil(allOutputs.length / 2)) {
+                commonThemes.push(word);
+              }
+            }
+          }
+          const summaryParts = [];
+          if (completed.length > 0) {
+            summaryParts.push(`Addressed: ${completed.map((r) => r.question).join(', ')}`);
+          }
+          if (blocked.length > 0) {
+            summaryParts.push(`Blocked: ${blocked.map((r) => r.question).join(', ')}`);
+          }
+          if (needsContext.length > 0) {
+            summaryParts.push(`Needs context: ${needsContext.map((r) => r.question).join(', ')}`);
+          }
+          if (commonThemes.length > 0) {
+            summaryParts.push(`Common themes: ${commonThemes.slice(0, 10).join(', ')}`);
+          }
+          return toContent({
+            findings: results,
+            synthesis:
+              summaryParts.length > 0
+                ? summaryParts.join('. ') + '.'
+                : 'No research results returned.',
+          });
+        }
+        case 'explore':
+          return toContent(runExplore(args.query, args.focus));
+        case 'changed-files': {
+          const filters = args || {};
+          const entries = [];
+          for (const [sid, data] of sessionFileChanges) {
+            if (filters.session_id && sid !== filters.session_id) continue;
+            if (filters.task_id && data.taskId !== filters.task_id) continue;
+            entries.push({ session_id: sid, ...data });
+          }
+          return toContent({
+            entries,
+            total: entries.length,
+            unverified: entries.filter((e) => !e.verified).length,
+          });
+        }
+        case 'verify':
+          return toContent(
+            runVerify(args.requirements, args.implementation_context, args.session_id),
+          );
+        default:
+          throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
+      }
+    } catch (err) {
+      if (err instanceof McpError) throw err;
+      return toContent(
+        structuredBlockedResult(redactSecrets(err instanceof Error ? err.message : String(err))),
+      );
+    }
+  });
+
+  server.setRequestHandler(ListPromptsRequestSchema, async () => {
+    if (!promptsCache) promptsCache = readPackagePrompts();
+    return { prompts: promptsCache };
+  });
+
+  server.setRequestHandler(GetPromptRequestSchema, async (request) => {
+    if (!promptsCache) promptsCache = readPackagePrompts();
+    const prompt = promptsCache.find((p) => p.name === request.params.name);
+    if (!prompt) {
+      throw new McpError(ErrorCode.InvalidParams, `Unknown prompt: ${request.params.name}`);
+    }
+    const text = renderPrompt(prompt, request.params.arguments);
+    return {
+      description: prompt.description,
+      messages: [{ role: 'user', content: { type: 'text', text } }],
+    };
+  });
+
+  return server;
+}
+
+// ── CLI entry ────────────────────────────────────────────────
+/** Start the server over the stdio transport. */
+export async function main() {
+  const server = createRegentServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  process.stdin.on('end', async () => {
+    await server.close();
+    process.exit(0);
+  });
+}
+
+// Run when invoked directly (`node mcp/index.js`).
+const isDirectRun = process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (isDirectRun) {
+  void main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });
+}