@j0hanz/superfetch 1.2.5 → 2.0.1

package/dist/middleware/error-handler.js

@@ -1,57 +1,56 @@
 import { FetchError } from '../errors/app-error.js';
 import { logError } from '../services/logger.js';
-function getStatusCode(err) {
-    return err instanceof FetchError ? err.statusCode : 500;
+function getStatusCode(fetchError) {
+    return fetchError ? fetchError.statusCode : 500;
 }
-function getErrorCode(err) {
-    return err instanceof FetchError ? err.code : 'INTERNAL_ERROR';
+function getErrorCode(fetchError) {
+    return fetchError ? fetchError.code : 'INTERNAL_ERROR';
 }
-function getErrorMessage(err) {
-    return err instanceof FetchError ? err.message : 'Internal Server Error';
+function getErrorMessage(fetchError) {
+    return fetchError ? fetchError.message : 'Internal Server Error';
 }
-function getErrorDetails(err) {
-    if (err instanceof FetchError && Object.keys(err.details).length > 0) {
-        return err.details;
+function getErrorDetails(fetchError) {
+    if (fetchError && Object.keys(fetchError.details).length > 0) {
+        return fetchError.details;
     }
     return undefined;
 }
-function setRetryAfterHeader(res, err) {
-    const retryAfter = resolveRetryAfter(err);
-    if (!retryAfter)
+function setRetryAfterHeader(res, fetchError) {
+    const retryAfter = resolveRetryAfter(fetchError);
+    if (retryAfter === undefined)
         return;
     res.set('Retry-After', retryAfter);
 }
-function buildErrorResponse(err) {
-    const details = getErrorDetails(err);
+function buildErrorResponse(fetchError) {
+    const details = getErrorDetails(fetchError);
     const response = {
         error: {
-            message: getErrorMessage(err),
-            code: getErrorCode(err),
-            statusCode: getStatusCode(err),
+            message: getErrorMessage(fetchError),
+            code: getErrorCode(fetchError),
+            statusCode: getStatusCode(fetchError),
             ...(details && { details }),
         },
     };
-    if (process.env.NODE_ENV === 'development' && err.stack) {
-        response.error.stack = err.stack;
-    }
+    // Never expose stack traces in production
     return response;
 }
-function resolveRetryAfter(err) {
-    if (!(err instanceof FetchError))
-        return null;
-    if (err.statusCode !== 429)
-        return null;
-    const { retryAfter } = err.details;
-    if (!isRetryAfterValue(retryAfter))
-        return null;
-    return String(retryAfter);
+function resolveRetryAfter(fetchError) {
+    if (fetchError?.statusCode !== 429)
+        return undefined;
+    const { retryAfter } = fetchError.details;
+    return isRetryAfterValue(retryAfter) ? String(retryAfter) : undefined;
 }
 function isRetryAfterValue(value) {
     return typeof value === 'number' || typeof value === 'string';
 }
-export function errorHandler(err, req, res, _next) {
-    const statusCode = getStatusCode(err);
+export function errorHandler(err, req, res, next) {
+    if (res.headersSent) {
+        next(err);
+        return;
+    }
+    const fetchError = err instanceof FetchError ? err : null;
+    const statusCode = getStatusCode(fetchError);
     logError(`HTTP ${statusCode}: ${err.message} - ${req.method} ${req.path}`, err);
-    setRetryAfterHeader(res, err);
-    res.status(statusCode).json(buildErrorResponse(err));
+    setRetryAfterHeader(res, fetchError);
+    res.status(statusCode).json(buildErrorResponse(fetchError));
 }

package/dist/resources/cached-content-params.d.ts

@@ -0,0 +1,5 @@
+export declare const CACHE_NAMESPACE = "markdown";
+export declare function resolveCacheParams(params: unknown): {
+    namespace: string;
+    urlHash: string;
+};

package/dist/resources/cached-content-params.js

@@ -0,0 +1,36 @@
+import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
+import { isRecord } from '../utils/guards.js';
+export const CACHE_NAMESPACE = 'markdown';
+const HASH_PATTERN = /^[a-f0-9.]+$/i;
+export function resolveCacheParams(params) {
+    const parsed = requireRecordParams(params);
+    const namespace = requireParamString(parsed, 'namespace');
+    const urlHash = requireParamString(parsed, 'urlHash');
+    if (!isValidNamespace(namespace) || !isValidHash(urlHash)) {
+        throw new McpError(ErrorCode.InvalidParams, 'Invalid cache resource parameters');
+    }
+    return { namespace, urlHash };
+}
+function requireRecordParams(value) {
+    if (!isRecord(value)) {
+        throw new McpError(ErrorCode.InvalidParams, 'Invalid cache resource parameters');
+    }
+    return value;
+}
+function requireParamString(params, key) {
+    const raw = params[key];
+    const resolved = resolveStringParam(raw);
+    if (!resolved) {
+        throw new McpError(ErrorCode.InvalidParams, 'Both namespace and urlHash parameters are required');
+    }
+    return resolved;
+}
+function isValidNamespace(namespace) {
+    return namespace === CACHE_NAMESPACE;
+}
+function isValidHash(hash) {
+    return HASH_PATTERN.test(hash) && hash.length >= 8 && hash.length <= 64;
+}
+function resolveStringParam(value) {
+    return typeof value === 'string' ? value : null;
+}

package/dist/resources/cached-content.js

@@ -1,45 +1,65 @@
 import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
 import * as cache from '../services/cache.js';
+import { parseCacheKey, toResourceUri } from '../services/cache-keys.js';
 import { logWarn } from '../services/logger.js';
-import { getErrorMessage } from '../utils/error-utils.js';
-const VALID_NAMESPACES = new Set(['url', 'markdown', 'links']);
+import { parseCachedPayload, resolveCachedPayloadContent, } from '../utils/cached-payload.js';
+import { getErrorMessage } from '../utils/error-details.js';
+import { isRecord } from '../utils/guards.js';
+const CACHE_NAMESPACE = 'markdown';
 const HASH_PATTERN = /^[a-f0-9.]+$/i;
+function resolveCacheParams(params) {
+    const parsed = requireRecordParams(params);
+    const namespace = requireParamString(parsed, 'namespace');
+    const urlHash = requireParamString(parsed, 'urlHash');
+    if (!isValidNamespace(namespace) || !isValidHash(urlHash)) {
+        throw new McpError(ErrorCode.InvalidParams, 'Invalid cache resource parameters');
+    }
+    return { namespace, urlHash };
+}
+function requireRecordParams(value) {
+    if (!isRecord(value)) {
+        throw new McpError(ErrorCode.InvalidParams, 'Invalid cache resource parameters');
+    }
+    return value;
+}
+function requireParamString(params, key) {
+    const raw = params[key];
+    const resolved = resolveStringParam(raw);
+    if (!resolved) {
+        throw new McpError(ErrorCode.InvalidParams, 'Both namespace and urlHash parameters are required');
+    }
+    return resolved;
+}
+function isValidNamespace(namespace) {
+    return namespace === CACHE_NAMESPACE;
+}
+function isValidHash(hash) {
+    return HASH_PATTERN.test(hash) && hash.length >= 8 && hash.length <= 64;
+}
+function resolveStringParam(value) {
+    return typeof value === 'string' ? value : null;
+}
 function buildResourceEntry(namespace, urlHash) {
     return {
         name: `${namespace}:${urlHash}`,
         uri: `superfetch://cache/${namespace}/${urlHash}`,
         description: `Cached content entry for ${namespace}`,
-        mimeType: resolveCacheMimeType(namespace),
+        mimeType: 'text/markdown',
     };
 }
 function listCachedResources() {
     const resources = cache
         .keys()
         .map((key) => {
-        const parts = cache.parseCacheKey(key);
-        return parts ? buildResourceEntry(parts.namespace, parts.urlHash) : null;
+        const parts = parseCacheKey(key);
+        if (parts?.namespace !== CACHE_NAMESPACE)
+            return null;
+        return buildResourceEntry(parts.namespace, parts.urlHash);
     })
         .filter((entry) => entry !== null);
     return { resources };
 }
-function buildCacheListPayload() {
-    const cacheKeys = cache.keys();
-    return {
-        totalEntries: cacheKeys.length,
-        entries: cacheKeys.map((key) => {
-            const parts = cache.parseCacheKey(key);
-            const namespace = parts?.namespace ?? 'unknown';
-            const urlHash = parts?.urlHash ?? 'unknown';
-            return {
-                namespace,
-                urlHash,
-                resourceUri: `superfetch://cache/${namespace}/${urlHash}`,
-            };
-        }),
-        timestamp: new Date().toISOString(),
-    };
-}
 function notifyResourceUpdate(server, uri) {
     if (!server.isConnected())
         return;
@@ -52,88 +72,31 @@ function notifyResourceUpdate(server, uri) {
 }
 export function registerCachedContentResource(server) {
     registerCacheContentResource(server);
-    registerCacheListResource(server);
     registerCacheUpdateSubscription(server);
 }
-function resolveCacheParams(params) {
-    const namespace = resolveStringParam(params.namespace);
-    const urlHash = resolveStringParam(params.urlHash);
-    if (!namespace || !urlHash) {
-        throw new McpError(ErrorCode.InvalidParams, 'Both namespace and urlHash parameters are required');
-    }
-    if (!isValidNamespace(namespace) || !isValidHash(urlHash)) {
-        throw new McpError(ErrorCode.InvalidParams, 'Invalid cache resource parameters');
-    }
-    return { namespace, urlHash };
-}
-function buildCachedContentResponse(uri, cacheKey, namespace) {
-    const cached = cache.get(cacheKey);
-    if (!cached) {
-        throw new McpError(ErrorCode.InvalidParams, `Content not found in cache for key: ${cacheKey}. Use superfetch://stats to see available cache entries.`);
-    }
-    if (namespace !== 'url' && namespace !== 'markdown') {
-        return {
-            contents: [
-                {
-                    uri: uri.href,
-                    mimeType: resolveCacheMimeType(namespace),
-                    text: cached.content,
-                },
-            ],
-        };
-    }
-    const payload = parseCachedPayload(cached.content);
-    const resolvedContent = payload
-        ? resolvePayloadContent(payload, namespace)
-        : null;
-    if (!resolvedContent) {
-        throw new McpError(ErrorCode.InternalError, `Cached content is missing for namespace ${namespace}`);
-    }
-    return {
-        contents: [
-            {
-                uri: uri.href,
-                mimeType: resolveCacheMimeType(namespace),
-                text: resolvedContent,
-            },
-        ],
-    };
+function buildCachedContentResponse(uri, cacheKey) {
+    const cached = requireCacheEntry(cacheKey);
+    return buildMarkdownContentResponse(uri, cached.content);
 }
 function registerCacheContentResource(server) {
     server.registerResource('cached-content', new ResourceTemplate('superfetch://cache/{namespace}/{urlHash}', {
         list: listCachedResources,
     }), {
         title: 'Cached Content',
-        description: 'Access previously fetched web content from cache. Namespace: url, links, markdown. UrlHash: SHA-256 hash of the URL.',
+        description: 'Access previously fetched web content from cache. Namespace: markdown. UrlHash: SHA-256 hash of the URL.',
         mimeType: 'text/plain',
     }, (uri, params) => {
         const { namespace, urlHash } = resolveCacheParams(params);
         const cacheKey = `${namespace}:${urlHash}`;
-        return buildCachedContentResponse(uri, cacheKey, namespace);
+        return buildCachedContentResponse(uri, cacheKey);
     });
 }
-function registerCacheListResource(server) {
-    server.registerResource('cached-urls', 'superfetch://cache/list', {
-        title: 'Cached URLs List',
-        description: 'List all URLs currently in cache with their namespaces',
-        mimeType: 'application/json',
-    }, (uri) => ({
-        contents: [
-            {
-                uri: uri.href,
-                mimeType: 'application/json',
-                text: JSON.stringify(buildCacheListPayload(), null, 2),
-            },
-        ],
-    }));
-}
 function registerCacheUpdateSubscription(server) {
     const unsubscribe = cache.onCacheUpdate(({ cacheKey }) => {
-        const resourceUri = cache.toResourceUri(cacheKey);
+        const resourceUri = toResourceUri(cacheKey);
         if (!resourceUri)
             return;
         notifyResourceUpdate(server, resourceUri);
-        notifyResourceUpdate(server, 'superfetch://cache/list');
         if (server.isConnected()) {
             server.sendResourceListChanged();
         }
@@ -144,47 +107,26 @@ function registerCacheUpdateSubscription(server) {
         unsubscribe();
     };
 }
-function resolveCacheMimeType(namespace) {
-    if (namespace === 'markdown')
-        return 'text/markdown';
-    if (namespace === 'url')
-        return 'application/jsonl';
-    return 'application/json';
-}
-function isValidNamespace(namespace) {
-    return VALID_NAMESPACES.has(namespace);
-}
-function isValidHash(hash) {
-    return HASH_PATTERN.test(hash) && hash.length >= 8 && hash.length <= 64;
-}
-function resolveStringParam(value) {
-    return typeof value === 'string' ? value : null;
-}
-function parseCachedPayload(raw) {
-    try {
-        const parsed = JSON.parse(raw);
-        return isCachedPayload(parsed) ? parsed : null;
-    }
-    catch {
-        return null;
+function requireCacheEntry(cacheKey) {
+    const cached = cache.get(cacheKey);
+    if (!cached) {
+        throw new McpError(-32002, `Content not found in cache for key: ${cacheKey}`);
     }
+    return cached;
 }
-function isCachedPayload(value) {
-    if (!value || typeof value !== 'object')
-        return false;
-    const record = value;
-    return ((record.content === undefined || typeof record.content === 'string') &&
-        (record.markdown === undefined || typeof record.markdown === 'string'));
-}
-function resolvePayloadContent(payload, namespace) {
-    if (namespace === 'markdown') {
-        if (typeof payload.markdown === 'string') {
-            return payload.markdown;
-        }
-        if (typeof payload.content === 'string') {
-            return payload.content;
-        }
-        return null;
+function buildMarkdownContentResponse(uri, content) {
+    const payload = parseCachedPayload(content);
+    const resolvedContent = payload ? resolveCachedPayloadContent(payload) : null;
+    if (!resolvedContent) {
+        throw new McpError(ErrorCode.InternalError, 'Cached markdown content is missing');
     }
-    return typeof payload.content === 'string' ? payload.content : null;
+    return {
+        contents: [
+            {
+                uri: uri.href,
+                mimeType: 'text/markdown',
+                text: resolvedContent,
+            },
+        ],
+    };
 }

package/dist/resources/index.js

@@ -1,86 +1,4 @@
-import { config } from '../config/index.js';
-import * as cache from '../services/cache.js';
 import { registerCachedContentResource } from './cached-content.js';
-function registerJsonResource(server, definition) {
-    server.registerResource(definition.name, definition.uri, {
-        title: definition.title,
-        description: definition.description,
-        mimeType: 'application/json',
-    }, (uri) => ({
-        contents: [
-            {
-                uri: uri.href,
-                mimeType: 'application/json',
-                text: JSON.stringify(definition.buildPayload(), null, 2),
-            },
-        ],
-    }));
-}
-function buildHealthPayload() {
-    const memUsage = process.memoryUsage();
-    const heapUsedMB = Math.round(memUsage.heapUsed / 1024 / 1024);
-    const heapTotalMB = Math.round(memUsage.heapTotal / 1024 / 1024);
-    return {
-        status: 'healthy',
-        uptime: process.uptime(),
-        checks: {
-            cache: config.cache.enabled,
-            memory: {
-                heapUsed: heapUsedMB,
-                heapTotal: heapTotalMB,
-                percentage: Math.round((heapUsedMB / heapTotalMB) * 100),
-                healthy: heapUsedMB < 400,
-            },
-        },
-        timestamp: new Date().toISOString(),
-    };
-}
-function buildStatsPayload() {
-    return {
-        server: {
-            name: config.server.name,
-            version: config.server.version,
-            uptime: process.uptime(),
-            nodeVersion: process.version,
-            memoryUsage: process.memoryUsage(),
-        },
-        cache: {
-            enabled: config.cache.enabled,
-            ttl: config.cache.ttl,
-            maxKeys: config.cache.maxKeys,
-            totalKeys: cache.keys().length,
-        },
-        config: {
-            fetcher: {
-                timeout: config.fetcher.timeout,
-                maxRedirects: config.fetcher.maxRedirects,
-            },
-            extraction: {
-                extractMainContent: config.extraction.extractMainContent,
-                includeMetadata: config.extraction.includeMetadata,
-            },
-        },
-    };
-}
 export function registerResources(server) {
     registerCachedContentResource(server);
-    const resources = [
-        {
-            name: 'health',
-            uri: 'superfetch://health',
-            title: 'Server Health',
-            description: 'Real-time server health and dependency status',
-            buildPayload: buildHealthPayload,
-        },
-        {
-            name: 'stats',
-            uri: 'superfetch://stats',
-            title: 'Server Statistics',
-            description: 'Fetch statistics and cache performance metrics',
-            buildPayload: buildStatsPayload,
-        },
-    ];
-    for (const resource of resources) {
-        registerJsonResource(server, resource);
-    }
 }

package/dist/server.js

@@ -3,50 +3,64 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { config } from './config/index.js';
 import { destroyAgents } from './services/fetcher.js';
 import { logError, logInfo } from './services/logger.js';
-import { destroyTransformWorkers } from './services/transform-worker-pool.js';
 import { registerTools } from './tools/index.js';
-import { registerResources } from './resources/index.js';
-export function createMcpServer() {
-    const server = new McpServer({
+import { registerCachedContentResource } from './resources/cached-content.js';
+function createServerInfo() {
+    return {
         name: config.server.name,
         version: config.server.version,
-    }, {
-        capabilities: {
-            tools: { listChanged: false },
-            resources: { listChanged: true, subscribe: true },
-            logging: {},
-        },
-        instructions: `superFetch MCP server v${config.server.version} - AI-optimized web content fetching with JSONL/Markdown output. Provides tools for fetching, parsing, and transforming web content into structured formats suitable for LLM consumption. Supports resource subscriptions for cache updates.`,
+    };
+}
+function createServerCapabilities() {
+    return {
+        tools: { listChanged: false },
+        resources: { listChanged: true, subscribe: true },
+        logging: {},
+    };
+}
+function createServerInstructions(serverVersion) {
+    return `superFetch MCP server |${serverVersion}| A high-performance web content fetching and processing server.`;
+}
+export function createMcpServer() {
+    const server = new McpServer(createServerInfo(), {
+        capabilities: createServerCapabilities(),
+        instructions: createServerInstructions(config.server.version),
     });
     registerTools(server);
-    registerResources(server);
+    registerCachedContentResource(server);
     return server;
 }
-export async function startStdioServer() {
-    const server = createMcpServer();
-    const transport = new StdioServerTransport();
+function attachServerErrorHandler(server) {
     server.server.onerror = (error) => {
         logError('[MCP Error]', error instanceof Error ? error : { error });
     };
-    const handleShutdown = (signal) => {
-        process.stderr.write(`\n${signal} received, shutting down superFetch MCP server...\n`);
-        destroyAgents();
-        destroyTransformWorkers();
-        server
-            .close()
-            .catch((err) => {
-            logError('Error during shutdown', err instanceof Error ? err : undefined);
-        })
-            .finally(() => {
-            process.exit(0);
-        });
+}
+function handleShutdownSignal(server, signal) {
+    process.stderr.write(`\n${signal} received, shutting down superFetch MCP server...\n`);
+    destroyAgents();
+    server
+        .close()
+        .catch((err) => {
+        logError('Error during shutdown', err instanceof Error ? err : undefined);
+    })
+        .finally(() => {
+        process.exit(0);
+    });
+}
+function createShutdownHandler(server) {
+    return (signal) => {
+        handleShutdownSignal(server, signal);
     };
+}
+function registerSignalHandlers(handler) {
     process.on('SIGINT', () => {
-        handleShutdown('SIGINT');
+        handler('SIGINT');
     });
     process.on('SIGTERM', () => {
-        handleShutdown('SIGTERM');
+        handler('SIGTERM');
     });
+}
+async function connectStdioServer(server, transport) {
     try {
         await server.connect(transport);
         logInfo('superFetch MCP server running on stdio');
@@ -56,3 +70,10 @@ export async function startStdioServer() {
         process.exit(1);
     }
 }
+export async function startStdioServer() {
+    const server = createMcpServer();
+    const transport = new StdioServerTransport();
+    attachServerErrorHandler(server);
+    registerSignalHandlers(createShutdownHandler(server));
+    await connectStdioServer(server, transport);
+}

package/dist/services/cache-events.d.ts

@@ -0,0 +1,8 @@
+import type { CacheKeyParts } from './cache-keys.js';
+export interface CacheUpdateEvent extends CacheKeyParts {
+    cacheKey: string;
+}
+type CacheUpdateListener = (event: CacheUpdateEvent) => void;
+export declare function onCacheUpdate(listener: CacheUpdateListener): () => void;
+export declare function notifyCacheUpdate(cacheKey: string): void;
+export {};

package/dist/services/cache-events.js

@@ -0,0 +1,19 @@
+import { parseCacheKey } from './cache-keys.js';
+const updateListeners = new Set();
+export function onCacheUpdate(listener) {
+    updateListeners.add(listener);
+    return () => {
+        updateListeners.delete(listener);
+    };
+}
+export function notifyCacheUpdate(cacheKey) {
+    if (updateListeners.size === 0)
+        return;
+    const parts = parseCacheKey(cacheKey);
+    if (!parts)
+        return;
+    const event = { cacheKey, ...parts };
+    for (const listener of updateListeners) {
+        listener(event);
+    }
+}

package/dist/services/cache-keys.d.ts

@@ -0,0 +1,7 @@
+export interface CacheKeyParts {
+    namespace: string;
+    urlHash: string;
+}
+export declare function createCacheKey(namespace: string, url: string, vary?: Record<string, unknown> | string): string | null;
+export declare function parseCacheKey(cacheKey: string): CacheKeyParts | null;
+export declare function toResourceUri(cacheKey: string): string | null;

package/dist/services/cache-keys.js

@@ -0,0 +1,57 @@
+import { CACHE_HASH } from '../config/constants.js';
+import { sha256Hex } from '../utils/crypto.js';
+import { isRecord } from '../utils/guards.js';
+function stableStringify(value) {
+    if (!isRecord(value)) {
+        if (value === null || value === undefined) {
+            return '';
+        }
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map((item) => stableStringify(item)).join(',')}]`;
+    }
+    const entries = Object.entries(value)
+        .filter(([, entryValue]) => entryValue !== undefined)
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([key, entryValue]) => `${JSON.stringify(key)}:${stableStringify(entryValue)}`);
+    return `{${entries.join(',')}}`;
+}
+function createHashFragment(input, length) {
+    return sha256Hex(input).substring(0, length);
+}
+function buildCacheKey(namespace, urlHash, varyHash) {
+    return varyHash
+        ? `${namespace}:${urlHash}.${varyHash}`
+        : `${namespace}:${urlHash}`;
+}
+function getVaryHash(vary) {
+    if (!vary)
+        return undefined;
+    const varyString = typeof vary === 'string' ? vary : stableStringify(vary);
+    if (!varyString)
+        return undefined;
+    return createHashFragment(varyString, CACHE_HASH.VARY_HASH_LENGTH);
+}
+export function createCacheKey(namespace, url, vary) {
+    if (!namespace || !url)
+        return null;
+    const urlHash = createHashFragment(url, CACHE_HASH.URL_HASH_LENGTH);
+    const varyHash = getVaryHash(vary);
+    return buildCacheKey(namespace, urlHash, varyHash);
+}
+export function parseCacheKey(cacheKey) {
+    if (!cacheKey)
+        return null;
+    const [namespace, ...rest] = cacheKey.split(':');
+    const urlHash = rest.join(':');
+    if (!namespace || !urlHash)
+        return null;
+    return { namespace, urlHash };
+}
+export function toResourceUri(cacheKey) {
+    const parts = parseCacheKey(cacheKey);
+    if (!parts)
+        return null;
+    return `superfetch://cache/${parts.namespace}/${parts.urlHash}`;
+}