@j0hanz/fetch-url-mcp 1.13.0 → 2.0.1

package/dist/tools/index.js

@@ -1,15 +1,15 @@
-import { ErrorCode, } from '@modelcontextprotocol/sdk/types.js';
+import { ProtocolErrorCode, } from '@modelcontextprotocol/server';
 import { config } from '../lib/config.js';
-import { Loggers, logInfo } from '../lib/core.js';
-import { classifyAndLogToolError, isAbortError } from '../lib/error/index.js';
-import { createMcpError, createProgressReporter, registerToolPresentation, validateOrThrow, } from '../lib/mcp-interop.js';
+import { logError, Loggers, logInfo } from '../lib/core.js';
+import { classifyAndLogToolError, FetchError, getErrorMessage, handleToolError, isAbortError, } from '../lib/error/index.js';
+import { createProgressReporter, createProtocolError, validateOrThrow, } from '../lib/mcp-interop.js';
 import { finalizeInlineMarkdown, markdownTransform, performSharedFetch, withSignal, } from '../lib/net/index.js';
 import { composeAbortSignal, isObject } from '../lib/utils.js';
 import { fetchUrlInputSchema, fetchUrlOutputSchema, normalizeExtractedMetadata, normalizePageTitle, } from '../schemas.js';
-import { registerTaskCapableTool, setTaskCapableToolSupport, unregisterTaskCapableTool, withRequestContextIfMissing, } from '../tasks/index.js';
+import { attachAbortController, detachAbortController, withRelatedTaskMeta, } from '../tasks/index.js';
 export const FETCH_URL_TOOL_NAME = 'fetch-url';
-const FETCH_URL_TOOL_DESCRIPTION = `
-Fetch public webpages and convert HTML to clean Markdown.
+const FETCH_URL_TOOL_DESCRIPTION = `
+Fetch public webpages and convert HTML to clean Markdown.
 `.trim();
 const TOOL_ICON = {
     src: 'data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCIgZmlsbD0ibm9uZSIgc3Ryb2tlPSJjdXJyZW50Q29sb3IiIHN0cm9rZS13aWR0aD0iMiIgc3Ryb2tlLWxpbmVjYXA9InJvdW5kIiBzdHJva2UtbGluZWpvaW49InJvdW5kIj48cGF0aCBkPSJNMjEgMTV2NGEyIDIgMCAwIDEtMiAySDVhMiAyIDAgMCAxLTItMnYtNCIvPjxwb2x5bGluZSBwb2ludHM9IjcgMTAgMTIgMTUgMTcgMTAiLz48bGluZSB4MT0iMTIiIHkxPSIxNSIgeDI9IjEyIiB5Mj0iMyIvPjwvc3ZnPg==',
@@ -63,7 +63,7 @@ function buildStructuredContent(pipeline, inlineResult, inputUrl) {
     };
 }
 function validateStructuredContent(structuredContent) {
-    validateOrThrow(fetchUrlOutputSchema, structuredContent, ErrorCode.InternalError, 'Output validation failed', Loggers.LOG_FETCH_URL);
+    validateOrThrow(fetchUrlOutputSchema, structuredContent, ProtocolErrorCode.InternalError, 'Output validation failed', Loggers.LOG_FETCH_URL);
 }
 export function buildFetchUrlContentBlocks(structuredContent) {
     const markdown = typeof structuredContent['markdown'] === 'string'
@@ -92,14 +92,16 @@ const Step = {
     DONE: 7,
 };
 function formatContentSize(contentSize) {
-    if (contentSize < 1000)
-        return `${contentSize} chars`;
-    if (contentSize < 1_000_000)
-        return `${(contentSize / 1024).toFixed(1)} KB`;
-    return `${(contentSize / (1024 * 1024)).toFixed(1)} MB`;
+    if (contentSize < 1024)
+        return `${contentSize} B`;
+    if (contentSize < 1_048_576) {
+        const kb = contentSize / 1024;
+        return kb < 10 ? `${kb.toFixed(1)} KB` : `${kb.toFixed(0)} KB`;
+    }
+    return `${(contentSize / 1_048_576).toFixed(1)} MB`;
 }
 function buildFetchSuccessSummary(contentSize) {
-    return `Done — ${formatContentSize(contentSize)}`;
+    return `Fetch completed \u2022 ${formatContentSize(contentSize)}`;
 }
 export function getFetchCompletionStatusMessage(result) {
     if (!isObject(result))
@@ -115,25 +117,59 @@ export function getFetchCompletionStatusMessage(result) {
 export class FetchUrlProgressPlan {
     reporter;
     context;
+    onStatusMessage;
     total = Step.DONE;
-    constructor(reporter, context) {
+    constructor(reporter, context, onStatusMessage) {
         this.reporter = reporter;
         this.context = context;
+        this.onStatusMessage = onStatusMessage;
     }
     reportStart() {
-        this.reporter.report(Step.START, 'Preparing request', this.total);
+        const message = 'Preparing';
+        this.onStatusMessage?.(message);
+        this.reporter.report({
+            progress: Step.START,
+            message,
+            total: this.total,
+        });
     }
     reportStage(stage) {
         const mapped = this.mapStage(stage);
         if (!mapped)
             return;
-        this.reporter.report(mapped.step, mapped.message, this.total);
+        this.onStatusMessage?.(mapped.message);
+        this.reporter.report({
+            progress: mapped.step,
+            message: mapped.message,
+            total: this.total,
+        });
     }
     reportSuccess(contentSize) {
-        this.reporter.report(Step.DONE, buildFetchSuccessSummary(contentSize), this.total);
+        const message = buildFetchSuccessSummary(contentSize);
+        this.onStatusMessage?.(message);
+        this.reporter.report({
+            progress: Step.DONE,
+            message,
+            total: this.total,
+        });
     }
-    reportFailure(cancelled) {
-        this.reporter.report(Step.DONE, cancelled ? 'Cancelled' : 'Failed', this.total);
+    reportFailure(cancelled, error) {
+        let message;
+        if (cancelled) {
+            message = 'Cancelled';
+        }
+        else if (error instanceof FetchError && error.statusCode > 0) {
+            message = `Fetch failed \u2022 ${String(error.statusCode)}`;
+        }
+        else {
+            message = 'Fetch failed';
+        }
+        this.onStatusMessage?.(message);
+        this.reporter.report({
+            progress: Step.DONE,
+            message,
+            total: this.total,
+        });
     }
     mapStage(stage) {
         switch (stage) {
@@ -150,20 +186,23 @@ export class FetchUrlProgressPlan {
             case 'response_ready':
                 return {
                     step: Step.RESPONSE,
-                    message: 'Received response',
+                    message: 'Processing response',
                 };
             case 'transform_start':
                 return {
                     step: Step.TRANSFORM,
-                    message: 'Parsing HTML -> Markdown',
+                    message: 'Converting to Markdown',
                 };
             case 'prepare_output':
                 return {
                     step: Step.PREPARE,
-                    message: 'Fetch completed',
+                    message: 'Finalizing',
                 };
             case 'finalize_output':
-                return undefined;
+                return {
+                    step: Step.DONE,
+                    message: 'Fetch completed',
+                };
         }
     }
 }
@@ -174,7 +213,7 @@ function buildToolAbortSignal(extraSignal) {
     const timeout = config.tools.timeoutMs > 0 ? config.tools.timeoutMs : HARD_TOOL_TIMEOUT_MS;
     const signal = composeAbortSignal(extraSignal, timeout);
     if (!signal) {
-        throw createMcpError(ErrorCode.InternalError, 'Failed to create timeout signal');
+        throw createProtocolError(ProtocolErrorCode.InternalError, 'Failed to create timeout signal');
     }
     return signal;
 }
@@ -190,21 +229,35 @@ function buildFetchOptions(url, signal, progressPlan) {
         },
     };
 }
-async function executeFetch(input, extra) {
+async function writeRequestScopedLog(ctx, level, message, data) {
+    if (!ctx)
+        return;
+    try {
+        await ctx.mcpReq.log(level, { message, ...data }, Loggers.LOG_FETCH_URL);
+    }
+    catch {
+        // Request-scoped logging is best-effort; internal logging remains authoritative.
+    }
+}
+async function executeFetch(input, ctx, executionSignal, onStatusMessage) {
     const { url } = input;
-    const signal = buildToolAbortSignal(extra?.signal);
+    const mcpReq = ctx?.mcpReq;
+    const signal = buildToolAbortSignal(executionSignal ?? mcpReq?.signal);
     const startedAt = performance.now();
-    const relatedTaskMeta = extra?._meta?.['modelcontextprotocol.io/related-task'];
-    const relatedTask = isObject(relatedTaskMeta) ? relatedTaskMeta : undefined;
-    const progressPlan = new FetchUrlProgressPlan(createProgressReporter(extra), formatUrlForDisplay(url));
+    const meta = mcpReq?._meta;
+    const progressToken = meta?.progressToken;
+    const taskId = ctx?.task?.id;
+    const progressPlan = new FetchUrlProgressPlan(createProgressReporter(ctx), formatUrlForDisplay(url), onStatusMessage);
     try {
         logInfo('fetch-url started', {
             inputUrl: url,
-            hasProgressToken: extra?._meta?.progressToken !== undefined,
-            ...(isObject(relatedTask) && typeof relatedTask['taskId'] === 'string'
-                ? { taskId: relatedTask['taskId'] }
-                : {}),
+            hasProgressToken: progressToken !== undefined,
+            ...(taskId ? { taskId } : {}),
         }, Loggers.LOG_FETCH_URL);
+        await writeRequestScopedLog(ctx, 'info', 'fetch-url started', {
+            inputUrl: url,
+            ...(taskId ? { taskId } : {}),
+        });
         progressPlan.reportStart();
         const { pipeline, inlineResult } = await performSharedFetch(buildFetchOptions(url, signal, progressPlan));
         const truncated = inlineResult.truncated ?? pipeline.data.truncated;
@@ -216,18 +269,30 @@ async function executeFetch(input, extra) {
             durationMs: Math.round(performance.now() - startedAt),
             ...(truncated ? { truncated: true } : {}),
         }, Loggers.LOG_FETCH_URL);
+        await writeRequestScopedLog(ctx, 'info', 'fetch-url completed', {
+            inputUrl: url,
+            resolvedUrl: pipeline.url,
+            contentSize: inlineResult.contentSize,
+            ...(taskId ? { taskId } : {}),
+            ...(truncated ? { truncated: true } : {}),
+        });
         const response = buildResponse(pipeline, inlineResult, url);
         progressPlan.reportSuccess(inlineResult.contentSize);
         return response;
     }
     catch (error) {
-        progressPlan.reportFailure(isAbortError(error));
+        progressPlan.reportFailure(isAbortError(error), error);
+        await writeRequestScopedLog(ctx, isAbortError(error) ? 'warning' : 'error', 'fetch-url failed', {
+            inputUrl: url,
+            error: getErrorMessage(error),
+            ...(taskId ? { taskId } : {}),
+        });
         throw error;
     }
 }
-export async function fetchUrlToolHandler(input, extra) {
+export async function fetchUrlToolHandler(input, ctx) {
     const startedAt = performance.now();
-    return executeFetch(input, extra).catch((error) => {
+    return executeFetch(input, ctx).catch((error) => {
         const durationMs = Math.round(performance.now() - startedAt);
         return classifyAndLogToolError(error, { url: input.url, durationMs }, Loggers.LOG_FETCH_URL, 'fetch-url', 'Failed to fetch URL');
     });
@@ -249,42 +314,72 @@ const TOOL_DEFINITION = {
         openWorldHint: true,
     },
 };
-function createTaskCapableDescriptor() {
-    return {
-        name: TOOL_DEFINITION.name,
-        parseArguments: (args) => {
-            return validateOrThrow(TOOL_DEFINITION.inputSchema, args, ErrorCode.InvalidParams, 'Invalid parameters for fetch-url', Loggers.LOG_FETCH_URL);
-        },
-        execute: TOOL_DEFINITION.handler,
-        getCompletionStatusMessage: getFetchCompletionStatusMessage,
-        taskSupport: 'optional',
-    };
-}
 export function registerTools(server) {
     if (!config.tools.enabled.includes(FETCH_URL_TOOL_NAME)) {
-        unregisterTaskCapableTool(server, FETCH_URL_TOOL_NAME);
         return {
             setTaskSupport: () => { },
         };
     }
-    const descriptor = createTaskCapableDescriptor();
-    registerTaskCapableTool(server, descriptor);
-    const registeredTool = server.registerTool(TOOL_DEFINITION.name, {
+    const registeredTool = server.experimental.tasks.registerToolTask(TOOL_DEFINITION.name, {
         title: TOOL_DEFINITION.title,
         description: TOOL_DEFINITION.description,
         inputSchema: TOOL_DEFINITION.inputSchema,
         outputSchema: TOOL_DEFINITION.outputSchema,
         annotations: TOOL_DEFINITION.annotations,
         execution: { taskSupport: 'optional' },
-        icons: [TOOL_ICON],
-    }, withRequestContextIfMissing(TOOL_DEFINITION.handler));
-    registerToolPresentation(server, TOOL_DEFINITION.name, {
-        icons: [TOOL_ICON],
+        _meta: { icons: [TOOL_ICON] },
+    }, {
+        createTask: async (args, ctx) => {
+            const task = await ctx.task.store.createTask(ctx.task.requestedTtl !== undefined
+                ? { ttl: ctx.task.requestedTtl }
+                : {});
+            const taskSignal = attachAbortController(task.taskId).signal;
+            const updateStatus = (message) => {
+                void ctx.task.store.updateTaskStatus(task.taskId, 'working', message);
+            };
+            // Spin off background execution
+            executeFetch(args, ctx, taskSignal, updateStatus)
+                .then(async (result) => {
+                try {
+                    await ctx.task.store.storeTaskResult(task.taskId, 'completed', result);
+                }
+                catch (storeError) {
+                    logError('Failed to store completed task result', {
+                        taskId: task.taskId,
+                        error: getErrorMessage(storeError),
+                    }, Loggers.LOG_TASKS);
+                    await ctx.task.store.updateTaskStatus(task.taskId, 'failed', 'Failed to store result');
+                }
+            })
+                .catch(async (error) => {
+                logError('Background execution crashed', { taskId: task.taskId, error: getErrorMessage(error) }, Loggers.LOG_TASKS);
+                const errorResult = handleToolError(error, args.url, 'Background execution failed');
+                try {
+                    await ctx.task.store.storeTaskResult(task.taskId, 'failed', errorResult);
+                }
+                catch (storeError) {
+                    logError('Failed to store task error result', {
+                        taskId: task.taskId,
+                        error: getErrorMessage(storeError),
+                    }, Loggers.LOG_TASKS);
+                    await ctx.task.store.updateTaskStatus(task.taskId, 'failed', getErrorMessage(error));
+                }
+            })
+                .finally(() => {
+                detachAbortController(task.taskId);
+            });
+            return { task };
+        },
+        getTask: async (_args, ctx) => {
+            return ctx.task.store.getTask(ctx.task.id);
+        },
+        getTaskResult: async (_args, ctx) => {
+            const result = (await ctx.task.store.getTaskResult(ctx.task.id));
+            return withRelatedTaskMeta(result, ctx.task.id);
+        },
     });
     const updateTaskSupport = (support) => {
-        setTaskCapableToolSupport(server, FETCH_URL_TOOL_NAME, support);
         registeredTool.execution = { taskSupport: support };
     };
-    updateTaskSupport('optional');
     return { setTaskSupport: updateTaskSupport };
 }

package/dist/transform/index.js

@@ -540,7 +540,7 @@ export function buildMetadataFooter(metadata, fallbackUrl) {
     if (parts.length > 0)
         lines.push(` ${parts.join(' | ')}`);
     if (metadata.description)
-        lines.push(` <sub>${metadata.description}</sub>`);
+        lines.push(` ${metadata.description}`);
     return lines.join('\n');
 }
 // eslint-disable-next-line sonarjs/slow-regex -- bounded title separator, no user input

package/package.json

@@ -1,108 +1,110 @@
-{
-  "name": "@j0hanz/fetch-url-mcp",
-  "version": "1.13.0",
-  "mcpName": "io.github.j0hanz/fetch-url-mcp",
-  "description": "An MCP server that fetches web pages and converts them to clean, 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",
-    "model-context-protocol",
-    "web-fetching",
-    "content-extraction",
-    "readability",
-    "markdown",
-    "html-to-markdown",
-    "web-scraper",
-    "llm-context",
-    "ai-tools",
-    "fetch-url-mcp",
-    "typescript",
-    "nodejs",
-    "stdio",
-    "streamable-http",
-    "structured-output",
-    "metadata-extraction",
-    "url-rewriting",
-    "worker-threads",
-    "content-cleanup"
-  ],
-  "scripts": {
-    "clean": "node scripts/tasks.mjs clean",
-    "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:src": "node node_modules/typescript/bin/tsc -p tsconfig.json --noEmit",
-    "type-check:tests": "node node_modules/typescript/bin/tsc -p tsconfig.test.json --noEmit",
-    "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:tests": "eslint __tests__",
-    "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",
-    "prepublishOnly": "npm run lint && npm run type-check && npm run build"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29",
-    "@mozilla/readability": "^0.6.0",
-    "linkedom": "^0.18.12",
-    "node-html-markdown": "^2.0.0",
-    "undici": "^7.24.7",
-    "zod": "^4.3.6"
-  },
-  "devDependencies": {
-    "@eslint/js": "^10.0.1",
-    "@trivago/prettier-plugin-sort-imports": "^6.0.2",
-    "@types/node": "^24",
-    "eslint": "^10.2.0",
-    "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-de-morgan": "^2.1.1",
-    "eslint-plugin-depend": "^1.5.0",
-    "eslint-plugin-sonarjs": "^4.0.2",
-    "eslint-plugin-unicorn": "^64.0.0",
-    "eslint-plugin-unused-imports": "^4.4.1",
-    "knip": "^6.3.0",
-    "prettier": "^3.8.1",
-    "tsx": "^4.21.0",
-    "typescript": "^6.0.2",
-    "typescript-eslint": "^8.58.0"
-  },
-  "engines": {
-    "node": ">=24"
-  }
-}
+{
+  "name": "@j0hanz/fetch-url-mcp",
+  "version": "2.0.1",
+  "mcpName": "io.github.j0hanz/fetch-url-mcp",
+  "description": "An MCP server that fetches web pages and converts them to clean, 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",
+    "model-context-protocol",
+    "web-fetching",
+    "content-extraction",
+    "readability",
+    "markdown",
+    "html-to-markdown",
+    "web-scraper",
+    "llm-context",
+    "ai-tools",
+    "fetch-url-mcp",
+    "typescript",
+    "nodejs",
+    "stdio",
+    "streamable-http",
+    "structured-output",
+    "metadata-extraction",
+    "url-rewriting",
+    "worker-threads",
+    "content-cleanup"
+  ],
+  "scripts": {
+    "clean": "node scripts/tasks.mjs clean",
+    "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:src": "node node_modules/typescript/bin/tsc -p tsconfig.json --noEmit",
+    "type-check:tests": "node node_modules/typescript/bin/tsc -p tsconfig.test.json --noEmit",
+    "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:tests": "eslint __tests__",
+    "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",
+    "prepublishOnly": "npm run lint && npm run type-check && npm run build"
+  },
+  "dependencies": {
+    "@cfworker/json-schema": "^4.1.1",
+    "@modelcontextprotocol/node": "^2.0.0-alpha.2",
+    "@modelcontextprotocol/server": "^2.0.0-alpha.2",
+    "@mozilla/readability": "^0.6.0",
+    "linkedom": "^0.18.12",
+    "node-html-markdown": "^2.0.0",
+    "undici": "^8.0.2",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@trivago/prettier-plugin-sort-imports": "^6.0.2",
+    "@types/node": "^24",
+    "eslint": "^10.2.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-de-morgan": "^2.1.1",
+    "eslint-plugin-depend": "^1.5.0",
+    "eslint-plugin-sonarjs": "^4.0.2",
+    "eslint-plugin-unicorn": "^64.0.0",
+    "eslint-plugin-unused-imports": "^4.4.1",
+    "knip": "^6.3.1",
+    "prettier": "^3.8.2",
+    "tsx": "^4.21.0",
+    "typescript": "^6.0.2",
+    "typescript-eslint": "^8.58.1"
+  },
+  "engines": {
+    "node": ">=24"
+  }
+}