mcp-safe-fetch 0.1.0

package/README.md

@@ -0,0 +1,79 @@
+# mcp-safe-fetch
+
+Deterministic content sanitization MCP server for agentic coding tools. Strips prompt injection vectors from web-fetched content before it enters the LLM context.
+
+Drop-in replacement for Claude Code's built-in `WebFetch` — exposes a `safe_fetch` tool that fetches URLs, sanitizes the HTML, and returns clean markdown.
+
+## What it strips
+
+- **Hidden HTML** — `display:none`, `visibility:hidden`, `opacity:0`, `[hidden]` attribute
+- **Dangerous tags** — `<script>`, `<style>`, `<noscript>`, `<meta>`, `<link>`
+- **HTML comments** — often used to inject instructions invisible to readers
+- **Invisible unicode** — zero-width chars, soft hyphens, BOM, bidi overrides, variation selectors, tag characters
+- **Control characters** — preserves `\n`, `\t`, `\r`, strips everything else
+- **Fake LLM delimiters** — `<|im_start|>`, `[INST]`, `<<SYS>>`, `\n\nHuman:`, etc.
+- **NFKC normalization** — collapses fullwidth and homoglyph characters
+
+## Install
+
+```bash
+npx -y mcp-safe-fetch init
+```
+
+This configures Claude Code to use `safe_fetch` and deny the built-in `WebFetch`. Restart Claude Code after running.
+
+## Usage
+
+### As MCP server (automatic)
+
+After `init`, Claude Code uses `safe_fetch` whenever it needs to read a URL. The sanitization header shows what was stripped:
+
+```
+[safe-fetch] Stripped: 5 hidden elements, 68 script tags, 3 style tags | 284127 → 12720 bytes (219ms)
+```
+
+### CLI
+
+Test sanitization on any URL:
+
+```bash
+npx -y mcp-safe-fetch test <url>
+```
+
+Stats print to stderr, sanitized markdown to stdout.
+
+### MCP tools
+
+| Tool | Description |
+|------|-------------|
+| `safe_fetch` | Fetch a URL and return sanitized markdown |
+| `sanitize_stats` | Show session sanitization statistics |
+
+## Configuration
+
+Optional. Create `.mcp-safe-fetch.json` in your project root or home directory:
+
+```json
+{
+  "logStripped": true,
+  "logFile": ".claude/sanitize.log"
+}
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `logStripped` | `false` | Log sanitization stats to file |
+| `logFile` | `.claude/sanitize.log` | Log file path |
+
+## How it works
+
+1. Fetch URL with native `fetch` (from your machine, not Anthropic's servers)
+2. Parse HTML with [cheerio](https://cheerio.js.org/) (htmlparser2 backend)
+3. Strip hidden elements, dangerous tags, and comments
+4. Convert to markdown with [turndown](https://github.com/mixmark-io/turndown)
+5. Strip invisible unicode characters and normalize with NFKC
+6. Strip fake LLM delimiter tokens
+
+## License
+
+MIT

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export declare function runCli(command: string, args: string[]): void;

package/dist/cli.js

@@ -0,0 +1,88 @@
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { fetchUrl } from './fetch.js';
+import { sanitize } from './sanitize/pipeline.js';
+const CLAUDE_JSON_PATH = join(process.env.HOME || '', '.claude.json');
+const SETTINGS_PATH = join(process.env.HOME || '', '.claude', 'settings.json');
+const MCP_CONFIG = {
+    type: 'stdio',
+    command: 'npx',
+    args: ['-y', 'mcp-safe-fetch'],
+};
+function readJson(path) {
+    if (!existsSync(path)) {
+        return {};
+    }
+    try {
+        return JSON.parse(readFileSync(path, 'utf-8'));
+    }
+    catch {
+        return {};
+    }
+}
+function writeJson(path, data) {
+    writeFileSync(path, JSON.stringify(data, null, 2) + '\n', 'utf-8');
+}
+function runInit(args) {
+    const dryRun = args.includes('--dry-run');
+    if (dryRun) {
+        console.log('Would add to ~/.claude.json:');
+        console.log(JSON.stringify({ mcpServers: { 'safe-fetch': MCP_CONFIG } }, null, 2));
+        console.log('\nWould add to ~/.claude/settings.json:');
+        console.log(JSON.stringify({ allowedTools: { WebFetch: 'deny', 'mcp__safe-fetch__safe_fetch': 'allow' } }, null, 2));
+        return;
+    }
+    // Add MCP server to ~/.claude.json
+    const claudeJson = readJson(CLAUDE_JSON_PATH);
+    if (!claudeJson.mcpServers)
+        claudeJson.mcpServers = {};
+    claudeJson.mcpServers['safe-fetch'] = MCP_CONFIG;
+    writeJson(CLAUDE_JSON_PATH, claudeJson);
+    // Add tool permissions to ~/.claude/settings.json
+    const settings = readJson(SETTINGS_PATH);
+    if (!settings.allowedTools)
+        settings.allowedTools = {};
+    settings.allowedTools['WebFetch'] = 'deny';
+    settings.allowedTools['mcp__safe-fetch__safe_fetch'] = 'allow';
+    writeJson(SETTINGS_PATH, settings);
+    console.log('Updated ~/.claude.json:');
+    console.log('  + mcpServers.safe-fetch (mcp-safe-fetch MCP server)');
+    console.log('\nUpdated ~/.claude/settings.json:');
+    console.log('  + allowedTools.WebFetch: "deny"');
+    console.log('  + allowedTools.mcp__safe-fetch__safe_fetch: "allow"');
+    console.log('\nRestart Claude Code to activate.');
+}
+async function runTest(args) {
+    const url = args[0];
+    if (!url) {
+        console.error('Usage: mcp-safe-fetch test <url>');
+        process.exit(1);
+    }
+    console.error(`Fetching ${url}...`);
+    const startTime = Date.now();
+    const fetched = await fetchUrl(url);
+    const result = sanitize(fetched.html);
+    const durationMs = Date.now() - startTime;
+    // Print stats to stderr
+    console.error(`\nSanitization complete (${durationMs}ms):`);
+    console.error(`  Input:  ${result.inputSize} bytes`);
+    console.error(`  Output: ${result.outputSize} bytes`);
+    console.error(`  Hidden elements: ${result.stats.hiddenElements}`);
+    console.error(`  Script tags: ${result.stats.scriptTags}`);
+    console.error(`  Style tags: ${result.stats.styleTags}`);
+    console.error(`  Zero-width chars: ${result.stats.zeroWidthChars}`);
+    console.error(`  LLM delimiters: ${result.stats.llmDelimiters}`);
+    // Print sanitized content to stdout
+    process.stdout.write(result.content);
+}
+export function runCli(command, args) {
+    if (command === 'init') {
+        runInit(args);
+    }
+    else if (command === 'test') {
+        runTest(args).catch((error) => {
+            console.error(`Error: ${error instanceof Error ? error.message : error}`);
+            process.exit(1);
+        });
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,8 @@
+export interface SanitizeConfig {
+    logStripped: boolean;
+    logFile: string;
+    allowDataUris: boolean;
+    maxBase64DecodeLength: number;
+    customPatterns: string[];
+}
+export declare function loadConfig(): SanitizeConfig;

package/dist/config.js

@@ -0,0 +1,28 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+const DEFAULT_CONFIG = {
+    logStripped: false,
+    logFile: '.claude/sanitize.log',
+    allowDataUris: false,
+    maxBase64DecodeLength: 500,
+    customPatterns: [],
+};
+export function loadConfig() {
+    const paths = [
+        join(process.cwd(), '.mcp-safe-fetch.json'),
+        join(process.env.HOME || '', '.mcp-safe-fetch.json'),
+    ];
+    for (const configPath of paths) {
+        if (existsSync(configPath)) {
+            try {
+                const raw = readFileSync(configPath, 'utf-8');
+                const parsed = JSON.parse(raw);
+                return { ...DEFAULT_CONFIG, ...parsed };
+            }
+            catch {
+                // Invalid config, use defaults
+            }
+        }
+    }
+    return DEFAULT_CONFIG;
+}

package/dist/fetch.d.ts

@@ -0,0 +1,7 @@
+export interface FetchResult {
+    html: string;
+    url: string;
+    status: number;
+    contentType: string;
+}
+export declare function fetchUrl(url: string): Promise<FetchResult>;

package/dist/fetch.js

@@ -0,0 +1,21 @@
+export async function fetchUrl(url) {
+    const response = await fetch(url, {
+        headers: {
+            'User-Agent': 'mcp-safe-fetch/0.1',
+            'Accept': 'text/html,application/xhtml+xml,*/*',
+        },
+        redirect: 'follow',
+        signal: AbortSignal.timeout(10000),
+    });
+    if (!response.ok) {
+        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
+    const html = await response.text();
+    const contentType = response.headers.get('content-type') || '';
+    return {
+        html,
+        url: response.url,
+        status: response.status,
+        contentType,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { startServer } from './server.js';
+import { runCli } from './cli.js';
+const command = process.argv[2];
+if (command === 'init' || command === 'test') {
+    runCli(command, process.argv.slice(3));
+}
+else {
+    // Default: start MCP server (this is what npx safe-fetch invokes)
+    startServer().catch((error) => {
+        console.error('[safe-fetch] Fatal error:', error);
+        process.exit(1);
+    });
+}

package/dist/logger.d.ts

@@ -0,0 +1,11 @@
+import type { PipelineStats } from './sanitize/pipeline.js';
+export interface LogEntry {
+    timestamp: string;
+    url: string;
+    stripped: PipelineStats;
+    inputSize: number;
+    outputSize: number;
+    reductionPercent: number;
+    durationMs: number;
+}
+export declare function logSanitization(logFile: string, entry: LogEntry): void;

package/dist/logger.js

@@ -0,0 +1,11 @@
+import { appendFileSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+export function logSanitization(logFile, entry) {
+    try {
+        mkdirSync(dirname(logFile), { recursive: true });
+        appendFileSync(logFile, JSON.stringify(entry) + '\n', 'utf-8');
+    }
+    catch {
+        console.error(`[safe-fetch] Failed to write log to ${logFile}`);
+    }
+}

package/dist/sanitize/delimiters.d.ts

@@ -0,0 +1,7 @@
+export interface DelimiterSanitizeResult {
+    text: string;
+    stats: {
+        llmDelimiters: number;
+    };
+}
+export declare function sanitizeDelimiters(text: string): DelimiterSanitizeResult;

package/dist/sanitize/delimiters.js

@@ -0,0 +1,30 @@
+const LLM_DELIMITER_PATTERNS = [
+    /<\|im_start\|>/gi,
+    /<\|im_end\|>/gi,
+    /<\|system\|>/gi,
+    /<\|user\|>/gi,
+    /<\|assistant\|>/gi,
+    /<\|endoftext\|>/gi,
+    /<\|pad\|>/gi,
+    /\\?\[INST\\?\]/gi,
+    /\\?\[\\?\/INST\\?\]/gi,
+    /<<SYS>>/gi,
+    /<<\\?\/SYS>>/gi,
+    /\n\nHuman:/g,
+    /\n\nAssistant:/g,
+];
+export function sanitizeDelimiters(text) {
+    let count = 0;
+    let result = text;
+    for (const pattern of LLM_DELIMITER_PATTERNS) {
+        const matches = result.match(pattern);
+        if (matches) {
+            count += matches.length;
+            result = result.replace(pattern, '');
+        }
+    }
+    return {
+        text: result,
+        stats: { llmDelimiters: count },
+    };
+}

package/dist/sanitize/html.d.ts

@@ -0,0 +1,13 @@
+import type { CheerioAPI } from 'cheerio';
+export interface HtmlSanitizeResult {
+    html: string;
+    stats: {
+        hiddenElements: number;
+        htmlComments: number;
+        scriptTags: number;
+        styleTags: number;
+        noscriptTags: number;
+        metaTags: number;
+    };
+}
+export declare function sanitizeHtml($: CheerioAPI): HtmlSanitizeResult;

package/dist/sanitize/html.js

@@ -0,0 +1,48 @@
+const HIDDEN_SELECTORS = [
+    '[style*="display:none"]',
+    '[style*="display: none"]',
+    '[style*="visibility:hidden"]',
+    '[style*="visibility: hidden"]',
+    '[style*="opacity:0"]',
+    '[style*="opacity: 0"]',
+    '[hidden]',
+].join(', ');
+const STRIP_TAGS = ['script', 'style', 'noscript', 'meta', 'link'];
+export function sanitizeHtml($) {
+    const stats = {
+        hiddenElements: 0,
+        htmlComments: 0,
+        scriptTags: 0,
+        styleTags: 0,
+        noscriptTags: 0,
+        metaTags: 0,
+    };
+    // Remove hidden elements by inline style / hidden attribute
+    const hidden = $(HIDDEN_SELECTORS);
+    stats.hiddenElements = hidden.length;
+    hidden.remove();
+    // Remove script, style, noscript, meta, link tags
+    for (const tag of STRIP_TAGS) {
+        const elements = $(tag);
+        const count = elements.length;
+        if (tag === 'script')
+            stats.scriptTags = count;
+        else if (tag === 'style')
+            stats.styleTags = count;
+        else if (tag === 'noscript')
+            stats.noscriptTags = count;
+        else if (tag === 'meta' || tag === 'link')
+            stats.metaTags += count;
+        elements.remove();
+    }
+    // Count and remove HTML comments
+    const comments = $('*').contents().filter(function () {
+        return this.type === 'comment';
+    });
+    stats.htmlComments = comments.length;
+    comments.remove();
+    return {
+        html: $.html(),
+        stats,
+    };
+}

package/dist/sanitize/pipeline.d.ts

@@ -0,0 +1,21 @@
+export interface PipelineStats {
+    hiddenElements: number;
+    htmlComments: number;
+    scriptTags: number;
+    styleTags: number;
+    noscriptTags: number;
+    metaTags: number;
+    zeroWidthChars: number;
+    controlChars: number;
+    bidiOverrides: number;
+    unicodeTags: number;
+    variationSelectors: number;
+    llmDelimiters: number;
+}
+export interface PipelineResult {
+    content: string;
+    stats: PipelineStats;
+    inputSize: number;
+    outputSize: number;
+}
+export declare function sanitize(html: string): PipelineResult;

package/dist/sanitize/pipeline.js

@@ -0,0 +1,39 @@
+import * as cheerio from 'cheerio/slim';
+import TurndownService from 'turndown';
+import { sanitizeHtml } from './html.js';
+import { sanitizeUnicode } from './unicode.js';
+import { sanitizeDelimiters } from './delimiters.js';
+const turndown = new TurndownService({
+    headingStyle: 'atx',
+    codeBlockStyle: 'fenced',
+    fence: '```',
+    hr: '---',
+    bulletListMarker: '-',
+    preformattedCode: true,
+});
+export function sanitize(html) {
+    const inputSize = html.length;
+    // Step 1: Parse HTML with cheerio (htmlparser2 backend via /slim)
+    const $ = cheerio.load(html);
+    // Step 2: Strip hidden HTML elements
+    const htmlResult = sanitizeHtml($);
+    // Step 3: Convert cleaned HTML to markdown
+    let content = turndown.turndown(htmlResult.html);
+    // Step 4: Unicode sanitization
+    const unicodeResult = sanitizeUnicode(content);
+    content = unicodeResult.text;
+    // Step 5: Strip fake LLM delimiters
+    const delimiterResult = sanitizeDelimiters(content);
+    content = delimiterResult.text;
+    const outputSize = content.length;
+    return {
+        content,
+        stats: {
+            ...htmlResult.stats,
+            ...unicodeResult.stats,
+            ...delimiterResult.stats,
+        },
+        inputSize,
+        outputSize,
+    };
+}

package/dist/sanitize/unicode.d.ts

@@ -0,0 +1,11 @@
+export interface UnicodeSanitizeResult {
+    text: string;
+    stats: {
+        zeroWidthChars: number;
+        controlChars: number;
+        bidiOverrides: number;
+        unicodeTags: number;
+        variationSelectors: number;
+    };
+}
+export declare function sanitizeUnicode(text: string): UnicodeSanitizeResult;

package/dist/sanitize/unicode.js

@@ -0,0 +1,35 @@
+// Zero-width and invisible characters
+const INVISIBLE_CHARS = /[\u200B\u200C\u200D\u200E\u200F\u2060\u2063\uFEFF\u00AD]/g;
+// Bidirectional overrides and isolates
+const BIDI_CHARS = /[\u202A-\u202E\u2066-\u2069]/g;
+// Variation selectors
+const VARIATION_SELECTORS = /[\uFE00-\uFE0F]/g;
+// Unicode tag characters (U+E0001-U+E007F)
+const UNICODE_TAGS = /[\u{E0001}-\u{E007F}]/gu;
+// Control characters (except \n \t \r)
+const CONTROL_CHARS = /[\x00-\x08\x0B\x0C\x0E-\x1F]/g;
+export function sanitizeUnicode(text) {
+    const stats = {
+        zeroWidthChars: 0,
+        controlChars: 0,
+        bidiOverrides: 0,
+        unicodeTags: 0,
+        variationSelectors: 0,
+    };
+    // Count before stripping
+    stats.zeroWidthChars = (text.match(INVISIBLE_CHARS) || []).length;
+    stats.bidiOverrides = (text.match(BIDI_CHARS) || []).length;
+    stats.variationSelectors = (text.match(VARIATION_SELECTORS) || []).length;
+    stats.unicodeTags = (text.match(UNICODE_TAGS) || []).length;
+    stats.controlChars = (text.match(CONTROL_CHARS) || []).length;
+    // Strip all
+    let result = text
+        .replace(INVISIBLE_CHARS, '')
+        .replace(BIDI_CHARS, '')
+        .replace(VARIATION_SELECTORS, '')
+        .replace(UNICODE_TAGS, '')
+        .replace(CONTROL_CHARS, '');
+    // NFKC normalization (collapses homoglyphs)
+    result = result.normalize('NFKC');
+    return { text: result, stats };
+}

package/dist/server.d.ts

@@ -0,0 +1 @@
+export declare function startServer(): Promise<void>;

package/dist/server.js

@@ -0,0 +1,104 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { fetchUrl } from './fetch.js';
+import { sanitize } from './sanitize/pipeline.js';
+import { loadConfig } from './config.js';
+import { logSanitization } from './logger.js';
+export async function startServer() {
+    const config = loadConfig();
+    const session = {
+        totalRequests: 0,
+        totalStripped: {
+            hiddenElements: 0, htmlComments: 0, scriptTags: 0,
+            styleTags: 0, noscriptTags: 0, metaTags: 0,
+            zeroWidthChars: 0, controlChars: 0, bidiOverrides: 0,
+            unicodeTags: 0, variationSelectors: 0, llmDelimiters: 0,
+        },
+        urls: [],
+    };
+    const server = new McpServer({
+        name: 'safe-fetch',
+        version: '0.1.0',
+    });
+    server.registerTool('safe_fetch', {
+        description: 'Fetch a URL and return sanitized content with prompt injection vectors removed. Strips hidden HTML elements, invisible unicode characters, and fake LLM delimiters.',
+        inputSchema: {
+            url: z.string().url().describe('URL to fetch'),
+        },
+    }, async ({ url }) => {
+        try {
+            const startTime = Date.now();
+            const fetched = await fetchUrl(url);
+            const result = sanitize(fetched.html);
+            const durationMs = Date.now() - startTime;
+            // Update session stats
+            session.totalRequests++;
+            session.urls.push(url);
+            for (const key of Object.keys(session.totalStripped)) {
+                session.totalStripped[key] += result.stats[key];
+            }
+            // Log if configured
+            if (config.logStripped) {
+                const entry = {
+                    timestamp: new Date().toISOString(),
+                    url,
+                    stripped: result.stats,
+                    inputSize: result.inputSize,
+                    outputSize: result.outputSize,
+                    reductionPercent: Math.round((1 - result.outputSize / result.inputSize) * 1000) / 10,
+                    durationMs,
+                };
+                logSanitization(config.logFile, entry);
+            }
+            // Build summary of what was stripped
+            const strippedItems = [];
+            if (result.stats.hiddenElements > 0)
+                strippedItems.push(`${result.stats.hiddenElements} hidden elements`);
+            if (result.stats.scriptTags > 0)
+                strippedItems.push(`${result.stats.scriptTags} script tags`);
+            if (result.stats.styleTags > 0)
+                strippedItems.push(`${result.stats.styleTags} style tags`);
+            if (result.stats.zeroWidthChars > 0)
+                strippedItems.push(`${result.stats.zeroWidthChars} zero-width chars`);
+            if (result.stats.llmDelimiters > 0)
+                strippedItems.push(`${result.stats.llmDelimiters} LLM delimiters`);
+            const header = strippedItems.length > 0
+                ? `[safe-fetch] Stripped: ${strippedItems.join(', ')} | ${result.inputSize} → ${result.outputSize} bytes (${durationMs}ms)\n\n`
+                : `[safe-fetch] Clean page | ${result.inputSize} → ${result.outputSize} bytes (${durationMs}ms)\n\n`;
+            return {
+                content: [{ type: 'text', text: header + result.content }],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                content: [{ type: 'text', text: `[safe-fetch] Error fetching ${url}: ${message}` }],
+                isError: true,
+            };
+        }
+    });
+    server.registerTool('sanitize_stats', {
+        description: 'Show sanitization statistics for the current session',
+        inputSchema: {},
+    }, async () => {
+        const lines = [
+            `Session stats (${session.totalRequests} requests):`,
+            `  Hidden elements stripped: ${session.totalStripped.hiddenElements}`,
+            `  Script tags stripped: ${session.totalStripped.scriptTags}`,
+            `  Style tags stripped: ${session.totalStripped.styleTags}`,
+            `  Zero-width chars stripped: ${session.totalStripped.zeroWidthChars}`,
+            `  LLM delimiters stripped: ${session.totalStripped.llmDelimiters}`,
+            `  Bidi overrides stripped: ${session.totalStripped.bidiOverrides}`,
+            '',
+            `URLs fetched:`,
+            ...session.urls.map(u => `  - ${u}`),
+        ];
+        return {
+            content: [{ type: 'text', text: lines.join('\n') }],
+        };
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('[safe-fetch] MCP server running on stdio');
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "mcp-safe-fetch",
+  "version": "0.1.0",
+  "description": "Deterministic content sanitization MCP server for agentic coding tools",
+  "type": "module",
+  "main": "./dist/index.js",
+  "bin": {
+    "mcp-safe-fetch": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "sanitize",
+    "prompt-injection",
+    "claude",
+    "llm",
+    "security"
+  ],
+  "author": "Tim Stark <tim@timstark.dev>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/timstarkk/mcp-safe-fetch"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.0",
+    "cheerio": "^1.2.0",
+    "turndown": "^7.2.2",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/turndown": "^5.0.5",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}