@j0hanz/superfetch 2.4.0 → 2.4.2

package/dist/cache.d.ts

@@ -36,7 +36,7 @@ export declare function get(cacheKey: string | null): CacheEntry | undefined;
 export declare function set(cacheKey: string | null, content: string, metadata: CacheEntryMetadata): void;
 export declare function keys(): readonly string[];
 export declare function isEnabled(): boolean;
-export declare function registerCachedContentResource(server: McpServer): void;
+export declare function registerCachedContentResource(server: McpServer, serverIcon?: string): void;
 export declare function generateSafeFilename(url: string, title?: string, hashFallback?: string, extension?: string): string;
 export declare function handleDownload(res: ServerResponse, namespace: string, hash: string): void;
 export {};

package/dist/cache.js

@@ -112,6 +112,7 @@ class NativeLruCache {
     max;
     ttlMs;
     entries = new Map();
+    nextPurgeAtMs = 0;
     constructor({ max, ttlMs }) {
         this.max = max;
         this.ttlMs = ttlMs;
@@ -132,12 +133,13 @@ class NativeLruCache {
     set(key, value) {
         if (this.max <= 0 || this.ttlMs <= 0)
             return;
+        const now = Date.now();
         this.entries.delete(key);
         this.entries.set(key, {
             value,
-            expiresAtMs: Date.now() + this.ttlMs,
+            expiresAtMs: now + this.ttlMs,
         });
-        this.purgeExpired(Date.now());
+        this.maybePurge(now);
         while (this.entries.size > this.max) {
             const oldestKey = this.entries.keys().next().value;
             if (oldestKey === undefined)
@@ -146,9 +148,15 @@ class NativeLruCache {
         }
     }
     keys() {
-        this.purgeExpired(Date.now());
+        this.maybePurge(Date.now());
         return [...this.entries.keys()];
     }
+    maybePurge(now) {
+        if (this.entries.size > this.max || now >= this.nextPurgeAtMs) {
+            this.purgeExpired(now);
+            this.nextPurgeAtMs = now + this.ttlMs;
+        }
+    }
     purgeExpired(now) {
         for (const [key, entry] of this.entries) {
             if (this.isExpired(entry, now)) {
@@ -387,23 +395,34 @@ function notifyResourceUpdate(server, uri, subscriptions) {
         });
     });
 }
-export function registerCachedContentResource(server) {
+export function registerCachedContentResource(server, serverIcon) {
     const isInitialized = attachInitializedGate(server);
     const subscriptions = registerResourceSubscriptionHandlers(server);
-    registerCacheContentResource(server);
+    registerCacheContentResource(server, serverIcon);
     registerCacheUpdateSubscription(server, subscriptions, isInitialized);
 }
 function buildCachedContentResponse(uri, cacheKey) {
     const cached = requireCacheEntry(cacheKey);
     return buildMarkdownContentResponse(uri, cached.content);
 }
-function registerCacheContentResource(server) {
+function registerCacheContentResource(server, serverIcon) {
     server.registerResource('cached-content', new ResourceTemplate('superfetch://cache/{namespace}/{urlHash}', {
         list: listCachedResources,
     }), {
         title: 'Cached Content',
         description: 'Access previously fetched web content from cache. Namespace: markdown. UrlHash: SHA-256 hash of the URL.',
         mimeType: 'text/markdown',
+        ...(serverIcon
+            ? {
+                icons: [
+                    {
+                        src: serverIcon,
+                        mimeType: 'image/svg+xml',
+                        sizes: ['any'],
+                    },
+                ],
+            }
+            : {}),
     }, (uri, params) => {
         const { namespace, urlHash } = resolveCacheParams(params);
         const cacheKey = `${namespace}:${urlHash}`;

package/dist/dom-noise-removal.d.ts

@@ -1,5 +1 @@
-/**
- * Remove noise elements from HTML and resolve relative URLs.
- * Used as a preprocessing step before markdown conversion.
- */
 export declare function removeNoiseFromHtml(html: string, document?: Document, baseUrl?: string): string;

package/dist/dom-noise-removal.js

@@ -331,7 +331,6 @@ function removeNoiseNodes(nodes, shouldCheckNoise = true) {
         removeNoiseFromNodeListLike(nodes, shouldCheckNoise);
         return;
     }
-    // Generic iterable: copy to avoid iteration issues while removing.
     const nodeList = Array.from(nodes);
     for (const node of nodeList) {
         if (isElement(node) && (!shouldCheckNoise || isNoiseElement(node))) {
@@ -340,21 +339,15 @@ function removeNoiseNodes(nodes, shouldCheckNoise = true) {
     }
 }
 function stripNoiseNodes(document) {
-    // Pass 1: Trusted selectors (Common noise)
-    // We trust these selectors match actual noise, so we skip the expensive isNoiseElement check
-    // Add user-configured extra selectors
     const targetSelectors = buildNoiseSelector(config.noiseRemoval.extraSelectors);
     const potentialNoiseNodes = document.querySelectorAll(targetSelectors);
     removeNoiseNodes(potentialNoiseNodes, false);
-    // Second pass: check remaining elements for noise patterns (promo, fixed positioning, etc.)
     const allElements = document.querySelectorAll(CANDIDATE_NOISE_SELECTOR);
     removeNoiseNodes(allElements, true);
 }
 // ─────────────────────────────────────────────────────────────────────────────
 // URL Resolution
 // ─────────────────────────────────────────────────────────────────────────────
-// Protocol patterns to skip during URL resolution (fragment, mailto, tel, blob, data, javascript)
-// JavaScript protocol is detected to skip it for XSS prevention, not to evaluate it
 const SKIP_URL_PREFIXES = [
     '#',
     'java' + 'script:',
@@ -363,11 +356,6 @@ const SKIP_URL_PREFIXES = [
     'data:',
     'blob:',
 ];
-/**
- * Check if a URL scheme should be skipped during resolution.
- * These schemes are either fragment-only (#), protocol handlers (mailto, tel),
- * inline data (data, blob), or javascript: which we skip to avoid XSS.
- */
 function shouldSkipUrlResolution(url) {
     const normalized = url.trim().toLowerCase();
     return SKIP_URL_PREFIXES.some((prefix) => normalized.startsWith(prefix));
@@ -383,79 +371,61 @@ function tryResolveUrl(relativeUrl, baseUrl) {
         return null;
     }
 }
-/**
- * Resolve anchor hrefs to absolute URLs.
- */
-function resolveAnchorUrls(document, baseUrl) {
-    for (const anchor of document.querySelectorAll('a[href]')) {
-        const href = anchor.getAttribute('href');
-        if (href && !shouldSkipUrlResolution(href)) {
-            const resolved = tryResolveUrl(href, baseUrl);
-            if (resolved)
-                anchor.setAttribute('href', resolved);
-        }
+function resolveAnchorElement(element, base) {
+    const href = element.getAttribute('href');
+    if (href && !shouldSkipUrlResolution(href)) {
+        const resolved = tryResolveUrl(href, base);
+        if (resolved)
+            element.setAttribute('href', resolved);
     }
 }
-/**
- * Resolve image srcs to absolute URLs.
- */
-function resolveImageUrls(document, baseUrl) {
-    for (const img of document.querySelectorAll('img[src]')) {
-        const src = img.getAttribute('src');
-        if (src && !shouldSkipUrlResolution(src)) {
-            const resolved = tryResolveUrl(src, baseUrl);
-            if (resolved)
-                img.setAttribute('src', resolved);
-        }
+function resolveImageElement(element, base) {
+    const src = element.getAttribute('src');
+    if (src && !shouldSkipUrlResolution(src)) {
+        const resolved = tryResolveUrl(src, base);
+        if (resolved)
+            element.setAttribute('src', resolved);
     }
 }
-/**
- * Resolve source srcset to absolute URLs (for picture elements).
- */
-function resolveSrcsetUrls(document, baseUrl) {
-    for (const source of document.querySelectorAll('source[srcset]')) {
-        const srcset = source.getAttribute('srcset');
-        if (!srcset)
-            continue;
-        // srcset can have multiple URLs with descriptors like "url 1x, url 2x"
-        const resolved = srcset
-            .split(',')
-            .map((entry) => {
-            const parts = entry.trim().split(/\s+/);
-            const url = parts[0];
-            if (url) {
-                const resolvedUrl = tryResolveUrl(url, baseUrl);
-                if (resolvedUrl)
-                    parts[0] = resolvedUrl;
-            }
-            return parts.join(' ');
-        })
-            .join(', ');
-        source.setAttribute('srcset', resolved);
-    }
+function resolveSourceElement(element, base) {
+    const srcset = element.getAttribute('srcset');
+    if (!srcset)
+        return;
+    const resolved = srcset
+        .split(',')
+        .map((entry) => {
+        const parts = entry.trim().split(/\s+/);
+        const url = parts[0];
+        if (url) {
+            const resolvedUrl = tryResolveUrl(url, base);
+            if (resolvedUrl)
+                parts[0] = resolvedUrl;
+        }
+        return parts.join(' ');
+    })
+        .join(', ');
+    element.setAttribute('srcset', resolved);
 }
-/**
- * Resolve relative URLs in anchor and image elements to absolute URLs.
- * Fixes broken links/images in markdown output when the source uses relative paths.
- */
 function resolveRelativeUrls(document, baseUrl) {
     try {
         const base = new URL(baseUrl);
-        resolveAnchorUrls(document, base);
-        resolveImageUrls(document, base);
-        resolveSrcsetUrls(document, base);
+        for (const element of document.querySelectorAll('a[href], img[src], source[srcset]')) {
+            const tag = element.tagName.toLowerCase();
+            if (tag === 'a') {
+                resolveAnchorElement(element, base);
+            }
+            else if (tag === 'img') {
+                resolveImageElement(element, base);
+            }
+            else if (tag === 'source') {
+                resolveSourceElement(element, base);
+            }
+        }
     }
     catch {
         /* invalid base URL - skip resolution */
     }
 }
-// ─────────────────────────────────────────────────────────────────────────────
-// Main Export
-// ─────────────────────────────────────────────────────────────────────────────
-/**
- * Remove noise elements from HTML and resolve relative URLs.
- * Used as a preprocessing step before markdown conversion.
- */
 export function removeNoiseFromHtml(html, document, baseUrl) {
     const shouldParse = isFullDocumentHtml(html) || mayContainNoise(html);
     if (!shouldParse)

package/dist/language-detection.js

@@ -98,8 +98,8 @@ function matchesPackageManagerVerb(line) {
     }
     return false;
 }
-function detectBashIndicators(code) {
-    for (const line of code.split('\n')) {
+function detectBashIndicators(lines) {
+    for (const line of lines) {
         const trimmed = line.trimStart();
         if (trimmed &&
             (isShellPrefix(trimmed) ||
@@ -110,8 +110,8 @@ function detectBashIndicators(code) {
     }
     return false;
 }
-function detectCssStructure(code) {
-    for (const line of code.split('\n')) {
+function detectCssStructure(lines) {
+    for (const line of lines) {
         const trimmed = line.trimStart();
         if (!trimmed)
             continue;
@@ -123,8 +123,8 @@ function detectCssStructure(code) {
     }
     return false;
 }
-function detectYamlStructure(code) {
-    for (const line of code.split('\n')) {
+function detectYamlStructure(lines) {
+    for (const line of lines) {
         const trimmed = line.trim();
         if (!trimmed)
             continue;
@@ -194,14 +194,14 @@ const LANGUAGE_PATTERNS = [
     {
         language: 'bash',
         pattern: {
-            custom: (code) => detectBashIndicators(code),
+            custom: (_code, _lower, lines) => detectBashIndicators(lines),
         },
     },
     {
         language: 'css',
         pattern: {
             regex: /@media|@import|@keyframes/,
-            custom: (code) => detectCssStructure(code),
+            custom: (_code, _lower, lines) => detectCssStructure(lines),
         },
     },
     {
@@ -230,7 +230,7 @@ const LANGUAGE_PATTERNS = [
     {
         language: 'yaml',
         pattern: {
-            custom: (code) => detectYamlStructure(code),
+            custom: (_code, _lower, lines) => detectYamlStructure(lines),
         },
     },
     {
@@ -255,7 +255,7 @@ const LANGUAGE_PATTERNS = [
         },
     },
 ];
-function matchesLanguagePattern(code, lower, pattern) {
+function matchesLanguagePattern(code, lower, lines, pattern) {
     if (pattern.keywords?.some((kw) => lower.includes(kw)))
         return true;
     if (pattern.wordBoundary?.some((w) => containsWord(lower, w)))
@@ -267,7 +267,7 @@ function matchesLanguagePattern(code, lower, pattern) {
         if (pattern.startsWith.some((prefix) => trimmed.startsWith(prefix)))
             return true;
     }
-    if (pattern.custom?.(code, lower))
+    if (pattern.custom?.(code, lower, lines))
         return true;
     return false;
 }
@@ -276,8 +276,9 @@ function matchesLanguagePattern(code, lower, pattern) {
  */
 export function detectLanguageFromCode(code) {
     const lower = code.toLowerCase();
+    const lines = code.split('\n');
     for (const { language, pattern } of LANGUAGE_PATTERNS) {
-        if (matchesLanguagePattern(code, lower, pattern))
+        if (matchesLanguagePattern(code, lower, lines, pattern))
             return language;
     }
     return undefined;

package/dist/markdown-cleanup.js

@@ -149,6 +149,21 @@ function normalizeListsAndSpacing(text) {
     // Collapse excessive blank lines
     return text.replace(/\n{3,}/g, '\n\n');
 }
+function fixConcatenatedProperties(text) {
+    const quotedValuePattern = /([a-z_][a-z0-9_]{0,30}\??:\s+)([\u0022\u201C][^\u0022\u201C\u201D]*[\u0022\u201D])([a-z_][a-z0-9_]{0,30}\??:)/g;
+    let result = text;
+    let iterations = 0;
+    const maxIterations = 3;
+    while (iterations < maxIterations) {
+        const before = result;
+        result = result.replace(quotedValuePattern, '$1$2\n\n$3');
+        if (result === before) {
+            break;
+        }
+        iterations++;
+    }
+    return result;
+}
 const CLEANUP_STEPS = [
     fixOrphanHeadings,
     removeEmptyHeadings,
@@ -157,6 +172,7 @@ const CLEANUP_STEPS = [
     removeTocBlocks,
     tidyLinksAndEscapes,
     normalizeListsAndSpacing,
+    fixConcatenatedProperties,
 ];
 // ─────────────────────────────────────────────────────────────────────────────
 // Public API

package/dist/mcp.js

@@ -22,7 +22,13 @@ function createServerInfo() {
     return {
         name: config.server.name,
         version: config.server.version,
-        ...(localIcon ? { icons: [{ src: localIcon, sizes: ['any'] }] } : {}),
+        ...(localIcon
+            ? {
+                icons: [
+                    { src: localIcon, mimeType: 'image/svg+xml', sizes: ['any'] },
+                ],
+            }
+            : {}),
     };
 }
 function createServerCapabilities() {
@@ -63,8 +69,9 @@ export function createMcpServer() {
         instructions,
     });
     setMcpServer(server);
-    registerTools(server);
-    registerCachedContentResource(server);
+    const localIcon = getLocalIconData();
+    registerTools(server, localIcon);
+    registerCachedContentResource(server, localIcon);
     registerInstructionsResource(server, instructions);
     return server;
 }

package/dist/tools.d.ts

@@ -1,4 +1,5 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { CallToolResult, ContentBlock } from '@modelcontextprotocol/sdk/types.js';
 import type { MarkdownTransformResult } from './transform-types.js';
 export interface FetchUrlInput {
     url: string;
@@ -23,20 +24,15 @@ export interface ToolContentResourceBlock {
         text: string;
     };
 }
-export type ToolContentBlockUnion = ToolContentBlock | ToolContentResourceLinkBlock | ToolContentResourceBlock;
-export interface ToolErrorResponse {
-    content: ToolContentBlockUnion[];
+export type ToolContentBlockUnion = ContentBlock;
+export type ToolErrorResponse = CallToolResult & {
     structuredContent: {
         error: string;
         url: string;
     };
     isError: true;
-}
-export interface ToolResponseBase {
-    content: ToolContentBlockUnion[];
-    structuredContent?: Record<string, unknown>;
-    isError?: boolean;
-}
+};
+export type ToolResponseBase = CallToolResult;
 export interface FetchPipelineOptions<T> {
     /** URL to fetch */
     url: string;
@@ -125,5 +121,5 @@ type MarkdownPipelineResult = MarkdownTransformResult & {
 export declare function parseCachedMarkdownResult(cached: string): MarkdownPipelineResult | undefined;
 export declare function fetchUrlToolHandler(input: FetchUrlInput, extra?: ToolHandlerExtra): Promise<ToolResponseBase>;
 export declare function withRequestContextIfMissing<TParams, TResult, TExtra = unknown>(handler: (params: TParams, extra?: TExtra) => Promise<TResult>): (params: TParams, extra?: TExtra) => Promise<TResult>;
-export declare function registerTools(server: McpServer): void;
+export declare function registerTools(server: McpServer, serverIcon?: string): void;
 export {};

package/dist/tools.js

@@ -482,12 +482,23 @@ function resolveRequestIdFromExtra(extra) {
         return String(requestId);
     return undefined;
 }
-export function registerTools(server) {
+export function registerTools(server, serverIcon) {
     server.registerTool(TOOL_DEFINITION.name, {
         title: TOOL_DEFINITION.title,
         description: TOOL_DEFINITION.description,
         inputSchema: TOOL_DEFINITION.inputSchema,
         outputSchema: TOOL_DEFINITION.outputSchema,
         annotations: TOOL_DEFINITION.annotations,
+        ...(serverIcon
+            ? {
+                icons: [
+                    {
+                        src: serverIcon,
+                        mimeType: 'image/svg+xml',
+                        sizes: ['any'],
+                    },
+                ],
+            }
+            : {}),
     }, withRequestContextIfMissing(TOOL_DEFINITION.handler));
 }

package/dist/transform.js

@@ -519,6 +519,36 @@ function createCustomTranslators() {
                 .join('\n');
             return { content: items ? `\n${items}\n\n` : '' };
         },
+        div: (ctx) => {
+            if (!isObject(ctx) || !isObject(ctx.node)) {
+                return {};
+            }
+            const node = ctx.node;
+            const className = typeof node.attribs?.class === 'string' ? node.attribs.class : '';
+            if (!className.includes('type')) {
+                return {};
+            }
+            return {
+                postprocess: ({ content }) => {
+                    const lines = content.split('\n');
+                    const separated = [];
+                    for (let i = 0; i < lines.length; i++) {
+                        const line = lines[i] ?? '';
+                        const nextLine = i < lines.length - 1 ? (lines[i + 1] ?? '') : '';
+                        separated.push(line);
+                        if (line.trim() &&
+                            nextLine.trim() &&
+                            line.includes(':') &&
+                            nextLine.includes(':') &&
+                            !line.startsWith(' ') &&
+                            !nextLine.startsWith(' ')) {
+                            separated.push('');
+                        }
+                    }
+                    return separated.join('\n');
+                },
+            };
+        },
         kbd: () => ({
             postprocess: ({ content }) => `\`${content}\``,
         }),
@@ -531,7 +561,8 @@ function createCustomTranslators() {
         sup: () => ({
             postprocess: ({ content }) => `^${content}^`,
         }),
-        // Fix #6: Handle <pre> without <code> - wrap in fenced code block
+        // Note: section translator removed in favor of HTML preprocessing
+        // See preprocessPropertySections() for the fix to TypeDoc section spacing
         pre: (ctx) => buildPreTranslator(ctx),
     };
 }
@@ -548,13 +579,18 @@ function getMarkdownConverter() {
     markdownInstance ??= createMarkdownInstance();
     return markdownInstance;
 }
+function preprocessPropertySections(html) {
+    const result = html.replace(/<\/section>\s*(<section[^>]*class="[^"]*tsd-panel[^"]*tsd-member[^"]*"[^>]*>)/g, '</section><p>&nbsp;</p>$1');
+    return result;
+}
 function translateHtmlToMarkdown(html, url, signal, document, skipNoiseRemoval) {
     throwIfAborted(signal, url, 'markdown:begin');
     const cleanedHtml = skipNoiseRemoval
         ? html
         : runTransformStage(url, 'markdown:noise', () => removeNoiseFromHtml(html, document, url));
     throwIfAborted(signal, url, 'markdown:cleaned');
-    const content = runTransformStage(url, 'markdown:translate', () => getMarkdownConverter().translate(cleanedHtml).trim());
+    const preprocessedHtml = runTransformStage(url, 'markdown:preprocess', () => preprocessPropertySections(cleanedHtml));
+    const content = runTransformStage(url, 'markdown:translate', () => getMarkdownConverter().translate(preprocessedHtml).trim());
     throwIfAborted(signal, url, 'markdown:translated');
     return cleanupMarkdownArtifacts(content);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@j0hanz/superfetch",
-  "version": "2.4.0",
+  "version": "2.4.2",
   "mcpName": "io.github.j0hanz/superfetch",
   "description": "Intelligent web content fetcher MCP server that converts HTML to clean, AI-readable Markdown",
   "type": "module",