@j0hanz/fetch-url-mcp 1.0.0 → 1.1.0

package/dist/resources.js

@@ -1,6 +1,8 @@
 import { ResourceTemplate, } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { ErrorCode, McpError, } from '@modelcontextprotocol/sdk/types.js';
-import { get as getCacheEntry, keys as listCacheKeys, parseCachedPayload, parseCacheKey, resolveCachedPayloadContent, } from './cache.js';
+import { ErrorCode, McpError, SubscribeRequestSchema, UnsubscribeRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { get as getCacheEntry, keys as listCacheKeys, onCacheUpdate, parseCachedPayload, parseCacheKey, resolveCachedPayloadContent, } from './cache.js';
+import { logWarn } from './observability.js';
+import { isObject } from './type-guards.js';
 const CACHE_RESOURCE_TEMPLATE_URI = 'internal://cache/{namespace}/{hash}';
 const CACHE_RESOURCE_PREFIX = 'internal://cache/';
 const CACHE_NAMESPACE_PATTERN = /^[a-z0-9_-]{1,64}$/i;
@@ -34,8 +36,8 @@ function firstVariableValue(value) {
     return undefined;
 }
 function parseCacheResourceFromVariables(variables) {
-    const namespace = firstVariableValue(variables.namespace);
-    const hash = firstVariableValue(variables.hash);
+    const namespace = firstVariableValue(variables['namespace']);
+    const hash = firstVariableValue(variables['hash']);
     if (!namespace || !hash)
         return null;
     const decoded = {
@@ -86,7 +88,7 @@ function completeCacheNamespaces(value) {
 }
 function completeCacheHashes(value, context) {
     const normalized = value.trim().toLowerCase();
-    const namespace = context?.arguments?.namespace?.trim();
+    const namespace = context?.arguments?.['namespace']?.trim();
     const hashes = new Set();
     for (const key of listCacheKeys()) {
         const parsed = parseCacheKey(key);
@@ -106,7 +108,6 @@ function listCacheResources() {
     const resources = listCacheKeys()
         .map((key) => parseCacheKey(key))
         .filter((parts) => Boolean(parts))
-        .slice(0, MAX_COMPLETION_VALUES)
         .map((parts) => {
         const cacheParts = {
             namespace: parts.namespace,
@@ -126,6 +127,85 @@ function listCacheResources() {
     });
     return { resources };
 }
+function normalizeSubscriptionUri(uri) {
+    if (!URL.canParse(uri)) {
+        throw new McpError(ErrorCode.InvalidParams, 'Invalid resource URI');
+    }
+    const parsedUri = new URL(uri);
+    const cacheParts = parseCacheResourceFromUri(parsedUri);
+    if (cacheParts)
+        return toCacheResourceUri(cacheParts);
+    return parsedUri.href;
+}
+function registerCacheResourceNotifications(server) {
+    const subscribedResourceUris = new Set();
+    server.server.setRequestHandler(SubscribeRequestSchema, async (request) => {
+        subscribedResourceUris.add(normalizeSubscriptionUri(request.params.uri));
+        return Promise.resolve({});
+    });
+    server.server.setRequestHandler(UnsubscribeRequestSchema, async (request) => {
+        subscribedResourceUris.delete(normalizeSubscriptionUri(request.params.uri));
+        return Promise.resolve({});
+    });
+    const unsubscribe = onCacheUpdate((event) => {
+        const changedUri = toCacheResourceUri({
+            namespace: event.namespace,
+            hash: event.urlHash,
+        });
+        if (server.isConnected() && subscribedResourceUris.has(changedUri)) {
+            void server.server
+                .sendResourceUpdated({ uri: changedUri })
+                .catch((error) => {
+                logWarn('Failed to send resource updated notification', {
+                    uri: changedUri,
+                    error,
+                });
+            });
+        }
+        if (!event.listChanged)
+            return;
+        if (!server.isConnected())
+            return;
+        try {
+            server.sendResourceListChanged();
+        }
+        catch (error) {
+            logWarn('Failed to send resources list changed notification', { error });
+        }
+    });
+    let cleanedUp = false;
+    const cleanup = () => {
+        if (cleanedUp)
+            return;
+        cleanedUp = true;
+        unsubscribe();
+    };
+    const originalOnClose = server.server.onclose;
+    server.server.onclose = () => {
+        cleanup();
+        originalOnClose?.();
+    };
+    const originalClose = server.close.bind(server);
+    server.close = async () => {
+        cleanup();
+        await originalClose();
+    };
+}
+function normalizeTemplateVariables(variables) {
+    if (!isObject(variables))
+        return {};
+    const normalized = {};
+    for (const [key, value] of Object.entries(variables)) {
+        if (typeof value === 'string' || value === undefined) {
+            normalized[key] = value;
+            continue;
+        }
+        if (Array.isArray(value)) {
+            normalized[key] = value.filter((item) => typeof item === 'string');
+        }
+    }
+    return normalized;
+}
 function resolveCacheResourceParts(uri, variables) {
     const fromVariables = parseCacheResourceFromVariables(variables);
     if (fromVariables)
@@ -212,5 +292,6 @@ export function registerCacheResourceTemplate(server, iconInfo) {
                 ],
             }
             : {}),
-    }, (uri, variables) => readCacheResource(uri, variables));
+    }, (uri, variables) => readCacheResource(uri, normalizeTemplateVariables(variables)));
+    registerCacheResourceNotifications(server);
 }

package/dist/server.js

@@ -42,7 +42,10 @@ catch (error) {
 function createServerCapabilities() {
     return {
         logging: {},
-        resources: {},
+        resources: {
+            subscribe: true,
+            listChanged: true,
+        },
         tools: {},
         prompts: {},
         completions: {},

package/dist/session.js

@@ -56,12 +56,15 @@ class SessionCleanupLoop {
         for await (const getNow of ticks) {
             const now = getNow();
             const evicted = this.store.evictExpired();
-            for (const session of evicted) {
-                unregisterMcpSessionServerByServer(session.server);
-                void Promise.allSettled([
-                    session.transport.close(),
-                    session.server.close(),
-                ]).then((results) => {
+            const closeBatchSize = 10;
+            for (let i = 0; i < evicted.length; i += closeBatchSize) {
+                const batch = evicted.slice(i, i + closeBatchSize);
+                await Promise.allSettled(batch.map(async (session) => {
+                    unregisterMcpSessionServerByServer(session.server);
+                    const results = await Promise.allSettled([
+                        session.transport.close(),
+                        session.server.close(),
+                    ]);
                     const [transportResult, serverResult] = results;
                     if (transportResult.status === 'rejected') {
                         logWarn('Failed to close expired session transport', {
@@ -73,7 +76,9 @@ class SessionCleanupLoop {
                             error: formatError(serverResult.reason),
                         });
                     }
-                });
+                }));
+                if (signal.aborted)
+                    return;
             }
             if (evicted.length > 0) {
                 logInfo('Expired sessions evicted', {

package/dist/tools.js

@@ -53,6 +53,11 @@ const fetchUrlOutputSchema = z.strictObject({
         .max(config.constants.maxUrlLength)
         .optional()
         .describe('The final response URL after redirects'),
+    cacheResourceUri: z
+        .string()
+        .max(config.constants.maxUrlLength)
+        .optional()
+        .describe('Internal cache resource URI for retrieving full markdown via resources/read'),
     title: z.string().max(512).optional().describe('Page title'),
     metadata: z
         .strictObject({
@@ -390,7 +395,7 @@ function applyInlineContentLimit(content, inlineLimitOverride) {
     return inlineLimiter.apply(content, inlineLimitOverride);
 }
 /* -------------------------------------------------------------------------------------------------
- * Tool response blocks (text only)
+ * Tool response blocks (text + optional embedded resource)
  * ------------------------------------------------------------------------------------------------- */
 function buildTextBlock(structuredContent) {
     return {
@@ -398,8 +403,46 @@ function buildTextBlock(structuredContent) {
         text: JSON.stringify(structuredContent),
     };
 }
-function buildToolContentBlocks(structuredContent) {
-    return [buildTextBlock(structuredContent)];
+function buildEmbeddedResource(content, url, title) {
+    if (!content)
+        return null;
+    const filename = cache.generateSafeFilename(url, title, undefined, '.md');
+    const uri = new URL(filename, 'file:///').href;
+    const resource = {
+        uri,
+        mimeType: 'text/markdown',
+        text: content,
+    };
+    return {
+        type: 'resource',
+        resource,
+    };
+}
+function buildCacheResourceLink(cacheResourceUri, contentSize, fetchedAt) {
+    return {
+        type: 'resource_link',
+        uri: cacheResourceUri,
+        name: 'cached-markdown',
+        title: 'Cached Fetch Output',
+        description: 'Read full markdown via resources/read.',
+        mimeType: 'text/markdown',
+        ...(contentSize > 0 ? { size: contentSize } : {}),
+        annotations: {
+            audience: ['assistant'],
+            priority: 0.8,
+            lastModified: fetchedAt,
+        },
+    };
+}
+function buildToolContentBlocks(structuredContent, resourceLink, embeddedResource) {
+    const blocks = [buildTextBlock(structuredContent)];
+    if (resourceLink) {
+        blocks.push(resourceLink);
+    }
+    if (embeddedResource) {
+        blocks.push(embeddedResource);
+    }
+    return blocks;
 }
 function resolveNormalizedUrl(url) {
     const { normalizedUrl: validatedUrl } = normalizeUrl(url);
@@ -415,7 +458,7 @@ function logRawUrlTransformation(resolvedUrl) {
 }
 function extractTitle(value) {
     const record = asRecord(value);
-    const title = record ? record.title : undefined;
+    const title = record ? record['title'] : undefined;
     return typeof title === 'string' ? title : undefined;
 }
 function logCacheMiss(reason, cacheNamespace, normalizedUrl, error) {
@@ -663,6 +706,7 @@ function serializeMarkdownResult(result) {
  * fetch-url tool implementation
  * ------------------------------------------------------------------------------------------------- */
 function buildStructuredContent(pipeline, inlineResult, inputUrl) {
+    const cacheResourceUri = resolveCacheResourceUri(pipeline.cacheKey);
     const truncated = inlineResult.truncated ?? pipeline.data.truncated;
     let markdown = inlineResult.content;
     if (pipeline.data.truncated &&
@@ -675,6 +719,7 @@ function buildStructuredContent(pipeline, inlineResult, inputUrl) {
         url: pipeline.originalUrl ?? pipeline.url,
         resolvedUrl: pipeline.url,
         ...(pipeline.finalUrl ? { finalUrl: pipeline.finalUrl } : {}),
+        ...(cacheResourceUri ? { cacheResourceUri } : {}),
         inputUrl,
         title: pipeline.data.title,
         ...(metadata ? { metadata } : {}),
@@ -685,12 +730,34 @@ function buildStructuredContent(pipeline, inlineResult, inputUrl) {
         ...(truncated ? { truncated: true } : {}),
     };
 }
-function buildFetchUrlContentBlocks(structuredContent) {
-    return buildToolContentBlocks(structuredContent);
+function resolveCacheResourceUri(cacheKey) {
+    if (!cacheKey)
+        return undefined;
+    if (!cache.isEnabled())
+        return undefined;
+    if (!cache.get(cacheKey))
+        return undefined;
+    const parsed = cache.parseCacheKey(cacheKey);
+    if (!parsed)
+        return undefined;
+    return `internal://cache/${encodeURIComponent(parsed.namespace)}/${encodeURIComponent(parsed.urlHash)}`;
+}
+function buildFetchUrlContentBlocks(structuredContent, pipeline, inlineResult) {
+    const cacheResourceUri = readString(structuredContent, 'cacheResourceUri');
+    const contentToEmbed = config.runtime.httpMode
+        ? inlineResult.content
+        : pipeline.data.content;
+    const resourceLink = cacheResourceUri
+        ? buildCacheResourceLink(cacheResourceUri, inlineResult.contentSize, pipeline.fetchedAt)
+        : null;
+    const embedded = contentToEmbed && pipeline.url
+        ? buildEmbeddedResource(contentToEmbed, pipeline.url, pipeline.data.title)
+        : null;
+    return buildToolContentBlocks(structuredContent, resourceLink, embedded);
 }
 function buildResponse(pipeline, inlineResult, inputUrl) {
     const structuredContent = buildStructuredContent(pipeline, inlineResult, inputUrl);
-    const content = buildFetchUrlContentBlocks(structuredContent);
+    const content = buildFetchUrlContentBlocks(structuredContent, pipeline, inlineResult);
     // Runtime validation guard: verify output matches schema
     const validation = fetchUrlOutputSchema.safeParse(structuredContent);
     if (!validation.success) {

package/dist/transform.js

@@ -44,7 +44,7 @@ function getTagName(node) {
 }
 function getAbortReason(signal) {
     const record = isObject(signal) ? signal : null;
-    return record && 'reason' in record ? record.reason : undefined;
+    return record && 'reason' in record ? record['reason'] : undefined;
 }
 function isTimeoutAbortReason(reason) {
     return reason instanceof Error && reason.name === 'TimeoutError';
@@ -424,6 +424,35 @@ function isReadabilityCompatible(doc) {
             'function' &&
         typeof record.querySelector === 'function');
 }
+function resolveCollapsedTextLengthUpTo(text, max) {
+    if (max <= 0)
+        return 0;
+    let length = 0;
+    let seenNonWhitespace = false;
+    let pendingSpace = false;
+    for (let i = 0; i < text.length; i += 1) {
+        const code = text.charCodeAt(i);
+        const isWhitespace = code <= 0x20;
+        if (isWhitespace) {
+            if (seenNonWhitespace)
+                pendingSpace = true;
+            continue;
+        }
+        if (!seenNonWhitespace) {
+            seenNonWhitespace = true;
+        }
+        else if (pendingSpace) {
+            length += 1;
+            pendingSpace = false;
+            if (length >= max)
+                return length;
+        }
+        length += 1;
+        if (length >= max)
+            return length;
+    }
+    return length;
+}
 function extractArticle(document, url, signal) {
     if (!isReadabilityCompatible(document)) {
         logWarn('Document not compatible with Readability');
@@ -436,7 +465,7 @@ function extractArticle(document, url, signal) {
         const rawText = doc.querySelector('body')?.textContent ??
             doc.documentElement.textContent ??
             '';
-        const textLength = rawText.replace(/\s+/g, ' ').trim().length;
+        const textLength = resolveCollapsedTextLengthUpTo(rawText, 401);
         if (textLength < 100) {
             logWarn('Very minimal server-rendered content detected (< 100 chars). ' +
                 'This might be a client-side rendered (SPA) application. ' +
@@ -1610,13 +1639,13 @@ function isWorkerErrorPayload(value) {
 function isWorkerResponse(raw) {
     if (!isObject(raw))
         return false;
-    if (typeof raw.id !== 'string')
+    if (typeof raw['id'] !== 'string')
         return false;
-    if (raw.type === 'result') {
-        return isWorkerResultPayload(raw.result);
+    if (raw['type'] === 'result') {
+        return isWorkerResultPayload(raw['result']);
     }
-    if (raw.type === 'error') {
-        return isWorkerErrorPayload(raw.error);
+    if (raw['type'] === 'error') {
+        return isWorkerErrorPayload(raw['error']);
     }
     return false;
 }
@@ -2287,7 +2316,7 @@ async function transformWithWorkerPool(htmlOrBuffer, url, options) {
     });
 }
 function resolveWorkerFallback(error, htmlOrBuffer, url, options) {
-    const isQueueFull = error instanceof FetchError && error.details.reason === 'queue_full';
+    const isQueueFull = error instanceof FetchError && error.details['reason'] === 'queue_full';
     if (isQueueFull) {
         logWarn('Transform worker queue full; falling back to in-process', {
             url: redactUrl(url),

package/dist/workers/transform-child.js

@@ -122,15 +122,16 @@ process.on('message', (raw) => {
     if (!raw || typeof raw !== 'object')
         return;
     const msg = raw;
-    if (msg.type === 'cancel') {
-        if (typeof msg.id !== 'string')
+    const { type, id } = msg;
+    if (type === 'cancel') {
+        if (typeof id !== 'string')
             return;
-        const controller = controllersById.get(msg.id);
+        const controller = controllersById.get(id);
         if (controller)
             controller.abort(new Error('Canceled'));
         return;
     }
-    if (msg.type === 'transform') {
+    if (type === 'transform') {
         handleTransform(msg);
     }
 });

package/dist/workers/transform-worker.js

@@ -114,15 +114,16 @@ port.on('message', (raw) => {
     if (!raw || typeof raw !== 'object')
         return;
     const msg = raw;
-    if (msg.type === 'cancel') {
-        if (typeof msg.id !== 'string')
+    const { type, id } = msg;
+    if (type === 'cancel') {
+        if (typeof id !== 'string')
             return;
-        const controller = controllersById.get(msg.id);
+        const controller = controllersById.get(id);
         if (controller)
             controller.abort(new Error('Canceled'));
         return;
     }
-    if (msg.type === 'transform') {
+    if (type === 'transform') {
         handleTransform(msg);
     }
 });

package/package.json

@@ -1,91 +1,91 @@
-{
-  "name": "@j0hanz/fetch-url-mcp",
-  "version": "1.0.0",
-  "mcpName": "io.github.j0hanz/fetch-url-mcp",
-  "description": "Intelligent web content fetcher MCP server that converts HTML to clean, AI-readable Markdown",
-  "type": "module",
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "bin": {
-    "fetch-url-mcp": "dist/index.js"
-  },
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "default": "./dist/index.js"
-    },
-    "./package.json": "./package.json"
-  },
-  "files": [
-    "dist",
-    "README.md"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/j0hanz/fetch-url-mcp.git"
-  },
-  "homepage": "https://github.com/j0hanz/fetch-url-mcp#readme",
-  "bugs": {
-    "url": "https://github.com/j0hanz/fetch-url-mcp/issues"
-  },
-  "author": "j0hanz",
-  "license": "MIT",
-  "keywords": [
-    "mcp",
-    "mcp-server",
-    "web-fetching",
-    "content-extraction",
-    "readability",
-    "markdown",
-    "ai-tools",
-    "model-context-protocol",
-    "fetch-url-mcp"
-  ],
-  "scripts": {
-    "clean": "node scripts/tasks.mjs clean",
-    "validate:instructions": "node scripts/tasks.mjs validate:instructions",
-    "build": "node scripts/tasks.mjs build",
-    "copy:assets": "node scripts/tasks.mjs copy:assets",
-    "prepare": "npm run build",
-    "dev": "tsc --watch --preserveWatchOutput",
-    "dev:run": "node --env-file=.env --watch dist/index.js",
-    "start": "node dist/index.js",
-    "format": "prettier --write .",
-    "type-check": "node scripts/tasks.mjs type-check",
-    "type-check:diagnostics": "tsc --noEmit --extendedDiagnostics",
-    "type-check:trace": "node -e \"require('fs').rmSync('.ts-trace',{recursive:true,force:true})\" && tsc --noEmit --generateTrace .ts-trace",
-    "lint": "eslint .",
-    "lint:fix": "eslint . --fix",
-    "test": "node scripts/tasks.mjs test",
-    "test:coverage": "node scripts/tasks.mjs test --coverage",
-    "knip": "knip",
-    "knip:fix": "knip --fix",
-    "inspector": "npm run build && npx -y @modelcontextprotocol/inspector node dist/index.js --stdio",
-    "prepublishOnly": "npm run lint && npm run type-check && npm run build"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.26.0",
-    "@mozilla/readability": "^0.6.0",
-    "linkedom": "^0.18.12",
-    "node-html-markdown": "^2.0.0",
-    "zod": "^4.3.6"
-  },
-  "devDependencies": {
-    "@eslint/js": "^9.39.2",
-    "@trivago/prettier-plugin-sort-imports": "^6.0.2",
-    "@types/node": "^24",
-    "eslint": "^9.23.2",
-    "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-de-morgan": "^2.0.0",
-    "eslint-plugin-depend": "^1.4.0",
-    "eslint-plugin-sonarjs": "^3.0.6",
-    "eslint-plugin-unused-imports": "^4.4.1",
-    "knip": "^5.83.1",
-    "prettier": "^3.8.1",
-    "typescript": "^5.9.3",
-    "typescript-eslint": "^8.55.0"
-  },
-  "engines": {
-    "node": ">=24"
-  }
-}
+{
+  "name": "@j0hanz/fetch-url-mcp",
+  "version": "1.1.0",
+  "mcpName": "io.github.j0hanz/fetch-url-mcp",
+  "description": "Intelligent web content fetcher MCP server that converts HTML to clean, AI-readable Markdown",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "fetch-url-mcp": "dist/index.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/j0hanz/fetch-url-mcp.git"
+  },
+  "homepage": "https://github.com/j0hanz/fetch-url-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/j0hanz/fetch-url-mcp/issues"
+  },
+  "author": "j0hanz",
+  "license": "MIT",
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "web-fetching",
+    "content-extraction",
+    "readability",
+    "markdown",
+    "ai-tools",
+    "model-context-protocol",
+    "fetch-url-mcp"
+  ],
+  "scripts": {
+    "clean": "node scripts/tasks.mjs clean",
+    "validate:instructions": "node scripts/tasks.mjs validate:instructions",
+    "build": "node scripts/tasks.mjs build",
+    "copy:assets": "node scripts/tasks.mjs copy:assets",
+    "prepare": "npm run build",
+    "dev": "tsc --watch --preserveWatchOutput",
+    "dev:run": "node --env-file=.env --watch dist/index.js",
+    "start": "node dist/index.js",
+    "format": "prettier --write .",
+    "type-check": "node scripts/tasks.mjs type-check",
+    "type-check:diagnostics": "tsc --noEmit --extendedDiagnostics",
+    "type-check:trace": "node -e \"require('fs').rmSync('.ts-trace',{recursive:true,force:true})\" && tsc --noEmit --generateTrace .ts-trace",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "test": "node scripts/tasks.mjs test",
+    "test:coverage": "node scripts/tasks.mjs test --coverage",
+    "knip": "knip",
+    "knip:fix": "knip --fix",
+    "inspector": "npm run build && npx -y @modelcontextprotocol/inspector node dist/index.js --stdio",
+    "prepublishOnly": "npm run lint && npm run type-check && npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "@mozilla/readability": "^0.6.0",
+    "linkedom": "^0.18.12",
+    "node-html-markdown": "^2.0.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.2",
+    "@trivago/prettier-plugin-sort-imports": "^6.0.2",
+    "@types/node": "^24",
+    "eslint": "^9.23.2",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-de-morgan": "^2.0.0",
+    "eslint-plugin-depend": "^1.4.0",
+    "eslint-plugin-sonarjs": "^3.0.6",
+    "eslint-plugin-unused-imports": "^4.4.1",
+    "knip": "^5.83.1",
+    "prettier": "^3.8.1",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.55.0"
+  },
+  "engines": {
+    "node": ">=24"
+  }
+}