@saiteja1123/mcp-server 1.1.4 → 1.1.5

package/src/server.js

@@ -10,29 +10,44 @@ import {
 } from './rule-engine/index.js';
 import {
   DEFAULT_INCLUDE, DEFAULT_EXCLUDE,
-  inferLang, normalizeRootPath, ensureDirectory,
+  normalizeRootPath, ensureDirectory,
   gatherRepoScan, readGitignoreChecks,
   detectWorkspacePath, isHomePath,
 } from './repo-scan.mjs';
-import { postRemoteLocalScan } from './api-scan.mjs';
-import { validateScanPath, diagnosticLock } from './lock.mjs';
+import { diagnosticLock } from './lock.mjs';
+import { persistRepoScanLog } from './api-scan.mjs';
+import { createBindingGuard, formatGuardError } from './security/pathGuard.js';
+import { registerLocalScanTool } from './tools/localScan.js';
+import { registerScanFileTool } from './tools/scanFile.js';
+import { registerDeepScanTools } from './tools/deepScan.js';
+import { registerProjectTools } from './tools/projects.js';
 
 const require = createRequire(import.meta.url);
 const mcpPkg = require('../package.json');
 
 const INSTALL_TOKEN = process.env.VIBESECUR_INSTALL_TOKEN || null;
+const AUTH_TOKEN = process.env.VIBESECUR_AUTH_TOKEN || process.env.VIBESECUR_TOKEN || null;
 const BOUND_ROOT = process.env.VIBESECUR_BOUND_ROOT
   ? path.resolve(process.env.VIBESECUR_BOUND_ROOT)
   : null;
+const API_BASE = process.env.VIBESECUR_API_BASE || process.env.VIBESECUR_API_URL || '';
+const UNIVERSAL_MODE = !!AUTH_TOKEN && !BOUND_ROOT;
 
-if (!INSTALL_TOKEN || !BOUND_ROOT) {
-  process.stderr.write(
-    '[vibesecur] WARNING: VIBESECUR_INSTALL_TOKEN and VIBESECUR_BOUND_ROOT are not set.\n' +
-    '[vibesecur] Run: vibesecur-mcp bind <folder> then vibesecur-mcp config <folder>\n' +
-    '[vibesecur] Scans will be restricted to process.cwd() as fallback.\n',
-  );
+function debugLog(message, payload) {
+  if (process.env.VIBESECUR_DEBUG !== '1') return;
+  process.stderr.write(`[vibesecur-debug] ${message}: ${JSON.stringify(payload)}\n`);
 }
 
+const guardPath = createBindingGuard({
+  boundRoot: BOUND_ROOT,
+  installToken: INSTALL_TOKEN,
+  authToken: AUTH_TOKEN,
+  apiBase: API_BASE,
+  universalMode: UNIVERSAL_MODE,
+  normalizePath: normalizeRootPath,
+  debugLog,
+});
+
 const server = new McpServer({
   name: 'vibesecur-mcp-server',
   version: mcpPkg.version || '2.0.0',
@@ -40,52 +55,7 @@ const server = new McpServer({
 
 const SEVERITY_ORDER = { critical: 0, high: 1, medium: 2, low: 3 };
 
-async function guardPath(requestedPath) {
-  const target = normalizeRootPath(requestedPath);
-  if (!BOUND_ROOT) {
-    const cwd = path.resolve(process.cwd());
-    if (!target.startsWith(cwd + path.sep) && target !== cwd) {
-      return {
-        ok: false,
-        httpStatus: 403,
-        code: 'NO_LOCK_OUT_OF_CWD',
-        message:
-          `No lock configured and "${target}" is outside process.cwd() "${cwd}". ` +
-          'Run vibesecur-mcp bind <folder> and add VIBESECUR_BOUND_ROOT to your MCP config.',
-      };
-    }
-    return { ok: true, resolvedRoot: target };
-  }
-  if (!target.startsWith(BOUND_ROOT + path.sep) && target !== BOUND_ROOT) {
-    return {
-      ok: false,
-      httpStatus: 403,
-      code: 'OUT_OF_FOLDER',
-      message:
-        `Path "${target}" is outside the locked project folder "${BOUND_ROOT}". ` +
-        'Vibesecur MCP is bound to one folder per install. ' +
-        'To scan a different folder, run "vibesecur-mcp rebind <new-folder>".',
-      rebindHint: `vibesecur-mcp rebind ${target}`,
-    };
-  }
-  const result = await validateScanPath(target, INSTALL_TOKEN);
-  if (!result.ok) return result;
-  return { ok: true, resolvedRoot: target, lock: result.lock };
-}
-
-function guardError(guard) {
-  const status = guard.httpStatus ? ` (${guard.httpStatus})` : '';
-  const text = JSON.stringify({
-    error: guard.code || 'SCAN_BLOCKED',
-    message: guard.message,
-    rebindHint: guard.rebindHint || null,
-    docs: 'https://vibesecur.com/docs/mcp-setup',
-  }, null, 2);
-  return {
-    content: [{ type: 'text', text: `Security Lock Error${status}:\n${text}` }],
-    isError: true,
-  };
-}
+const guardError = formatGuardError;
 
 function buildScanMeta(resolvedRoot, includeGlobs, excludeGlobs, maxFiles, matchedLen, scannedLen) {
   return {
@@ -96,7 +66,8 @@ function buildScanMeta(resolvedRoot, includeGlobs, excludeGlobs, maxFiles, match
     matchedFiles: matchedLen,
     scannedFiles: scannedLen,
     cappedByMaxFiles: matchedLen > maxFiles,
-    boundRoot: BOUND_ROOT || 'unconfigured',
+    boundRoot: BOUND_ROOT || (UNIVERSAL_MODE ? 'account-wide' : 'unconfigured'),
+    mode: UNIVERSAL_MODE ? 'universal' : (BOUND_ROOT ? 'single-folder' : 'unconfigured'),
   };
 }
 
@@ -108,6 +79,33 @@ function humanRepoSummary(meta, agg) {
   return parts.join(' ');
 }
 
+async function syncRepoScanToDashboard({ aggregate, findings, projectRoot, guard }) {
+  const installToken = guard.installToken || INSTALL_TOKEN;
+  const lockedRootHash = guard.lockedRootHash || guard.lock?.lockedRootHash || guard.lock?.rootHash;
+  if (!installToken || !lockedRootHash) {
+    return { ok: false, reason: 'missing install token or locked root hash' };
+  }
+  try {
+    const logRes = await persistRepoScanLog({
+      aggregate,
+      findings,
+      projectRoot,
+      installToken,
+      lockedRootHash,
+    });
+    if (logRes?.ok && logRes.json?.success) {
+      return { ok: true, scanId: logRes.json?.data?.scanId || null };
+    }
+    return {
+      ok: false,
+      reason: logRes?.reason || logRes?.error || logRes?.json?.error || `status ${logRes?.status || 'unknown'}`,
+    };
+  } catch (err) {
+    process.stderr.write(`[vibesecur] scan log failed (non-fatal): ${err.message}\n`);
+    return { ok: false, reason: err.message };
+  }
+}
+
 function flattenFindings(fileResults) {
   return fileResults.flatMap((fr) =>
     (fr.result.findings || []).map((f) => ({
@@ -149,9 +147,13 @@ server.registerTool('health', {
     ok: true,
     server: { name: 'vibesecur-mcp-server', version: mcpPkg.version },
     lock: {
-      configured: !!(INSTALL_TOKEN && BOUND_ROOT),
+      configured: UNIVERSAL_MODE || !!(INSTALL_TOKEN && BOUND_ROOT),
+      mode: UNIVERSAL_MODE ? 'universal' : 'single-folder',
       boundRoot: BOUND_ROOT || null,
+      accountWide: UNIVERSAL_MODE,
       healthy: diag.healthy,
+      runtimeCompatible: diag.runtimeCompatible || false,
+      source: diag.source || null,
       issues: diag.issues || [],
     },
     rules: {
@@ -170,9 +172,11 @@ server.registerTool('health', {
 
   if (detail === 'full') {
     payload.envHints = {
+      VIBESECUR_AUTH_TOKEN: AUTH_TOKEN ? '***set***' : 'NOT SET',
       VIBESECUR_INSTALL_TOKEN: INSTALL_TOKEN ? '***set***' : 'NOT SET',
       VIBESECUR_BOUND_ROOT: BOUND_ROOT || 'NOT SET',
-      VIBESECUR_API_BASE: process.env.VIBESECUR_API_BASE || 'NOT SET',
+      VIBESECUR_API_BASE: API_BASE || 'NOT SET',
+      universalMode: UNIVERSAL_MODE,
       CURSOR_WORKSPACE_PATH: process.env.CURSOR_WORKSPACE_PATH ?? null,
       WORKSPACE_PATH: process.env.WORKSPACE_PATH ?? null,
     };
@@ -183,7 +187,9 @@ server.registerTool('health', {
     ok: true,
     version: mcpPkg.version,
     lockConfigured: payload.lock.configured,
+    lockMode: payload.lock.mode,
     lockHealthy: payload.lock.healthy,
+    runtimeCompatible: payload.lock.runtimeCompatible,
     boundRoot: BOUND_ROOT || null,
     totalRules: JS_RULES.length + PY_RULES.length,
     processCwd: cwd,
@@ -223,100 +229,29 @@ server.registerTool('installDiagnostic', {
   };
 });
 
-server.registerTool('localScan', {
-  title: 'Local Security Scan',
-  description: 'Run Vibesecur rule-engine on code. Restricted to bound project folder.',
-  inputSchema: {
-    code: z.string().min(1).max(50000).describe('Source code to scan'),
-    lang: z.enum(['js', 'ts', 'py', 'json', 'auto']).default('auto'),
-    projectRoot: z.string().default('.').describe('Must be inside bound folder'),
-  },
-}, async ({ code, lang = 'auto', projectRoot = '.' }) => {
-  const guard = await guardPath(projectRoot);
-  if (!guard.ok) return guardError(guard);
-  const remote = await postRemoteLocalScan({
-    code,
-    lang,
-    projectRoot: guard.resolvedRoot,
-    platform: 'mcp',
-    token: INSTALL_TOKEN,
-  });
-  if (!remote.skipped && remote.status === 402) {
-    return {
-      content: [{ type: 'text', text: JSON.stringify({ ...remote.json, upgradeUrl: 'https://vibesecur.com/#pricing' }, null, 2) }],
-      isError: true,
-    };
-  }
-  if (!remote.skipped && remote.ok && remote.json?.success && remote.json?.data) {
-    const data = remote.json.data;
-    const humanSummary = `${data.verdict || ''} Score ${data.score} (${data.grade}) - ${(data.findings || []).length} finding(s).`;
-    const enriched = { ...data, humanSummary, engineVersion: mcpPkg.version, quota: remote.json.quota };
-    return { content: [{ type: 'text', text: JSON.stringify(enriched, null, 2) }], structuredContent: enriched };
-  }
-  const result = localScan(code, lang);
-  const humanSummary = `${result.verdict} Score ${result.score} (${result.grade}) - ${result.findings.length} finding(s).`;
-  const enriched = { ...result, humanSummary, engineVersion: mcpPkg.version, mode: 'offline' };
-  return { content: [{ type: 'text', text: JSON.stringify(enriched, null, 2) }], structuredContent: enriched };
+registerProjectTools(server, {
+  authToken: AUTH_TOKEN,
+  apiBase: API_BASE,
+  normalizeRootPath,
 });
 
-server.registerTool('scanFile', {
-  title: 'Scan File',
-  description: 'Scan a single file. Must be inside the bound project folder.',
-  inputSchema: {
-    filePath: z.string().min(1).describe('Absolute or relative file path (must be inside bound folder)'),
-    lang: z.enum(['js', 'ts', 'py', 'json', 'auto']).default('auto'),
-  },
-}, async ({ filePath, lang = 'auto' }) => {
-  try {
-    const resolvedPath = path.resolve(filePath);
-    const guard = await guardPath(path.dirname(resolvedPath));
-    if (!guard.ok) return guardError(guard);
-    const code = await fs.readFile(resolvedPath, 'utf8');
-    const useLang = lang === 'auto' ? inferLang(resolvedPath) : lang;
-    const remote = await postRemoteLocalScan({
-      code,
-      lang: useLang,
-      projectRoot: guard.resolvedRoot,
-      platform: 'mcp',
-      token: INSTALL_TOKEN,
-    });
-    let result;
-    if (!remote.skipped && remote.ok && remote.json?.success && remote.json?.data) {
-      result = remote.json.data;
-    } else if (!remote.skipped && remote.status === 402) {
-      return { content: [{ type: 'text', text: JSON.stringify(remote.json, null, 2) }], isError: true };
-    } else {
-      result = localScan(code, useLang);
-    }
-    const findings = result.findings || [];
-    const findingsWithLocation = findings.map((f) => ({
-      ...f,
-      filePath: resolvedPath,
-      snippetPreview: f.snippetPreview || f.snippet || '',
-    }));
-    const bySev = findings.reduce((a, f) => {
-      a[f.severity] = (a[f.severity] || 0) + 1;
-      return a;
-    }, { critical: 0, high: 0, medium: 0, low: 0 });
-    const humanSummary = `File "${resolvedPath}": score ${result.score} (${result.grade}), ${findings.length} issue(s).`;
-    const body = {
-      humanSummary,
-      filePath: resolvedPath,
-      lang: useLang,
-      score: result.score,
-      grade: result.grade,
-      findings: findingsWithLocation.length,
-      bySeverity: bySev,
-      checklist: result.checklist,
-      result: {
-        ...result,
-        findings: findingsWithLocation,
-      },
-    };
-    return { content: [{ type: 'text', text: JSON.stringify(body, null, 2) }], structuredContent: body };
-  } catch (e) {
-    return { content: [{ type: 'text', text: `scanFile failed: ${e.message}` }], isError: true };
-  }
+registerLocalScanTool(server, {
+  guardPath,
+  guardError,
+  installToken: INSTALL_TOKEN,
+  engineVersion: mcpPkg.version,
+});
+
+registerScanFileTool(server, {
+  guardPath,
+  guardError,
+  installToken: INSTALL_TOKEN,
+  engineVersion: mcpPkg.version,
+});
+
+registerDeepScanTools(server, {
+  guardPath,
+  guardError,
 });
 
 server.registerTool('scanRepo', {
@@ -348,6 +283,12 @@ server.registerTool('scanRepo', {
       fix: f.fix,
     }));
     const meta = buildScanMeta(resolvedRoot, includeGlobs, excludeGlobs, maxFiles, matchedFiles.length, limitedFiles.length);
+    const logged = await syncRepoScanToDashboard({
+      aggregate,
+      findings: allFindings,
+      projectRoot: resolvedRoot,
+      guard,
+    });
     const body = {
       meta,
       humanSummary: humanRepoSummary(meta, aggregate),
@@ -359,6 +300,7 @@ server.registerTool('scanRepo', {
       checklist: aggregate.checklist,
       topRiskFiles,
       allFindings,
+      logged,
     };
     return { content: [{ type: 'text', text: JSON.stringify(body, null, 2) }], structuredContent: { ...body, fileResults } };
   } catch (e) {
@@ -453,6 +395,12 @@ server.registerTool('scanCurrentWorkspace', {
       fix: f.fix,
     }));
     const meta = buildScanMeta(guard.resolvedRoot, includeGlobs, excludeGlobs, maxFiles, matchedFiles.length, limitedFiles.length);
+    const logged = await syncRepoScanToDashboard({
+      aggregate,
+      findings: allFindings,
+      projectRoot: guard.resolvedRoot,
+      guard,
+    });
     const body = {
       meta,
       humanSummary: humanRepoSummary(meta, aggregate),
@@ -464,6 +412,7 @@ server.registerTool('scanCurrentWorkspace', {
       checklist: aggregate.checklist,
       topRiskFiles,
       allFindings,
+      logged,
     };
     return { content: [{ type: 'text', text: JSON.stringify(body, null, 2) }], structuredContent: { ...body, fileResults } };
   } catch (e) {
@@ -533,6 +482,16 @@ server.registerTool('buildClaudePrompt', {
 });
 
 async function main() {
+  if (!INSTALL_TOKEN || !BOUND_ROOT) {
+    throw new Error(
+      'VIBESECUR_INSTALL_TOKEN and VIBESECUR_BOUND_ROOT are required. ' +
+      'Run "vibesecur-mcp bind <folder>" and update your MCP config env.',
+    );
+  }
+  const startupGuard = await guardPath(BOUND_ROOT);
+  if (!startupGuard.ok) {
+    throw new Error(`${startupGuard.code}: ${startupGuard.message}`);
+  }
   const transport = new StdioServerTransport();
   await server.connect(transport);
   process.stderr.write(

package/src/tools/deepScan.js

@@ -0,0 +1,286 @@
+import * as z from 'zod';
+import {
+  DeepScanRuntime,
+  LocalDeepScanStore,
+  StepperRegistry,
+  buildDeepScanStatus,
+  createSampleStepperRegistry,
+  appendAcceptedRiskRecord,
+} from '../deep-scan/index.js';
+
+const buildRuntime = (rootPath) => {
+  const registry = createSampleStepperRegistry(new StepperRegistry());
+  const store = new LocalDeepScanStore({ rootPath });
+  return new DeepScanRuntime({ registry, store });
+};
+
+const localDeepScanProfile = ({
+  requireHumanApproval = false,
+  previousDeterministicScanRef = null,
+  previousFailureStateRef = null,
+} = {}) => ({
+  id: 'local-deep-scan-v1',
+  version: '1.0.0',
+  checkpoint: true,
+  ralphLoop: {
+    retry: {
+      maxAttempts: 3,
+      escalateAt: 2,
+      trackSeverities: ['critical', 'high'],
+    },
+  },
+  steppers: [
+    ...(requireHumanApproval ? [{ id: 'sample.needsHuman', required: true }] : []),
+    { id: 'project.map', required: true },
+    { id: 'rules.scan', required: true },
+    { id: 'tests.plan', required: true },
+    { id: 'ralph.tasks', required: true },
+    { id: 'ralph.compare', required: true, config: previousDeterministicScanRef ? { previousDeterministicScanRef } : {} },
+    { id: 'ralph.accept', required: true },
+    { id: 'ralph.track', required: true, config: previousFailureStateRef ? { previousFailureStateRef } : {} },
+  ],
+});
+
+const artifactRefFromRun = (artifacts, { stepperId, type, fallbackId }) => {
+  const ref = artifacts[stepperId]
+    || Object.values(artifacts).find((item) => item?.type === type);
+  if (!ref?.uri || !ref?.hash) return null;
+  return {
+    id: ref.id || fallbackId,
+    type,
+    storage: ref.storage || 'local',
+    uri: ref.uri,
+    hash: ref.hash,
+  };
+};
+
+const resolvePreviousRunRefs = async ({ rootPath, previousRunId, previousDeterministicScanRef }) => {
+  if (previousDeterministicScanRef?.uri && previousDeterministicScanRef?.hash) {
+    return {
+      previousDeterministicScanRef: {
+        id: previousDeterministicScanRef.id || 'artifact-previous-deterministic-scan',
+        type: 'deterministic_scan',
+        storage: previousDeterministicScanRef.storage || 'local',
+        uri: previousDeterministicScanRef.uri,
+        hash: previousDeterministicScanRef.hash,
+      },
+      previousFailureStateRef: null,
+    };
+  }
+  if (!previousRunId) {
+    return { previousDeterministicScanRef: null, previousFailureStateRef: null };
+  }
+  const store = new LocalDeepScanStore({ rootPath });
+  const previousState = await store.getRun(previousRunId);
+  const artifacts = previousState?.artifacts || {};
+  const scanRef = artifactRefFromRun(artifacts, {
+    stepperId: 'rules.scan',
+    type: 'deterministic_scan',
+    fallbackId: `artifact-${previousRunId}-deterministic-scan`,
+  });
+  if (!scanRef) {
+    throw new Error(`Run ${previousRunId} does not contain a deterministic_scan artifact with uri/hash.`);
+  }
+  return {
+    previousDeterministicScanRef: scanRef,
+    previousFailureStateRef: artifactRefFromRun(artifacts, {
+      stepperId: 'ralph.track',
+      type: 'ralph_failure_state',
+      fallbackId: `artifact-${previousRunId}-ralph-failure-state`,
+    }),
+  };
+};
+
+const toolResult = (payload) => ({
+  content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+  structuredContent: payload,
+});
+
+export function registerDeepScanTools(server, { guardPath, guardError }) {
+  server.registerTool('deepScanStart', {
+    title: 'Start Deep Scan Project Map, Deterministic Scan, Test Plan, Ralph Tasks, Comparison, And Failure Tracking',
+    description: 'Create and run local-first Deep Scan Project Map, deterministic scan, metadata-only Security Test Plan, source-safe Ralph Agent Fix Tasks, optional rerun comparison, and repeated failure tracking with checkpoints, receipts, and artifact references.',
+    inputSchema: {
+      rootPath: z.string().default('.').describe('Project root, inside the bound folder'),
+      projectId: z.string().min(1).max(160).default('local-project'),
+      projectHash: z.string().regex(/^[a-f0-9]{64}$/i).optional(),
+      requireHumanApproval: z.boolean().default(false),
+      previousRunId: z.string().min(1).max(160).optional(),
+      previousDeterministicScanRef: z.object({
+        id: z.string().min(1).max(160).optional(),
+        storage: z.string().min(1).max(40).optional(),
+        uri: z.string().min(1).max(1000),
+        hash: z.string().regex(/^[a-f0-9]{64}$/i),
+      }).optional(),
+    },
+  }, async ({
+    rootPath = '.',
+    projectId = 'local-project',
+    projectHash = undefined,
+    requireHumanApproval = false,
+    previousRunId = undefined,
+    previousDeterministicScanRef = undefined,
+  }) => {
+    const guard = await guardPath(rootPath);
+    if (!guard.ok) return guardError(guard);
+    const runtime = buildRuntime(guard.resolvedRoot);
+    const { previousDeterministicScanRef: baselineRef, previousFailureStateRef } = await resolvePreviousRunRefs({
+      rootPath: guard.resolvedRoot,
+      previousRunId,
+      previousDeterministicScanRef,
+    });
+    const run = await runtime.createRun({
+      projectId,
+      projectHash: projectHash || null,
+      graphProfile: localDeepScanProfile({
+        requireHumanApproval,
+        previousDeterministicScanRef: baselineRef,
+        previousFailureStateRef,
+      }),
+      metadata: {
+        runtimeBoundary: 'mcp-local',
+        artifactStorage: 'refs-only',
+        trustModel: 'No raw source is stored in Deep Scan checkpoints.',
+      },
+    });
+    const state = await runtime.startRun(run.runId);
+    return toolResult(buildDeepScanStatus(state));
+  });
+
+  server.registerTool('deepScanStatus', {
+    title: 'Deep Scan Status',
+    description: 'Inspect a local-first Deep Scan run without exposing raw source.',
+    inputSchema: {
+      rootPath: z.string().default('.').describe('Project root, inside the bound folder'),
+      runId: z.string().min(1).max(160),
+    },
+  }, async ({ rootPath = '.', runId }) => {
+    const guard = await guardPath(rootPath);
+    if (!guard.ok) return guardError(guard);
+    const store = new LocalDeepScanStore({ rootPath: guard.resolvedRoot });
+    const state = await store.getRun(runId);
+    return toolResult(buildDeepScanStatus(state));
+  });
+
+  server.registerTool('deepScanApprove', {
+    title: 'Approve Deep Scan Step',
+    description: 'Record an auditable human approval or denial for a paused local Deep Scan run.',
+    inputSchema: {
+      rootPath: z.string().default('.').describe('Project root, inside the bound folder'),
+      runId: z.string().min(1).max(160),
+      requirementId: z.string().min(1).max(160),
+      decision: z.enum(['approved', 'denied']),
+      approvedBy: z.string().min(1).max(255),
+      reason: z.string().min(1).max(1000),
+      relatedFindingId: z.string().max(120).optional(),
+      relatedArtifactId: z.string().max(120).optional(),
+      metadata: z.record(z.string(), z.unknown()).default({}),
+    },
+  }, async ({
+    rootPath = '.',
+    runId,
+    requirementId,
+    decision,
+    approvedBy,
+    reason,
+    relatedFindingId,
+    relatedArtifactId,
+    metadata = {},
+  }) => {
+    const guard = await guardPath(rootPath);
+    if (!guard.ok) return guardError(guard);
+    const runtime = buildRuntime(guard.resolvedRoot);
+    const approval = await runtime.recordApproval({
+      runId,
+      requirementId,
+      decision,
+      approvedBy,
+      reason,
+      relatedFindingId,
+      relatedArtifactId,
+      metadata,
+    });
+    const store = new LocalDeepScanStore({ rootPath: guard.resolvedRoot });
+    const state = await store.getRun(runId);
+    return toolResult({
+      approval,
+      status: buildDeepScanStatus(state),
+      nextAction: 'Resume the Deep Scan run from deepScanResume.',
+    });
+  });
+
+  server.registerTool('deepScanResume', {
+    title: 'Resume Deep Scan Runtime',
+    description: 'Resume a local-first Deep Scan run after checkpoint, block, or human approval.',
+    inputSchema: {
+      rootPath: z.string().default('.').describe('Project root, inside the bound folder'),
+      runId: z.string().min(1).max(160),
+    },
+  }, async ({ rootPath = '.', runId }) => {
+    const guard = await guardPath(rootPath);
+    if (!guard.ok) return guardError(guard);
+    const runtime = buildRuntime(guard.resolvedRoot);
+    const state = await runtime.resumeRun(runId);
+    return toolResult(buildDeepScanStatus(state));
+  });
+
+  server.registerTool('deepScanAcceptRisk', {
+    title: 'Record Accepted Risk For A Deep Scan Finding',
+    description: 'Record an explicit, attributable accepted-risk decision for a finding or task in the local accepted-risk register. High and critical findings require reason, reviewer, and an expiry/review date. Accepted risk never removes the finding from history and reverts to unresolved after expiry.',
+    inputSchema: {
+      rootPath: z.string().default('.').describe('Project root, inside the bound folder'),
+      findingKey: z.string().regex(/^[a-f0-9]{64}$/i).optional().describe('Stable finding key from the Ralph comparison artifact'),
+      findingId: z.string().max(120).optional().describe('Deterministic scan finding id'),
+      taskId: z.string().max(120).optional().describe('Related Agent Fix Task id'),
+      severity: z.enum(['critical', 'high', 'medium', 'low']),
+      reason: z.string().max(1000).optional().describe('Required for high/critical findings'),
+      reviewer: z.string().max(255).optional().describe('Required for high/critical findings'),
+      acceptedAt: z.string().max(40).optional(),
+      expiresAt: z.string().max(40).optional().describe('Required for high/critical findings; ISO date'),
+      reviewBy: z.string().max(40).optional(),
+      reportVisibility: z.enum(['visible', 'summary_only']).default('visible'),
+      riskId: z.string().max(160).optional(),
+      metadata: z.record(z.string(), z.unknown()).default({}),
+    },
+  }, async ({
+    rootPath = '.',
+    findingKey = undefined,
+    findingId = undefined,
+    taskId = undefined,
+    severity,
+    reason = undefined,
+    reviewer = undefined,
+    acceptedAt = undefined,
+    expiresAt = undefined,
+    reviewBy = undefined,
+    reportVisibility = 'visible',
+    riskId = undefined,
+    metadata = {},
+  }) => {
+    const guard = await guardPath(rootPath);
+    if (!guard.ok) return guardError(guard);
+    const result = await appendAcceptedRiskRecord({
+      rootPath: guard.resolvedRoot,
+      record: {
+        riskId,
+        findingKey,
+        findingId,
+        taskId,
+        severity,
+        reason,
+        reviewer,
+        acceptedAt,
+        expiresAt,
+        reviewBy,
+        reportVisibility,
+        metadata: { ...metadata, source: 'mcp' },
+      },
+    });
+    return toolResult({
+      record: result.record,
+      registerRef: { uri: result.uri, hash: result.hash },
+      activeRecordCount: result.register.records.length,
+      nextAction: 'Rerun the Deep Scan so ralph.compare and ralph.accept apply this accepted risk and reports show it separately from resolved findings.',
+    });
+  });
+}