visus-mcp 0.6.0 → 0.6.2

package/server.json

@@ -0,0 +1,43 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.visus-mcp/visus-mcp",
+  "description": "Security-first web access for Claude. Sanitizes pages, blocks injection, redacts PII.",
+  "repository": {
+    "url": "https://github.com/visus-mcp/visus-mcp",
+    "source": "github"
+  },
+  "version": "0.6.2",
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "visus-mcp",
+      "version": "0.6.2",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "description": "Optional timeout in milliseconds for page fetching (default: 10000)",
+          "isRequired": false,
+          "format": "number",
+          "isSecret": false,
+          "name": "VISUS_TIMEOUT_MS"
+        },
+        {
+          "description": "Optional maximum content size in KB before truncation (default: 512)",
+          "isRequired": false,
+          "format": "number",
+          "isSecret": false,
+          "name": "VISUS_MAX_CONTENT_KB"
+        },
+        {
+          "description": "Optional URL for managed Lambda renderer (Phase 2 - not yet available)",
+          "isRequired": false,
+          "format": "string",
+          "isSecret": false,
+          "name": "VISUS_RENDERER_URL"
+        }
+      ]
+    }
+  ]
+}

package/src/browser/playwright-renderer.ts

@@ -9,7 +9,6 @@
  * Lambda to the local process before Claude sees it. PHI never touches Lateos infrastructure.
  */
 
-import { request } from 'undici';
 import type { BrowserRenderResult, Result } from '../types.js';
 import { Ok, Err } from '../types.js';
 
@@ -99,22 +98,28 @@ async function renderWithLambda(
   try {
     // Retry Lambda calls with exponential backoff (3 attempts)
     const response = await retryWithBackoff(async () => {
-      return await request(`${RENDERER_URL}/render`, {
-        method: 'POST',
-        headers: {
-          'Content-Type': 'application/json',
-        },
-        body: JSON.stringify({
-          url,
-          timeout_ms,
-          content_limit_bytes: 512000, // 500KB default
-        }),
-        bodyTimeout: timeout_ms + 5000, // Add 5s buffer for network overhead
-        headersTimeout: timeout_ms + 5000,
-      });
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), timeout_ms + 5000);
+
+      try {
+        return await fetch(`${RENDERER_URL}/render`, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+          },
+          body: JSON.stringify({
+            url,
+            timeout_ms,
+            content_limit_bytes: 512000, // 500KB default
+          }),
+          signal: controller.signal,
+        });
+      } finally {
+        clearTimeout(timeoutId);
+      }
     }, 3, 1000); // 3 retries, starting with 1s delay
 
-    const body = await response.body.json() as LambdaRenderSuccess | LambdaRenderError;
+    const body = await response.json() as LambdaRenderSuccess | LambdaRenderError;
 
     // Check if response is an error
     if ('error' in body) {
@@ -145,7 +150,7 @@ async function renderWithLambda(
 }
 
 /**
- * Render a page using undici fetch (fallback)
+ * Render a page using native fetch (fallback)
  */
 async function renderWithFetch(
   url: string,
@@ -154,39 +159,51 @@ async function renderWithFetch(
   logRenderer('fetch', url);
 
   try {
-    const response = await request(url, {
-      method: 'GET',
-      headers: {
-        'User-Agent': 'Visus-MCP/0.2.0 (Security-focused web content fetcher; +https://github.com/visus-mcp/visus-mcp)',
-      },
-      bodyTimeout: timeout_ms,
-      headersTimeout: timeout_ms,
-    });
+    // Use AbortController for timeout
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout_ms);
 
-    const html = await response.body.text();
+    try {
+      const response = await fetch(url, {
+        method: 'GET',
+        headers: {
+          'User-Agent': 'Visus-MCP/0.3.1 (Security-focused web content fetcher; +https://github.com/lateos/visus-mcp)',
+        },
+        signal: controller.signal,
+      });
 
-    // Capture Content-Type header
-    const contentTypeHeader = response.headers['content-type'];
-    const contentType = typeof contentTypeHeader === 'string'
-      ? contentTypeHeader.split(';')[0].trim()  // Remove charset and other params
-      : 'text/html'; // Default to HTML if missing
+      if (!response.ok) {
+        return Err(new Error(`HTTP ${response.status}: ${response.statusText}`));
+      }
 
-    // Extract title using regex (simple fallback)
-    const titleMatch = html.match(/<title[^>]*>(.*?)<\/title>/i);
-    const title = titleMatch ? titleMatch[1].trim() : '';
+      const html = await response.text();
 
-    return Ok({
-      html,
-      title,
-      url,
-      contentType,
-      text: undefined,
-    });
+      // Capture Content-Type header
+      const contentTypeHeader = response.headers.get('content-type');
+      const contentType = contentTypeHeader
+        ? contentTypeHeader.split(';')[0].trim()  // Remove charset and other params
+        : 'text/html'; // Default to HTML if missing
+
+      // Extract title using regex (simple fallback)
+      const titleMatch = html.match(/<title[^>]*>(.*?)<\/title>/i);
+      const title = titleMatch ? titleMatch[1].trim() : '';
+
+      return Ok({
+        html,
+        title,
+        url,
+        contentType,
+        text: undefined,
+      });
+
+    } finally {
+      clearTimeout(timeoutId);
+    }
 
   } catch (error) {
     if (error instanceof Error) {
-      // Handle timeout errors
-      if (error.message.includes('timeout') || error.message.includes('UND_ERR')) {
+      // Handle abort/timeout errors
+      if (error.name === 'AbortError') {
         return Err(new Error(`Navigation timeout after ${timeout_ms}ms`));
       }
 
@@ -256,17 +273,23 @@ export async function checkUrl(
   timeout_ms = 5000
 ): Promise<Result<boolean, Error>> {
   try {
-    const response = await request(url, {
-      method: 'HEAD',
-      headersTimeout: timeout_ms,
-      bodyTimeout: timeout_ms,
-    });
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout_ms);
+
+    try {
+      const response = await fetch(url, {
+        method: 'HEAD',
+        signal: controller.signal,
+      });
+
+      // Consider 2xx and 3xx status codes as accessible
+      const isAccessible = (response.status >= 200 && response.status < 400);
 
-    // Consider 2xx and 3xx status codes as accessible
-    const statusCode = response.statusCode;
-    const isAccessible = (statusCode >= 200 && statusCode < 400);
+      return Ok(isAccessible);
 
-    return Ok(isAccessible);
+    } finally {
+      clearTimeout(timeoutId);
+    }
 
   } catch (error) {
     // URL is not accessible

package/src/index.ts

@@ -31,6 +31,9 @@ import { visusRead, visusReadToolDefinition } from './tools/read.js';
 import { visusSearch, visusSearchToolDefinition } from './tools/search.js';
 import { closeBrowser } from './browser/playwright-renderer.js';
 import { detectRuntime, logRuntimeConfig, validateRuntime } from './runtime.js';
+import { shouldElicit } from './sanitizer/hitl-gate.js';
+import { runElicitation } from './sanitizer/elicit-runner.js';
+import type { ThreatReport } from './sanitizer/threat-reporter.js';
 
 /**
  * Create and configure the MCP server
@@ -38,7 +41,7 @@ import { detectRuntime, logRuntimeConfig, validateRuntime } from './runtime.js';
 const server = new Server(
   {
     name: 'visus-mcp',
-    version: '0.2.0'
+    version: '0.6.0'
   },
   {
     capabilities: {
@@ -61,6 +64,50 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
   };
 });
 
+/**
+ * Helper function to handle HITL elicitation for CRITICAL threats
+ *
+ * Returns modified output with threat_report removed if user declined,
+ * or blocked response if user declined to proceed.
+ */
+async function handleCriticalThreatElicitation(
+  output: any,
+  url: string
+): Promise<{ output: any; blocked: boolean }> {
+  const threatReport = output.threat_report as ThreatReport | undefined;
+
+  // Check if elicitation is needed
+  if (shouldElicit(threatReport ?? null)) {
+    const { proceed, includeReport } = await runElicitation(
+      server,
+      threatReport!,
+      url
+    );
+
+    if (!proceed) {
+      // User declined — return blocked response with threat report
+      return {
+        output: {
+          url,
+          blocked: true,
+          reason: 'User declined to proceed after CRITICAL threat detected',
+          threat_report: threatReport
+        },
+        blocked: true
+      };
+    }
+
+    // User accepted — proceed with sanitized content
+    // Remove threat_report if user didn't request it
+    if (!includeReport && output.threat_report) {
+      const { threat_report, ...outputWithoutReport } = output;
+      return { output: outputWithoutReport, blocked: false };
+    }
+  }
+
+  return { output, blocked: false };
+}
+
 /**
  * Handle tool execution requests
  */
@@ -79,11 +126,17 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           );
         }
 
+        // Handle HITL elicitation for CRITICAL threats
+        const { output } = await handleCriticalThreatElicitation(
+          result.value,
+          (args as any).url
+        );
+
         return {
           content: [
             {
               type: 'text',
-              text: JSON.stringify(result.value, null, 2)
+              text: JSON.stringify(output, null, 2)
             }
           ]
         };
@@ -99,11 +152,17 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           );
         }
 
+        // Handle HITL elicitation for CRITICAL threats
+        const { output } = await handleCriticalThreatElicitation(
+          result.value,
+          (args as any).url
+        );
+
         return {
           content: [
             {
               type: 'text',
-              text: JSON.stringify(result.value, null, 2)
+              text: JSON.stringify(output, null, 2)
             }
           ]
         };
@@ -119,11 +178,17 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           );
         }
 
+        // Handle HITL elicitation for CRITICAL threats
+        const { output } = await handleCriticalThreatElicitation(
+          result.value,
+          (args as any).url
+        );
+
         return {
           content: [
             {
               type: 'text',
-              text: JSON.stringify(result.value, null, 2)
+              text: JSON.stringify(output, null, 2)
             }
           ]
         };
@@ -139,11 +204,18 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
           );
         }
 
+        // Handle HITL elicitation for CRITICAL threats
+        // For search, use the query as the "URL" in the elicitation message
+        const { output } = await handleCriticalThreatElicitation(
+          result.value,
+          `search: ${(args as any).query}`
+        );
+
         return {
           content: [
             {
               type: 'text',
-              text: JSON.stringify(result.value, null, 2)
+              text: JSON.stringify(output, null, 2)
             }
           ]
         };
@@ -181,7 +253,7 @@ async function startMcpServer() {
     timestamp: new Date().toISOString(),
     event: 'mcp_server_started',
     name: 'visus-mcp',
-    version: '0.2.0',
+    version: '0.6.0',
     tools: ['visus_fetch', 'visus_fetch_structured', 'visus_read', 'visus_search']
   }));
 

package/src/sanitizer/elicit-runner.ts

@@ -0,0 +1,125 @@
+/**
+ * Elicitation Runner
+ *
+ * Executes MCP elicitation requests with comprehensive error handling
+ * and fail-safe behavior. If elicitation fails for ANY reason, the
+ * sanitized content is delivered — security is never compromised.
+ *
+ * Error handling includes:
+ * - Client doesn't support elicitation
+ * - Client timeout
+ * - Network errors
+ * - Unexpected responses
+ *
+ * Fail-safe principle: Elicitation is UX. Sanitization is security.
+ * Never block content delivery due to elicitation failures.
+ */
+
+import type { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import type { ThreatReport } from './threat-reporter.js';
+import { buildElicitMessage, ElicitSchema } from './hitl-gate.js';
+
+/**
+ * Result of elicitation execution
+ */
+export interface ElicitationResult {
+  /** Whether user chose to proceed with sanitized content */
+  proceed: boolean;
+  /** Whether to include threat report in response */
+  includeReport: boolean;
+}
+
+/**
+ * Runs MCP elicitation for CRITICAL threat confirmation
+ *
+ * Three possible outcomes:
+ * 1. User accepts → proceed: true, includeReport: user's choice
+ * 2. User declines → proceed: false, includeReport: false
+ * 3. User cancels → proceed: false, includeReport: false
+ *
+ * Fail-safe: Any error → proceed: true, includeReport: true
+ * (Content reaches user in sanitized form, security maintained)
+ *
+ * CRITICAL: Only ONE elicitation per tool call is allowed per MCP spec.
+ * Calling this function twice in the same request will cause timeout.
+ *
+ * @param server The MCP server instance
+ * @param threatReport The CRITICAL threat report
+ * @param url The source URL
+ * @returns Elicitation result with proceed and includeReport flags
+ */
+export async function runElicitation(
+  server: Server,
+  threatReport: ThreatReport,
+  url: string
+): Promise<ElicitationResult> {
+  try {
+    // Build user-facing message
+    const message = buildElicitMessage(threatReport, url);
+
+    // Execute elicitation
+    const result = await server.elicitInput({
+      mode: 'form' as const,
+      message,
+      requestedSchema: ElicitSchema as any // Type cast due to SDK's strict schema definition
+    });
+
+    // Handle user response
+    if (result.action === 'accept') {
+      // User explicitly accepted
+      // Content values can be string | number | boolean | string[]
+      const proceed = result.content?.proceed === true || result.content?.proceed === 'true';
+      const includeReport = result.content?.view_report === true || result.content?.view_report === 'true' || result.content?.view_report === undefined;
+
+      return {
+        proceed,
+        includeReport: proceed ? includeReport : false // Only include report if proceeding
+      };
+    }
+
+    if (result.action === 'decline') {
+      // User explicitly declined
+      return {
+        proceed: false,
+        includeReport: false
+      };
+    }
+
+    if (result.action === 'cancel') {
+      // User canceled or dismissed dialog
+      return {
+        proceed: false,
+        includeReport: false
+      };
+    }
+
+    // Unknown action (should never happen)
+    console.error(JSON.stringify({
+      timestamp: new Date().toISOString(),
+      event: 'elicitation_unknown_action',
+      action: result.action,
+      message: 'Unexpected elicitation action, proceeding with sanitized content (fail-safe)'
+    }));
+
+    return {
+      proceed: true,
+      includeReport: true
+    };
+
+  } catch (error) {
+    // Elicitation failed — FAIL SAFE
+    // Client may not support elicitation, or timeout occurred
+    // Proceed with sanitized content + include report
+    console.error(JSON.stringify({
+      timestamp: new Date().toISOString(),
+      event: 'elicitation_failed',
+      error: error instanceof Error ? error.message : String(error),
+      message: 'Elicitation not supported or timed out, proceeding with sanitized content (fail-safe)'
+    }));
+
+    return {
+      proceed: true,
+      includeReport: true
+    };
+  }
+}