visus-mcp 0.6.2 → 0.8.0

package/src/content-handlers/index.ts

@@ -0,0 +1,72 @@
+/**
+ * Content Handlers Module
+ *
+ * Central routing for content-type specific sanitization handlers.
+ * Detects MIME type from Content-Type header and routes to appropriate handler.
+ *
+ * Supported content types:
+ * - application/pdf -> PDF handler
+ * - application/json -> JSON handler
+ * - image/svg+xml -> SVG handler
+ *
+ * Unsupported types return structured rejection (no throw).
+ */
+
+import { handlePdf } from './pdf-handler.js';
+import { handleJson } from './json-handler.js';
+import { handleSvg } from './svg-handler.js';
+import type { HandlerResult } from './types.js';
+
+/**
+ * Normalize Content-Type header to base MIME type
+ *
+ * Examples:
+ * - "application/pdf; charset=utf-8" -> "application/pdf"
+ * - "application/json" -> "application/json"
+ * - "IMAGE/SVG+XML" -> "image/svg+xml"
+ *
+ * @param contentType - Raw Content-Type header value
+ * @returns Normalized MIME type (lowercase, parameters stripped)
+ */
+export function normalizeMimeType(contentType: string): string {
+  return contentType.toLowerCase().split(';')[0].trim();
+}
+
+/**
+ * Route content to appropriate handler based on MIME type
+ *
+ * @param content - Raw content (string or Buffer)
+ * @param contentType - Content-Type header value
+ * @returns Handler result (success or error/rejected)
+ */
+export async function routeContentHandler(
+  content: string | Buffer,
+  contentType: string
+): Promise<HandlerResult> {
+  const mimeType = normalizeMimeType(contentType);
+
+  // Route to appropriate handler
+  switch (mimeType) {
+    case 'application/pdf':
+      return handlePdf(content, mimeType);
+
+    case 'application/json':
+    case 'text/json':
+      return handleJson(content, mimeType);
+
+    case 'image/svg+xml':
+      return handleSvg(content, mimeType);
+
+    default:
+      // Unsupported content type - return structured rejection
+      return {
+        status: 'rejected',
+        reason: 'UNSUPPORTED_CONTENT_TYPE',
+        mime: mimeType,
+        message: `Content type ${mimeType} is not supported by Visus-MCP.`
+      };
+  }
+}
+
+// Re-export types
+export type { HandlerResult, HandlerSuccessResult, HandlerErrorResult } from './types.js';

package/src/content-handlers/json-handler.ts

@@ -0,0 +1,137 @@
+/**
+ * JSON Content Handler
+ *
+ * Handles application/json content type. Recursively traverses all nodes in the JSON
+ * object tree and applies the full injection pattern registry to every string value.
+ *
+ * What it handles:
+ * - All string values in the JSON tree (any depth)
+ * - Arrays, nested objects, and mixed-type arrays
+ * - Falls back to plain text pipeline if JSON.parse fails
+ *
+ * What it strips:
+ * - Nothing (preserves original structure)
+ *
+ * What it passes through:
+ * - Sanitized JSON with original structure preserved
+ * - All non-string values pass through unchanged
+ */
+
+import { sanitize } from '../sanitizer/index.js';
+import type { HandlerResult } from './types.js';
+
+/**
+ * Handle JSON content
+ *
+ * @param content - Raw JSON string
+ * @param mimeType - Original MIME type
+ * @returns Sanitized handler result
+ */
+export function handleJson(
+  content: string | Buffer,
+  mimeType: string
+): HandlerResult {
+  const startTime = Date.now();
+
+  // Convert Buffer to string if needed
+  const jsonString = Buffer.isBuffer(content) ? content.toString('utf-8') : content;
+
+  try {
+    // Parse JSON
+    const parsed = JSON.parse(jsonString);
+
+    // Track sanitization metadata across all fields
+    let sanitizedFieldCount = 0;
+    const allPatternsDetected = new Set<string>();
+    const allPiiTypesRedacted = new Set<string>();
+    const allPiiAllowlisted: Array<{ type: string; value: string; reason: string }> = [];
+
+    // Recursively sanitize all string values
+    const sanitized = recursiveSanitize(parsed, (text: string) => {
+      const result = sanitize(text);
+      if (result.sanitization.content_modified) {
+        sanitizedFieldCount++;
+      }
+
+      // Aggregate metadata
+      result.sanitization.patterns_detected.forEach(p => allPatternsDetected.add(p));
+      result.sanitization.pii_types_redacted.forEach(p => allPiiTypesRedacted.add(p));
+      allPiiAllowlisted.push(...result.sanitization.pii_allowlisted);
+
+      return result.content;
+    });
+
+    // Re-stringify with 2-space indent
+    const sanitizedJson = JSON.stringify(sanitized, null, 2);
+
+    const processingTime = Date.now() - startTime;
+
+    return {
+      status: 'sanitized',
+      content_type: mimeType,
+      sanitized_content: sanitizedJson,
+      sanitization: {
+        patterns_detected: Array.from(allPatternsDetected),
+        pii_types_redacted: Array.from(allPiiTypesRedacted),
+        pii_allowlisted: allPiiAllowlisted,
+        sanitized_fields: sanitizedFieldCount
+      },
+      processing_time_ms: processingTime
+    };
+
+  } catch (error) {
+    // JSON.parse failed - fall back to plain text sanitization
+    const sanitizationResult = sanitize(jsonString);
+
+    const processingTime = Date.now() - startTime;
+
+    return {
+      status: 'sanitized',
+      content_type: mimeType,
+      sanitized_content: sanitizationResult.content,
+      sanitization: {
+        patterns_detected: sanitizationResult.sanitization.patterns_detected,
+        pii_types_redacted: sanitizationResult.sanitization.pii_types_redacted,
+        pii_allowlisted: sanitizationResult.sanitization.pii_allowlisted,
+        sanitized_fields: sanitizationResult.sanitization.patterns_detected.length
+      },
+      processing_time_ms: processingTime
+    };
+  }
+}
+
+/**
+ * Recursively traverse JSON tree and sanitize all string values
+ *
+ * @param obj - JSON object/array/primitive
+ * @param sanitizeFn - Function to sanitize string values
+ * @returns Sanitized object with same structure
+ */
+function recursiveSanitize(obj: any, sanitizeFn: (text: string) => string): any {
+  // Handle null
+  if (obj === null) {
+    return null;
+  }
+
+  // Handle string - sanitize it
+  if (typeof obj === 'string') {
+    return sanitizeFn(obj);
+  }
+
+  // Handle array - recursively sanitize each element
+  if (Array.isArray(obj)) {
+    return obj.map((item) => recursiveSanitize(item, sanitizeFn));
+  }
+
+  // Handle object - recursively sanitize each value
+  if (typeof obj === 'object') {
+    const sanitizedObj: Record<string, any> = {};
+    for (const [key, value] of Object.entries(obj)) {
+      sanitizedObj[key] = recursiveSanitize(value, sanitizeFn);
+    }
+    return sanitizedObj;
+  }
+
+  // Handle primitives (number, boolean, undefined) - pass through
+  return obj;
+}

package/src/content-handlers/pdf-handler.ts

@@ -0,0 +1,91 @@
+/**
+ * PDF Content Handler
+ *
+ * Handles application/pdf content type. Extracts text and metadata from PDF files,
+ * passes all text through the injection pattern registry, and returns sanitized plain text.
+ *
+ * What it handles:
+ * - PDF body text (full document)
+ * - PDF metadata: title, author, subject, keywords, creator, producer
+ * - Annotation text
+ * - Form field values
+ *
+ * What it strips:
+ * - Embedded binary objects (fonts, images, attachments)
+ * - Returns only extracted text, not original binary
+ *
+ * What it passes through:
+ * - All extracted text after injection pattern sanitization
+ */
+
+import { PDFParse } from 'pdf-parse';
+import { sanitize } from '../sanitizer/index.js';
+import type { HandlerResult } from './types.js';
+
+/**
+ * Handle PDF content
+ *
+ * @param content - Raw PDF binary data as Buffer or string
+ * @param mimeType - Original MIME type
+ * @returns Sanitized handler result
+ */
+export async function handlePdf(
+  content: string | Buffer,
+  mimeType: string
+): Promise<HandlerResult> {
+  const startTime = Date.now();
+
+  try {
+    // Ensure we have a Buffer
+    const buffer = Buffer.isBuffer(content) ? content : Buffer.from(content);
+
+    // Parse PDF using pdf-parse v2 API
+    const parser = new PDFParse({ data: buffer });
+
+    // Get text and metadata separately
+    const textResult = await parser.getText();
+    const infoResult = await parser.getInfo();
+
+    // Extract text and metadata
+    const bodyText = textResult.text || '';
+    const metadata = infoResult.info || {};
+
+    // Build combined text from body + metadata
+    let combinedText = bodyText;
+
+    // Append metadata fields
+    const metadataFields = ['Title', 'Author', 'Subject', 'Keywords', 'Creator', 'Producer'];
+    for (const field of metadataFields) {
+      const value = metadata[field];
+      if (value && typeof value === 'string') {
+        combinedText += `\n\n${field}: ${value}`;
+      }
+    }
+
+    // Pass through injection detection pipeline
+    const sanitizationResult = sanitize(combinedText);
+
+    const processingTime = Date.now() - startTime;
+
+    return {
+      status: 'sanitized',
+      content_type: mimeType,
+      sanitized_content: sanitizationResult.content,
+      sanitization: {
+        patterns_detected: sanitizationResult.sanitization.patterns_detected,
+        pii_types_redacted: sanitizationResult.sanitization.pii_types_redacted,
+        pii_allowlisted: sanitizationResult.sanitization.pii_allowlisted,
+        sanitized_fields: sanitizationResult.sanitization.patterns_detected.length
+      },
+      processing_time_ms: processingTime
+    };
+
+  } catch (error) {
+    return {
+      status: 'error',
+      reason: 'PDF_PARSE_FAILED',
+      mime: mimeType,
+      message: error instanceof Error ? error.message : String(error)
+    };
+  }
+}

package/src/content-handlers/svg-handler.ts

@@ -0,0 +1,243 @@
+/**
+ * SVG Content Handler
+ *
+ * Handles image/svg+xml content type. SVG is XML, not a binary image, and can contain
+ * executable code and external references. This handler strips dangerous elements and
+ * attributes unconditionally, then sanitizes remaining text content.
+ *
+ * What it handles:
+ * - All text content in SVG elements after stripping dangerous parts
+ *
+ * What it strips (unconditionally, no attempt to sanitize):
+ * - <script> elements and all children
+ * - <use> elements with external href or xlink:href attributes
+ * - <foreignObject> elements and all children
+ * - All event handler attributes (onload, onclick, onerror, etc.)
+ * - <set> and <animate> elements that reference external resources
+ * - data: URI attributes
+ *
+ * What it passes through (after injection scan):
+ * - Path data (d attribute)
+ * - Text elements and their content
+ * - <title> and <desc> elements
+ * - Presentation attributes (fill, stroke, transform, etc.)
+ * - viewBox, width, height attributes
+ */
+
+import { XMLParser, XMLBuilder } from 'fast-xml-parser';
+import { sanitize } from '../sanitizer/index.js';
+import type { HandlerResult } from './types.js';
+
+/**
+ * Handle SVG content
+ *
+ * @param content - Raw SVG XML string or Buffer
+ * @param mimeType - Original MIME type
+ * @returns Sanitized handler result
+ */
+export function handleSvg(
+  content: string | Buffer,
+  mimeType: string
+): HandlerResult {
+  const startTime = Date.now();
+
+  // Convert Buffer to string if needed
+  const svgString = Buffer.isBuffer(content) ? content.toString('utf-8') : content;
+
+  try {
+    // Parse SVG XML
+    const parser = new XMLParser({
+      ignoreAttributes: false,
+      attributeNamePrefix: '@_',
+      textNodeName: '#text',
+      preserveOrder: false,
+      removeNSPrefix: true,
+    });
+
+    const parsed = parser.parse(svgString);
+
+    // Track sanitized field count
+    let sanitizedFieldCount = 0;
+
+    // Strip dangerous elements and attributes
+    const stripped = stripDangerousContent(parsed);
+
+    // Extract all text content for injection scanning
+    const textContent = extractTextContent(stripped);
+
+    // Run text through injection detection
+    let sanitizationResult;
+    if (textContent.length > 0) {
+      sanitizationResult = sanitize(textContent);
+      if (sanitizationResult.sanitization.content_modified) {
+        sanitizedFieldCount = sanitizationResult.sanitization.patterns_detected.length;
+      }
+    }
+
+    // Rebuild SVG
+    const builder = new XMLBuilder({
+      ignoreAttributes: false,
+      attributeNamePrefix: '@_',
+      textNodeName: '#text',
+      format: true,
+      suppressEmptyNode: true,
+    });
+
+    const sanitizedSvg = builder.build(stripped);
+
+    const processingTime = Date.now() - startTime;
+
+    return {
+      status: 'sanitized',
+      content_type: mimeType,
+      sanitized_content: sanitizedSvg,
+      sanitization: {
+        patterns_detected: sanitizationResult?.sanitization.patterns_detected || [],
+        pii_types_redacted: sanitizationResult?.sanitization.pii_types_redacted || [],
+        pii_allowlisted: sanitizationResult?.sanitization.pii_allowlisted || [],
+        sanitized_fields: sanitizedFieldCount
+      },
+      processing_time_ms: processingTime
+    };
+
+  } catch (error) {
+    return {
+      status: 'error',
+      reason: 'SVG_PARSE_FAILED',
+      mime: mimeType,
+      message: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+
+/**
+ * Strip dangerous content from parsed SVG
+ *
+ * Removes:
+ * - <script> elements
+ * - <foreignObject> elements
+ * - <use> with external href
+ * - Event handler attributes
+ * - <set> and <animate> with external references
+ * - data: URIs
+ */
+function stripDangerousContent(node: any): any {
+  if (typeof node !== 'object' || node === null) {
+    return node;
+  }
+
+  // Handle arrays
+  if (Array.isArray(node)) {
+    return node
+      .filter((item) => !shouldRemoveElement(item))
+      .map((item) => stripDangerousContent(item));
+  }
+
+  // Handle objects
+  const result: any = {};
+
+  for (const [key, value] of Object.entries(node)) {
+    // Skip dangerous elements
+    if (key === 'script' || key === 'foreignObject') {
+      continue;
+    }
+
+    // Handle <use> with external href
+    if (key === 'use' && typeof value === 'object' && value !== null) {
+      const href = (value as any)['@_href'] || (value as any)['@_xlink:href'];
+      if (href && (href.startsWith('http://') || href.startsWith('https://') || href.startsWith('//'))) {
+        continue;
+      }
+    }
+
+    // Handle <set> and <animate> with external references
+    if ((key === 'set' || key === 'animate') && typeof value === 'object' && value !== null) {
+      const href = (value as any)['@_href'] || (value as any)['@_xlink:href'];
+      if (href && (href.startsWith('http://') || href.startsWith('https://') || href.startsWith('//'))) {
+        continue;
+      }
+    }
+
+    // Strip event handler attributes
+    if (key.startsWith('@_on')) {
+      continue;
+    }
+
+    // Strip data: URIs
+    if (typeof value === 'string' && value.startsWith('data:')) {
+      result[key] = '';
+      continue;
+    }
+
+    // Strip attributes with data: URIs
+    if (key.startsWith('@_') && typeof value === 'string' && value.startsWith('data:')) {
+      continue;
+    }
+
+    // Recursively process
+    result[key] = stripDangerousContent(value);
+  }
+
+  return result;
+}
+
+/**
+ * Check if element should be removed entirely
+ */
+function shouldRemoveElement(element: any): boolean {
+  if (typeof element !== 'object' || element === null) {
+    return false;
+  }
+
+  // Check for dangerous element types
+  const dangerousElements = ['script', 'foreignObject'];
+  for (const dangerous of dangerousElements) {
+    if (dangerous in element) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+/**
+ * Extract all text content from SVG for injection scanning
+ */
+function extractTextContent(node: any): string {
+  if (typeof node !== 'object' || node === null) {
+    return '';
+  }
+
+  if (typeof node === 'string') {
+    return node;
+  }
+
+  if (Array.isArray(node)) {
+    return node.map((item) => extractTextContent(item)).join(' ');
+  }
+
+  let text = '';
+
+  for (const [key, value] of Object.entries(node)) {
+    // Extract text from text nodes
+    if (key === '#text' && typeof value === 'string') {
+      text += value + ' ';
+    }
+
+    // Extract from title and desc elements (can be string or object)
+    if (key === 'title' || key === 'desc') {
+      if (typeof value === 'string') {
+        text += value + ' ';
+      } else if (typeof value === 'object') {
+        text += extractTextContent(value) + ' ';
+      }
+    }
+
+    // Recursively extract from other children
+    if (key !== 'title' && key !== 'desc' && typeof value === 'object') {
+      text += extractTextContent(value) + ' ';
+    }
+  }
+
+  return text.trim();
+}

package/src/content-handlers/types.ts

@@ -0,0 +1,44 @@
+/**
+ * Content Handler Types
+ *
+ * Shared interfaces for content-type specific handlers.
+ */
+
+/**
+ * Success result from a content handler
+ */
+export interface HandlerSuccessResult {
+  status: 'sanitized';
+  content_type: string;
+  sanitized_content: string;
+  sanitization: {
+    patterns_detected: string[];
+    pii_types_redacted: string[];
+    pii_allowlisted: Array<{ type: string; value: string; reason: string }>;
+    sanitized_fields: number;
+  };
+  processing_time_ms: number;
+}
+
+/**
+ * Error result from a content handler
+ */
+export interface HandlerErrorResult {
+  status: 'error' | 'rejected';
+  reason: string;
+  mime: string;
+  message: string;
+}
+
+/**
+ * Union type for all handler results
+ */
+export type HandlerResult = HandlerSuccessResult | HandlerErrorResult;
+
+/**
+ * Content handler function signature
+ */
+export type ContentHandler = (
+  content: string | Buffer,
+  mimeType: string
+) => Promise<HandlerResult> | HandlerResult;

package/src/tools/fetch.ts

@@ -10,6 +10,7 @@ import { renderPage } from '../browser/playwright-renderer.js';
 import { sanitize } from '../sanitizer/index.js';
 import { truncateContent } from '../utils/truncate.js';
 import { detectFormat, convertJson, convertXml, convertRss } from '../utils/format-converter.js';
+import { routeContentHandler, normalizeMimeType } from '../content-handlers/index.js';
 import type { VisusFetchInput, VisusFetchOutput, Result } from '../types.js';
 import { Err } from '../types.js';
 
@@ -41,8 +42,72 @@ export async function visusFetch(input: VisusFetchInput): Promise<Result<VisusFe
     const { html, title, contentType } = renderResult.value;
     const rawContent = html || '';
 
-    // Step 2: Detect format and apply format-appropriate conversion
+    // Step 2: Detect content type and route to specialized handlers if applicable
     const detectedContentType = contentType || 'text/html';
+    const normalizedMime = normalizeMimeType(detectedContentType);
+
+    // Check if content requires specialized handler (PDF, JSON, SVG)
+    if (normalizedMime === 'application/pdf' ||
+        normalizedMime === 'application/json' ||
+        normalizedMime === 'text/json' ||
+        normalizedMime === 'image/svg+xml') {
+
+      // Route to specialized content handler
+      const handlerResult = await routeContentHandler(rawContent, detectedContentType);
+
+      // Handle unsupported or error cases
+      if (handlerResult.status === 'rejected' || handlerResult.status === 'error') {
+        return Err(new Error(handlerResult.message));
+      }
+
+      // Type guard: ensure we have a success result
+      if (handlerResult.status !== 'sanitized') {
+        return Err(new Error('Unexpected handler result status'));
+      }
+
+      // Handler success - use the already-sanitized content
+      const sanitizedContent = handlerResult.sanitized_content;
+      const sanitization = handlerResult.sanitization;
+      const truncationResult = truncateContent(sanitizedContent);
+
+      // Determine format_detected based on MIME type
+      let formatDetected: 'html' | 'json' | 'xml' | 'rss' = 'html';
+      if (normalizedMime === 'application/json' || normalizedMime === 'text/json') {
+        formatDetected = 'json';
+      } else if (normalizedMime === 'image/svg+xml') {
+        formatDetected = 'xml'; // SVG is XML-based
+      } else if (normalizedMime === 'application/pdf') {
+        // PDF doesn't have a format_detected value in the current schema
+        // Leaving as 'html' for now
+      }
+
+      const output: VisusFetchOutput = {
+        url,
+        content: truncationResult.content,
+        sanitization: {
+          patterns_detected: sanitization.patterns_detected,
+          pii_types_redacted: sanitization.pii_types_redacted,
+          pii_allowlisted: sanitization.pii_allowlisted,
+          content_modified: sanitization.sanitized_fields > 0
+        },
+        metadata: {
+          title: title || 'Untitled',
+          fetched_at: new Date().toISOString(),
+          content_length_original: rawContent.length,
+          content_length_sanitized: sanitizedContent.length,
+          format_detected: formatDetected,
+          content_type: detectedContentType,
+          ...(truncationResult.truncated && {
+            truncated: true,
+            truncated_at_chars: truncationResult.truncated_at_chars
+          })
+        }
+      };
+
+      return { ok: true, value: output };
+    }
+
+    // Step 3: For HTML/XML/RSS - use existing format conversion flow
     const formatType = detectFormat(detectedContentType);
 
     let processedContent = rawContent;
@@ -57,15 +122,15 @@ export async function visusFetch(input: VisusFetchInput): Promise<Result<VisusFe
     }
     // For 'html' format, processedContent remains as rawContent
 
-    // Step 3: CRITICAL - Sanitize content (injection detection + PII redaction with allowlisting)
+    // Step 4: CRITICAL - Sanitize content (injection detection + PII redaction with allowlisting)
     // This step CANNOT be skipped or bypassed
     const sanitizationResult = sanitize(processedContent, url);
 
-    // Step 3: Apply token ceiling truncation (AFTER sanitization)
+    // Step 5: Apply token ceiling truncation (AFTER sanitization)
     // Anthropic MCP Directory enforces 25,000 token response limit
     const truncationResult = truncateContent(sanitizationResult.content);
 
-    // Step 4: Build output
+    // Step 6: Build output
     const output: VisusFetchOutput = {
       url,
       content: truncationResult.content,