@saiteja1123/mcp-server 1.1.3 → 1.1.5

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.',
+    });
+  });
+}

package/src/tools/localScan.js

@@ -0,0 +1,85 @@
+/**
+ * src/tools/localScan.js
+ *
+ * MCP tool: 'localScan'
+ *
+ * Registers the localScan tool against a McpServer instance.
+ * All server-level dependencies (guard, token, version) are injected
+ * by the caller — this file never imports from server.js.
+ *
+ * Dependency injection contract:
+ *   registerLocalScanTool(server, deps)
+ *     server       — McpServer instance
+ *     deps.guardPath     — async (path: string) => GuardResult
+ *     deps.guardError    — (guard: GuardResult) => McpErrorResponse
+ *     deps.INSTALL_TOKEN — string | null
+ *     deps.engineVersion — string (mcpPkg.version)
+ *
+ * DOES NOT OWN:
+ *   - Path guard implementation (server.js)
+ *   - Install token / bound root resolution (server.js)
+ *   - Scan orchestration (orchestrator/runScan.js)
+ *   - Governance middleware (middleware/governance.js — called inside runScan)
+ */
+
+import * as z from 'zod';
+import { runScan } from '../orchestrator/runScan.js';
+
+/**
+ * Register the 'localScan' MCP tool on the provided server instance.
+ *
+ * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server
+ * @param {Object} deps
+ * @param {Function} deps.guardPath     - Bound-folder + lock validation
+ * @param {Function} deps.guardError    - Guard failure → MCP error response
+ * @param {string|null} deps.INSTALL_TOKEN
+ * @param {string} deps.engineVersion
+ */
+export function registerLocalScanTool(server, { guardPath, guardError, installToken, engineVersion }) {
+  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 = '.' }) => {
+    // ── Binding / path guard ──────────────────────────────────────────────
+    const guard = await guardPath(projectRoot);
+    if (!guard.ok) return guardError(guard);
+
+    // ── Scan orchestration (remote → governance → local fallback) ─────────
+    const outcome = await runScan({
+      code,
+      lang,
+      projectRoot: guard.resolvedRoot,
+      installToken: guard.installToken || installToken,
+      lockedRootHash: guard.lockedRootHash || guard.lock?.lockedRootHash || guard.lock?.rootHash,
+      engineVersion,
+    });
+
+    // ── Error outcome (REMOTE_VERIFICATION_REQUIRED / UPGRADE_REQUIRED /
+    //    GOVERNANCE_BLOCKED) ─────────────────────────────────────────────
+    if (!outcome.ok) {
+      return {
+        content: [{ type: 'text', text: JSON.stringify(outcome.errorPayload, null, 2) }],
+        isError: true,
+      };
+    }
+
+    // ── Remote success ────────────────────────────────────────────────────
+    if (outcome.mode === 'remote') {
+      const data = outcome.result;
+      const humanSummary = `${data.verdict || ''} Score ${data.score} (${data.grade}) - ${(data.findings || []).length} finding(s).`;
+      const enriched = { ...data, humanSummary, engineVersion: outcome.engineVersion, quota: outcome.quota };
+      return { content: [{ type: 'text', text: JSON.stringify(enriched, null, 2) }], structuredContent: enriched };
+    }
+
+    // ── Offline fallback ──────────────────────────────────────────────────
+    const result = outcome.result;
+    const humanSummary = `${result.verdict} Score ${result.score} (${result.grade}) - ${result.findings.length} finding(s).`;
+    const enriched = { ...result, humanSummary, engineVersion: outcome.engineVersion, mode: 'offline' };
+    return { content: [{ type: 'text', text: JSON.stringify(enriched, null, 2) }], structuredContent: enriched };
+  });
+}

package/src/tools/projects.js

@@ -0,0 +1,124 @@
+import * as z from 'zod';
+
+import { listProjects } from '../api-scan.mjs';
+import { ensureProjectBinding, invalidateProjectsListCache } from '../project-bindings.mjs';
+
+function resolveAuthToken(authToken) {
+  return (
+    authToken
+    || process.env.VIBESECUR_AUTH_TOKEN
+    || process.env.VIBESECUR_TOKEN
+    || ''
+  ).trim();
+}
+
+function formatApiError(res, fallback) {
+  return res.json?.error || res.error || fallback || `Request failed (${res.status || 'unknown'})`;
+}
+
+/**
+ * Register project management tools (CRU — create/read/update, never delete).
+ */
+export function registerProjectTools(server, { authToken, apiBase, normalizeRootPath }) {
+  const token = () => resolveAuthToken(authToken);
+
+  server.registerTool('projectList', {
+    title: 'List Projects',
+    description: 'List all projects in your Vibesecur account. Read-only.',
+    inputSchema: {},
+  }, async () => {
+    if (!token()) {
+      return {
+        content: [{ type: 'text', text: JSON.stringify({
+          error: 'AUTH_REQUIRED',
+          message: 'Set VIBESECUR_AUTH_TOKEN in MCP config (login JWT from dashboard).',
+        }, null, 2) }],
+        isError: true,
+      };
+    }
+    const res = await listProjects({ authToken: token() });
+    if (!res.ok || !res.json?.success) {
+      return {
+        content: [{ type: 'text', text: JSON.stringify({
+          error: 'PROJECT_LIST_FAILED',
+          message: formatApiError(res, 'Unable to list projects'),
+        }, null, 2) }],
+        isError: true,
+      };
+    }
+    const projects = res.json.data?.projects || [];
+    const body = {
+      count: projects.length,
+      projects: projects.map((p) => ({
+        id: p.id,
+        name: p.name,
+        lockedRootHint: p.lockedRootHint,
+        mcpBound: p.mcpBound,
+        latestScan: p.latestScan,
+      })),
+    };
+    return {
+      content: [{ type: 'text', text: JSON.stringify(body, null, 2) }],
+      structuredContent: body,
+    };
+  });
+
+  server.registerTool('projectUpsert', {
+    title: 'Create or Update Project',
+    description:
+      'Register a codebase folder as a project, or update an existing one. ' +
+      'Never deletes projects. Creates install credentials for scans in that folder.',
+    inputSchema: {
+      rootPath: z.string().min(1).describe('Absolute or relative codebase root folder'),
+      name: z.string().min(1).max(200).optional().describe('Display name (optional)'),
+      projectId: z.string().uuid().optional().describe('Existing project id to update/rebind'),
+    },
+  }, async ({ rootPath, name, projectId }) => {
+    if (!token()) {
+      return {
+        content: [{ type: 'text', text: JSON.stringify({
+          error: 'AUTH_REQUIRED',
+          message: 'Set VIBESECUR_AUTH_TOKEN in MCP config (login JWT from dashboard).',
+        }, null, 2) }],
+        isError: true,
+      };
+    }
+
+    const resolvedRoot = normalizeRootPath(rootPath);
+    const binding = await ensureProjectBinding({
+      lockedRootPath: resolvedRoot,
+      name,
+      projectId,
+      authToken: token(),
+      apiBase,
+    });
+
+    if (!binding.ok) {
+      return {
+        content: [{ type: 'text', text: JSON.stringify({
+          error: binding.code || 'PROJECT_UPSERT_FAILED',
+          message: binding.message,
+        }, null, 2) }],
+        isError: true,
+      };
+    }
+
+    invalidateProjectsListCache();
+    const body = {
+      action: binding.action,
+      project: {
+        id: binding.projectId,
+        projectHash: binding.projectHash,
+        lockedRootPath: binding.projectRoot,
+        lockedRootHash: binding.lockedRootHash,
+      },
+      message:
+        'Project registered. Scans under this folder will sync metadata to the dashboard. ' +
+        'Install token is cached for this MCP session (not returned for security).',
+    };
+    return {
+      content: [{ type: 'text', text: JSON.stringify(body, null, 2) }],
+      structuredContent: body,
+    };
+  });
+}

package/src/tools/scanFile.js

@@ -0,0 +1,131 @@
+/**
+ * src/tools/scanFile.js
+ *
+ * MCP tool: 'scanFile'
+ *
+ * Registers the scanFile tool against a McpServer instance.
+ * All server-level dependencies (guard, token, version) are injected
+ * by the caller — this file never imports from server.js.
+ *
+ * Dependency injection contract:
+ *   registerScanFileTool(server, deps)
+ *     server                  — McpServer instance
+ *     deps.guardPath          — async (path: string) => GuardResult
+ *     deps.guardError         — (guard: GuardResult) => McpErrorResponse
+ *     deps.INSTALL_TOKEN      — string | null
+ *     deps.engineVersion      — string (mcpPkg.version)
+ *
+ * Tool-owned responsibilities:
+ *   - path.resolve() / fs.realpath()  — symlink resolution + existence check
+ *   - fs.readFile()                   — file content loading
+ *   - inferLang()                     — language detection from file extension
+ *   - File-report response formatting — findingsWithLocation, bySev, body shape
+ *   - Top-level try/catch             — wraps all I/O so ENOENT etc. are caught
+ *
+ * DOES NOT OWN:
+ *   - Path guard implementation        (server.js — injected)
+ *   - Install token / bound root       (server.js — injected)
+ *   - Scan orchestration               (orchestrator/runScan.js — direct import)
+ *   - Governance middleware            (middleware/governance.js — called inside runScan)
+ *
+ * NOTE: guardPath is called with path.dirname(realPath) — the containing
+ * directory of the resolved real file — not the raw filePath argument.
+ * This is intentional: symlinks may point outside the apparent directory.
+ */
+
+import * as z from 'zod';
+import fs from 'fs/promises';
+import path from 'path';
+import { inferLang } from '../repo-scan.mjs';
+import { runScan } from '../orchestrator/runScan.js';
+
+/**
+ * Register the 'scanFile' MCP tool on the provided server instance.
+ *
+ * @param {import('@modelcontextprotocol/sdk/server/mcp.js').McpServer} server
+ * @param {Object} deps
+ * @param {Function}    deps.guardPath      - Bound-folder + lock validation
+ * @param {Function}    deps.guardError     - Guard failure → MCP error response
+ * @param {string|null} deps.INSTALL_TOKEN
+ * @param {string}      deps.engineVersion
+ */
+export function registerScanFileTool(server, { guardPath, guardError, installToken, engineVersion }) {
+  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 {
+      // ── File I/O + symlink resolution ───────────────────────────────────
+      const resolvedPath = path.resolve(filePath);
+      const realPath = await fs.realpath(resolvedPath);
+
+      // ── Binding / path guard ─────────────────────────────────────────────
+      // Guard receives dirname(realPath) — the directory of the resolved real
+      // file. Using realPath prevents symlinks from bypassing the bound folder.
+      const guard = await guardPath(path.dirname(realPath));
+      if (!guard.ok) return guardError(guard);
+
+      // ── Read file content + resolve language ────────────────────────────
+      const code = await fs.readFile(realPath, 'utf8');
+      const useLang = lang === 'auto' ? inferLang(realPath) : lang;
+
+      // ── Scan orchestration (remote → governance → local fallback) ────────
+      const outcome = await runScan({
+        code,
+        lang: useLang,
+        projectRoot: guard.resolvedRoot,
+        installToken: guard.installToken || installToken,
+        lockedRootHash: guard.lockedRootHash || guard.lock?.lockedRootHash || guard.lock?.rootHash,
+        engineVersion,
+      });
+
+      // ── Error outcome (REMOTE_VERIFICATION_REQUIRED / UPGRADE_REQUIRED /
+      //    GOVERNANCE_BLOCKED) ──────────────────────────────────────────────
+      if (!outcome.ok) {
+        return {
+          content: [{ type: 'text', text: JSON.stringify(outcome.errorPayload, null, 2) }],
+          isError: true,
+        };
+      }
+
+      // ── File-report response formatting ─────────────────────────────────
+      // NOTE: findings field is the COUNT (number), not the array.
+      // The full findings array lives inside result.findings.
+      const result = outcome.result;
+      const findings = result.findings || [];
+      const findingsWithLocation = findings.map((f) => ({
+        ...f,
+        filePath: realPath,
+        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 "${realPath}": score ${result.score} (${result.grade}), ${findings.length} issue(s).`;
+      const body = {
+        humanSummary,
+        filePath: realPath,
+        lang: useLang,
+        score: result.score,
+        grade: result.grade,
+        findings: findingsWithLocation.length,   // count — not array
+        bySeverity: bySev,
+        checklist: result.checklist,
+        result: {
+          ...result,
+          findings: findingsWithLocation,
+        },
+      };
+      return { content: [{ type: 'text', text: JSON.stringify(body, null, 2) }], structuredContent: body };
+
+    } catch (e) {
+      // Catches: ENOENT from realpath, EACCES from readFile, unexpected throws
+      return { content: [{ type: 'text', text: `scanFile failed: ${e.message}` }], isError: true };
+    }
+  });
+}