visus-mcp 0.2.0 → 0.6.0

package/README.md

@@ -147,13 +147,22 @@ Restart Claude Desktop. Visus tools are now available to Claude.
 
 ### `visus_fetch`
 
-Fetch and sanitize a web page.
+Fetch and sanitize a web page with automatic format detection. Supports HTML, JSON, XML, and RSS/Atom feeds. Includes NIST AI 600-1 / OWASP LLM / MITRE ATLAS aligned threat report when injection or PII is detected.
+
+**Supported Formats:**
+- **HTML** (`text/html`, `application/xhtml+xml`) - Standard web pages, returned as-is
+- **JSON** (`application/json`) - API responses, formatted with 2-space indentation
+- **XML** (`application/xml`, `text/xml`) - XML documents, converted to clean text representation
+- **RSS/Atom** (`application/rss+xml`, `application/atom+xml`) - Feeds converted to Markdown with up to 10 items
+
+### `visus_read`
+
+Extract clean article content from a web page using Mozilla Readability (reader mode). Includes NIST AI 600-1 / OWASP LLM / MITRE ATLAS aligned threat report when injection or PII is detected.
 
 **Input:**
 ```json
 {
-  "url": "https://example.com",
-  "format": "markdown",  // or "text"
+  "url": "https://example.com/article",
   "timeout_ms": 10000    // optional
 }
 ```
@@ -161,25 +170,59 @@ Fetch and sanitize a web page.
 **Output:**
 ```json
 {
-  "url": "https://example.com",
-  "content": "# Page Title\n\nSanitized page content...",
-  "sanitization": {
-    "patterns_detected": ["direct_instruction_injection"],
-    "pii_types_redacted": ["email", "phone"],
-    "content_modified": true
-  },
+  "url": "https://example.com/article",
+  "content": "This is the main article content, stripped of navigation, ads, and boilerplate...",
   "metadata": {
-    "title": "Example Domain",
-    "fetched_at": "2024-01-15T10:30:00.000Z",
-    "content_length_original": 5000,
-    "content_length_sanitized": 4800
+    "title": "Article Title",
+    "author": "Jane Doe",
+    "published": "2024-01-15T10:00:00Z",
+    "word_count": 1250,
+    "reader_mode_available": true,
+    "sanitized": true,
+    "injections_removed": 0,
+    "pii_redacted": 1,
+    "truncated": false,
+    "fetched_at": "2024-01-15T10:30:00.000Z"
   }
 }
 ```
 
+### `visus_search`
+
+Search the web via DuckDuckGo and return sanitized results with prompt injection and PII removed. Use before `visus_fetch` or `visus_read` to safely discover and then read pages. Includes NIST AI 600-1 / OWASP LLM / MITRE ATLAS aligned threat report when injection or PII is detected.
+
+**Input:**
+```json
+{
+  "query": "TypeScript programming",
+  "max_results": 5    // optional, default: 5, max: 10
+}
+```
+
+**Output:**
+```json
+{
+  "query": "TypeScript programming",
+  "result_count": 5,
+  "sanitized": true,
+  "results": [
+    {
+      "title": "TypeScript is a strongly typed programming language.",
+      "url": "https://typescriptlang.org",
+      "snippet": "TypeScript is a strongly typed programming language that builds on JavaScript...",
+      "injections_removed": 0,
+      "pii_redacted": 0
+    }
+  ],
+  "total_injections_removed": 0
+}
+```
+
+All search result titles and snippets are independently sanitized before reaching the LLM.
+
 ### `visus_fetch_structured`
 
-Extract structured data from a web page according to a schema.
+Extract structured data from a web page according to a schema. Includes NIST AI 600-1 / OWASP LLM / MITRE ATLAS aligned threat report when injection or PII is detected.
 
 **Input:**
 ```json
@@ -221,6 +264,418 @@ All extracted fields are individually sanitized.
 
 ---
 
+## Threat Reporting
+
+When prompt injection or PII is detected, Visus automatically generates a structured threat report with two output layers:
+
+### 1. TOON-Formatted Findings (Token-Efficient)
+
+Findings are encoded using [TOON format](https://toonformat.dev) for token efficiency while preserving machine readability. Each finding includes:
+
+- Pattern ID and category
+- Severity level (CRITICAL, HIGH, MEDIUM, LOW)
+- Confidence score
+- Framework alignments (OWASP LLM Top 10, NIST AI 600-1, MITRE ATLAS)
+- Remediation status
+
+### 2. Markdown Compliance Report (Human-Readable)
+
+A formatted Markdown table renders cleanly in Claude Desktop and GitHub, showing:
+
+- Overall severity assessment
+- Findings summary by severity
+- Detailed findings table with framework mappings
+- PII redaction statistics
+- Remediation confirmation
+
+### Framework Alignments
+
+Every detected threat is mapped to three compliance frameworks:
+
+- **[OWASP LLM Top 10 (2025)](https://owasp.org/www-project-top-10-for-large-language-model-applications/)**: Industry-standard LLM security risks
+- **[NIST AI 600-1](https://csrc.nist.gov/pubs/ai/600/1/final)**: Generative AI Profile for risk management
+- **[MITRE ATLAS](https://atlas.mitre.org/)**: Adversarial Threat Landscape for AI Systems
+
+### When Reports Are Generated
+
+Threat reports are included in tool responses **only when findings exist**:
+- ✅ Injections detected → Report included
+- ✅ PII redacted → Report included
+- ❌ Clean content → Report omitted (zero overhead)
+
+### Example Threat Report
+
+When a HIGH severity injection is detected:
+
+```markdown
+---
+## 🟠 Visus Threat Report
+**Generated:** 2026-03-23T14:30:00.000Z
+**Source:** https://malicious.example.com
+**Overall Severity:** HIGH
+**Framework:** OWASP LLM Top 10 | NIST AI 600-1 | MITRE ATLAS
+
+### Findings Summary
+| Severity | Count |
+|---|---|
+| 🔴 CRITICAL | 0 |
+| 🟠 HIGH | 1 |
+| 🟡 MEDIUM | 0 |
+| 🟢 LOW | 0 |
+
+### Findings Detail
+| # | Category | Severity | Confidence | OWASP | MITRE |
+|---|---|---|---|---|---|
+| 1 | role_hijacking | CRITICAL | 95% | LLM01:2025 | AML.T0051.000 |
+
+### Remediation Status
+✅ All findings sanitized. Content delivered clean.
+
+*Report generated by Visus MCP — Security-first web access for Claude*
+---
+```
+
+**Note:** PDF export for compliance artifacts is on the roadmap for a future `visus_report` tool.
+
+---
+
+## Examples
+
+### Example 1: Public Health Page with PII Allowlist
+
+Fetching a MedlinePlus health information page demonstrates both injection pattern detection and the domain-scoped PII allowlist feature.
+
+**Tool Call:**
+```json
+{
+  "url": "https://medlineplus.gov/poisoning.html",
+  "format": "markdown"
+}
+```
+
+**Sanitized Output (excerpt):**
+```json
+{
+  "url": "https://medlineplus.gov/poisoning.html",
+  "content": "# Poisoning\n\n**Call 1-800-222-1222** for immediate help...\n\n**Contact:** [REDACTED:EMAIL] for general inquiries...",
+  "sanitization": {
+    "patterns_detected": [],
+    "pii_types_redacted": ["email"],
+    "pii_allowlisted": [
+      {
+        "type": "phone",
+        "value": "1-800-222-1222",
+        "reason": "Trusted health authority number on medlineplus.gov (Poison Control)"
+      }
+    ],
+    "content_modified": true
+  },
+  "metadata": {
+    "title": "Poisoning: MedlinePlus",
+    "content_length_original": 15234,
+    "content_length_sanitized": 15180
+  }
+}
+```
+
+**What Visus caught:** Regular email addresses were redacted (`[REDACTED:EMAIL]`), but the Poison Control hotline number was preserved because it appears on a trusted `.gov` health domain. This demonstrates the PII allowlist in action — critical health resources remain accessible while general contact info is scrubbed.
+
+---
+
+### Example 2: Structured Data Extraction from Documentation
+
+Extract navigation links and headings from a documentation page.
+
+**Tool Call:**
+```json
+{
+  "url": "https://docs.github.com/en",
+  "schema": {
+    "main_heading": "h1",
+    "first_link": "link url",
+    "first_link_text": "link text",
+    "description": "paragraph text"
+  }
+}
+```
+
+**Sanitized Output:**
+```json
+{
+  "url": "https://docs.github.com/en",
+  "data": {
+    "main_heading": "GitHub Docs",
+    "first_link": "/en/get-started",
+    "first_link_text": "Get started",
+    "description": "Help for wherever you are on your GitHub journey."
+  },
+  "sanitization": {
+    "patterns_detected": [],
+    "pii_types_redacted": [],
+    "pii_allowlisted": [],
+    "content_modified": false
+  },
+  "metadata": {
+    "title": "GitHub Docs",
+    "content_length_original": 45123,
+    "content_length_sanitized": 45123
+  }
+}
+```
+
+**What Visus caught:** This page was clean — no injection patterns or PII detected. The structured extraction returned all requested fields with `content_modified: false`, indicating the sanitizer validated the content but made no changes.
+
+---
+
+### Example 3: JavaScript-Heavy SPA with Playwright Rendering
+
+Modern single-page applications require JavaScript execution. Visus uses headless Chromium via Playwright to render dynamic content before sanitization.
+
+**Tool Call:**
+```json
+{
+  "url": "https://github.com/anthropics/anthropic-sdk-typescript",
+  "format": "markdown",
+  "timeout_ms": 15000
+}
+```
+
+**Sanitized Output (excerpt):**
+```json
+{
+  "url": "https://github.com/anthropics/anthropic-sdk-typescript",
+  "content": "# anthropic-sdk-typescript\n\n**Repository:** anthropics/anthropic-sdk-typescript\n\n**Description:** TypeScript SDK for Anthropic's Claude API...\n\n**Latest commit:** [REDACTED:COMMIT_HASH] by [REDACTED:EMAIL]...",
+  "sanitization": {
+    "patterns_detected": [],
+    "pii_types_redacted": ["email"],
+    "pii_allowlisted": [],
+    "content_modified": true
+  },
+  "metadata": {
+    "title": "GitHub - anthropics/anthropic-sdk-typescript",
+    "content_length_original": 23456,
+    "content_length_sanitized": 23401
+  }
+}
+```
+
+**What Visus caught:** The page rendered completely via Playwright (including React components, lazy-loaded content, and dynamic navigation). Email addresses in commit author fields were redacted. No injection patterns were detected in this legitimate repository page.
+
+**Key difference from static fetchers:** Tools like `curl` or basic HTTP clients would return an empty `<div id="root">` for SPAs. Visus renders the full JavaScript application before sanitization, ensuring you get the actual page content Claude sees.
+
+---
+
+### Example 4: Reader Mode for Context-Efficient Article Reading
+
+When you need clean article content without navigation clutter, use `visus_read` to extract the main text using Mozilla Readability.
+
+**Tool Call:**
+```json
+{
+  "url": "https://en.wikipedia.org/wiki/Prompt_injection",
+  "timeout_ms": 15000
+}
+```
+
+**Sanitized Output (excerpt):**
+```json
+{
+  "url": "https://en.wikipedia.org/wiki/Prompt_injection",
+  "content": "Prompt injection is a type of cyberattack that involves adding malicious instructions to a prompt for an AI system...\n\n[Main article content continues, stripped of navigation, sidebars, and Wikipedia UI elements]\n\nSee also:\n- AI safety\n- Adversarial machine learning\n- Computer security...",
+  "metadata": {
+    "title": "Prompt injection - Wikipedia",
+    "author": null,
+    "published": null,
+    "word_count": 892,
+    "reader_mode_available": true,
+    "sanitized": true,
+    "injections_removed": 0,
+    "pii_redacted": 0,
+    "truncated": false,
+    "fetched_at": "2024-01-15T14:22:00.000Z"
+  }
+}
+```
+
+**What Visus caught:** Readability successfully extracted the main article content, removing Wikipedia's navigation sidebar, footer links, and UI chrome. The extracted text is ~70% smaller than the full page HTML, saving tokens while preserving all essential information. No injection patterns or PII were detected in this educational content.
+
+**Use case:** Reader mode is ideal for documentation pages, news articles, blog posts, and any content-heavy page where you want the text without the surrounding UI. The `word_count` field helps you estimate token usage before processing.
+
+---
+
+### Example 5: Safe Web Search with Injection Detection
+
+Search the web safely using `visus_search` with DuckDuckGo, demonstrating how search results are sanitized before reaching the LLM.
+
+**Tool Call:**
+```json
+{
+  "query": "AI prompt injection attacks",
+  "max_results": 3
+}
+```
+
+**Sanitized Output (with detected injection):**
+```json
+{
+  "query": "AI prompt injection attacks",
+  "result_count": 3,
+  "sanitized": true,
+  "results": [
+    {
+      "title": "Prompt injection is a type of cyberattack...",
+      "url": "https://en.wikipedia.org/wiki/Prompt_injection",
+      "snippet": "Prompt injection is a type of cyberattack that involves adding malicious instructions to a prompt...",
+      "injections_removed": 0,
+      "pii_redacted": 0
+    },
+    {
+      "title": "[REDACTED:INSTRUCTION_INJECTION] for details contact...",
+      "url": "https://suspicious-seo-spam.example",
+      "snippet": "[REDACTED:INSTRUCTION_INJECTION] [REDACTED:EMAIL]",
+      "injections_removed": 2,
+      "pii_redacted": 1
+    },
+    {
+      "title": "AI Safety: Understanding Prompt Injection.",
+      "url": "https://example.com/ai-safety",
+      "snippet": "Learn how to protect your AI systems from prompt injection vulnerabilities...",
+      "injections_removed": 0,
+      "pii_redacted": 0
+    }
+  ],
+  "total_injections_removed": 2
+}
+```
+
+**What Visus caught:** The second search result contained both a prompt injection pattern ("Ignore previous instructions and...") and an email address. Both were detected and redacted before the result reached the LLM. The other results were clean and passed through unmodified.
+
+**Use case:** Always use `visus_search` before fetching pages to safely discover content. Search results can contain SEO spam, malicious instructions, or PII that would compromise your AI agent.
+
+---
+
+### Example 6: JSON API Response with Format Detection
+
+Fetch JSON data from an API endpoint with automatic formatting and sanitization.
+
+**Tool Call:**
+```json
+{
+  "url": "https://api.github.com/repos/anthropics/anthropic-sdk-typescript",
+  "format": "text"
+}
+```
+
+**Sanitized Output (excerpt):**
+```json
+{
+  "url": "https://api.github.com/repos/anthropics/anthropic-sdk-typescript",
+  "content": "JSON Response:\n\n{\n  \"name\": \"anthropic-sdk-typescript\",\n  \"full_name\": \"anthropics/anthropic-sdk-typescript\",\n  \"description\": \"TypeScript library for the Anthropic API\",\n  \"stargazers_count\": 1234,\n  \"forks_count\": 89\n}",
+  "sanitization": {
+    "patterns_detected": [],
+    "pii_types_redacted": [],
+    "content_modified": false
+  },
+  "metadata": {
+    "title": "",
+    "fetched_at": "2024-01-15T16:30:00.000Z",
+    "content_length_original": 3456,
+    "content_length_sanitized": 3456,
+    "format_detected": "json",
+    "content_type": "application/json"
+  }
+}
+```
+
+**What Visus caught:** The Content-Type header `application/json` was detected, and the raw JSON was automatically formatted with 2-space indentation for readability. The sanitizer validated the content and found no injection patterns or PII (clean API response).
+
+**Format detection features:**
+- Automatically detects Content-Type from HTTP response headers
+- JSON responses are pretty-printed with indentation
+- XML/RSS feeds are converted to clean Markdown
+- All formats pass through the sanitizer pipeline
+- `format_detected` and `content_type` included in metadata
+
+---
+
+### Example 7: RSS Feed with Automatic Markdown Conversion
+
+Fetch an RSS feed and have it automatically converted to clean Markdown format.
+
+**Tool Call:**
+```json
+{
+  "url": "https://blog.example.com/feed.xml"
+}
+```
+
+**Sanitized Output (excerpt):**
+```json
+{
+  "url": "https://blog.example.com/feed.xml",
+  "content": "RSS Feed:\n\n# Example Blog\nThe latest news and updates\n\n## Items\n\n### New Feature Release\n\nWe're excited to announce our latest feature update...\n\nLink: https://blog.example.com/new-feature\nPublished: Mon, 15 Jan 2024 10:00:00 GMT\n\n---\n\n### Security Best Practices\n\nLearn about the latest security recommendations...\n\nLink: https://blog.example.com/security\nPublished: Tue, 16 Jan 2024 14:30:00 GMT\n\n---",
+  "sanitization": {
+    "patterns_detected": [],
+    "pii_types_redacted": [],
+    "content_modified": false
+  },
+  "metadata": {
+    "title": "",
+    "fetched_at": "2024-01-15T16:45:00.000Z",
+    "content_length_original": 5678,
+    "content_length_sanitized": 5678,
+    "format_detected": "rss",
+    "content_type": "application/rss+xml"
+  }
+}
+```
+
+**What Visus caught:** The Content-Type header `application/rss+xml` triggered RSS feed parsing. The feed XML was converted to clean Markdown showing the channel title, description, and up to 10 feed items with titles, links, descriptions (truncated to 200 chars), and publication dates. All content was sanitized for injection patterns.
+
+**RSS/Atom support:**
+- RSS 2.0, RSS 1.0 (RDF), and Atom feed formats supported
+- Extracts channel metadata and up to 10 items
+- Converts to clean Markdown with proper formatting
+- Item descriptions truncated to 200 characters for readability
+- Graceful fallback to XML parsing for invalid feeds
+
+---
+
+### Safe Research Loop (3-Step Workflow)
+
+Combine all three tools for safe, context-efficient web research:
+
+**Step 1: Discover** – Use `visus_search` to find relevant pages safely:
+```json
+{
+  "query": "TypeScript async patterns",
+  "max_results": 5
+}
+```
+
+**Step 2: Read** – Use `visus_read` to extract clean article content:
+```json
+{
+  "url": "https://blog.example.com/typescript-async-guide"
+}
+```
+
+**Step 3: Extract** – Use `visus_fetch_structured` to pull specific data:
+```json
+{
+  "url": "https://docs.typescript.com/reference/async",
+  "schema": {
+    "syntax": "async/await syntax",
+    "example": "code example",
+    "best_practices": "recommended patterns"
+  }
+}
+```
+
+All three steps run content through the sanitization pipeline, ensuring end-to-end security from search to extraction.
+
+---
+
 ## Environment Variables
 
 ```bash
@@ -243,7 +698,7 @@ Visus is part of the **Lateos** platform — a security-by-design AI agent frame
 
 - **AWS Serverless**: Lambda, Step Functions, API Gateway, Cognito
 - **Security**: Bedrock Guardrails, KMS encryption, Secrets Manager
-- **Validated Patterns**: 43 injection patterns, 73/73 passing tests
+- **Validated Patterns**: 43 injection patterns, 122/122 passing tests
 - **CISSP/CEH-Informed**: Designed by security professionals
 
 Learn more: [lateos.ai](https://lateos.ai) (Phase 2)
@@ -252,6 +707,26 @@ Learn more: [lateos.ai](https://lateos.ai) (Phase 2)
 
 ## Development
 
+### Prerequisites
+
+**macOS / Windows:** No additional setup required.
+
+**Linux:** Playwright requires the following system libraries. Install them before running `npm install`:
+
+```bash
+# Ubuntu / Debian
+sudo apt-get install -y \
+  libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 \
+  libxkbcommon0 libxcomposite1 libxdamage1 libxfixes3 \
+  libxrandr2 libgbm1 libnss3 libxss1 libasound2
+
+# Fedora / RHEL
+sudo dnf install -y atk at-spi2-atk libXrandr libgbm \
+  nss alsa-lib libXss cups-libs libdrm libxkbcommon
+```
+
+> If `npm test` fails with a Chromium launch error on Linux, see [TROUBLESHOOT-PLAYWRIGHT.md](./TROUBLESHOOT-PLAYWRIGHT-20260321-1549.md) for detailed troubleshooting steps.
+
 ```bash
 # Clone repo
 git clone https://github.com/visus-mcp/visus-mcp.git