@j0hanz/fetch-url-mcp 1.4.0 → 1.5.0

package/dist/lib/mcp-tools.d.ts

@@ -0,0 +1,28 @@
+import { type CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+export type JsonRpcId = string | number | null;
+interface McpRequestParams {
+    _meta?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+interface McpRequestBody {
+    jsonrpc: '2.0';
+    method: string;
+    id?: JsonRpcId;
+    params?: McpRequestParams;
+}
+export declare function isJsonRpcBatchRequest(body: unknown): boolean;
+export declare function isMcpRequestBody(body: unknown): body is McpRequestBody;
+export declare function acceptsEventStream(header: string | null | undefined): boolean;
+export declare function acceptsJsonAndEventStream(header: string | null | undefined): boolean;
+type ToolErrorResponse = CallToolResult & {
+    isError: true;
+};
+export declare function createToolErrorResponse(message: string, url: string, extra?: {
+    code?: string;
+    statusCode?: number;
+    details?: Record<string, unknown>;
+}): ToolErrorResponse;
+export declare function handleToolError(error: unknown, url: string, fallbackMessage?: string): ToolErrorResponse;
+export { registerServerLifecycleCleanup, registerTaskHandlers, cancelTasksForOwner, abortAllTaskExecutions, } from './task-handlers.js';
+export { readString, readNestedRecord, withSignal, TRUNCATION_MARKER, type InlineContentResult, appendTruncationMarker, type PipelineResult, executeFetchPipeline, type MarkdownPipelineResult, parseCachedMarkdownResult, markdownTransform, serializeMarkdownResult, performSharedFetch, } from './fetch-pipeline.js';
+export { type ProgressNotificationParams, type ProgressNotification, type ToolHandlerExtra, type ProgressReporter, createProgressReporter, } from './progress.js';

package/dist/lib/mcp-tools.js

@@ -0,0 +1,107 @@
+import {} from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod';
+import { FetchError, isAbortError, isSystemError } from './utils.js';
+const paramsSchema = z.looseObject({});
+const mcpRequestSchema = z.strictObject({
+    jsonrpc: z.literal('2.0'),
+    method: z.string().min(1),
+    id: z.union([z.string(), z.number(), z.null()]).optional(),
+    params: paramsSchema.optional(),
+});
+export function isJsonRpcBatchRequest(body) {
+    return Array.isArray(body);
+}
+export function isMcpRequestBody(body) {
+    return mcpRequestSchema.safeParse(body).success;
+}
+function parseAcceptMediaTypes(header) {
+    if (!header)
+        return [];
+    return header
+        .split(',')
+        .map((value) => extractAcceptMediaType(value.trim()))
+        .filter((value) => value.length > 0);
+}
+function extractAcceptMediaType(value) {
+    return value.split(';', 1)[0]?.trim().toLowerCase() ?? '';
+}
+export function acceptsEventStream(header) {
+    const mediaTypes = parseAcceptMediaTypes(header);
+    return mediaTypes.some((mediaType) => mediaType === 'text/event-stream');
+}
+function hasAcceptedMediaType(mediaTypes, exact, wildcardPrefix) {
+    return mediaTypes.some((mediaType) => typeof mediaType === 'string' &&
+        mediaType.length > 0 &&
+        (mediaType === '*/*' ||
+            mediaType === exact ||
+            mediaType === wildcardPrefix));
+}
+export function acceptsJsonAndEventStream(header) {
+    const mediaTypes = parseAcceptMediaTypes(header);
+    const acceptsJson = hasAcceptedMediaType(mediaTypes, 'application/json', 'application/*');
+    if (!acceptsJson)
+        return false;
+    return hasAcceptedMediaType(mediaTypes, 'text/event-stream', 'text/*');
+}
+export function createToolErrorResponse(message, url, extra) {
+    const errorContent = {
+        error: message,
+        ...(extra?.code ? { code: extra.code } : {}),
+        url,
+        ...(extra?.statusCode !== undefined
+            ? { statusCode: extra.statusCode }
+            : {}),
+        ...(extra?.details ? { details: extra.details } : {}),
+    };
+    return {
+        content: [{ type: 'text', text: JSON.stringify(errorContent) }],
+        isError: true,
+    };
+}
+function isValidationError(error) {
+    return (error instanceof Error &&
+        isSystemError(error) &&
+        error.code === 'VALIDATION_ERROR');
+}
+function isHandledToolError(error) {
+    return error instanceof FetchError || isValidationError(error);
+}
+function resolveToolErrorMessage(error, fallbackMessage) {
+    if (isHandledToolError(error)) {
+        return error.message;
+    }
+    if (error instanceof Error) {
+        return `${fallbackMessage}: ${error.message}`;
+    }
+    return `${fallbackMessage}: Unknown error`;
+}
+function resolveToolErrorCode(error) {
+    if (error instanceof FetchError)
+        return error.code;
+    if (isValidationError(error))
+        return 'VALIDATION_ERROR';
+    if (isAbortError(error))
+        return 'ABORTED';
+    return 'FETCH_ERROR';
+}
+export function handleToolError(error, url, fallbackMessage = 'Operation failed') {
+    const message = resolveToolErrorMessage(error, fallbackMessage);
+    const code = resolveToolErrorCode(error);
+    if (error instanceof FetchError) {
+        return createToolErrorResponse(message, url, {
+            code,
+            statusCode: error.statusCode,
+            details: error.details,
+        });
+    }
+    return createToolErrorResponse(message, url, { code });
+}
+/* -------------------------------------------------------------------------------------------------
+ * Re-exports from split modules
+ *
+ * Preserves backward compatibility — consumers import from 'lib/mcp-tools.js'
+ * without changes. Direct imports from the sub-modules are preferred for new code.
+ * ------------------------------------------------------------------------------------------------- */
+export { registerServerLifecycleCleanup, registerTaskHandlers, cancelTasksForOwner, abortAllTaskExecutions, } from './task-handlers.js';
+export { readString, readNestedRecord, withSignal, TRUNCATION_MARKER, appendTruncationMarker, executeFetchPipeline, parseCachedMarkdownResult, markdownTransform, serializeMarkdownResult, performSharedFetch, } from './fetch-pipeline.js';
+export { createProgressReporter, } from './progress.js';

package/dist/lib/{tool-progress.d.ts → progress.d.ts}

@@ -28,4 +28,3 @@ export interface ProgressReporter {
 }
 export declare function createProgressReporter(extra?: ToolHandlerExtra): ProgressReporter;
 export {};
-//# sourceMappingURL=tool-progress.d.ts.map

package/dist/lib/{tool-progress.js → progress.js}

@@ -1,14 +1,7 @@
-import { getErrorMessage } from './errors.js';
-import { logWarn } from './observability.js';
-import { isObject } from './type-guards.js';
-/* -------------------------------------------------------------------------------------------------
- * Constants
- * ------------------------------------------------------------------------------------------------- */
+import { logWarn } from './core.js';
+import { getErrorMessage, isObject } from './utils.js';
 const FETCH_PROGRESS_TOTAL = 4;
 const PROGRESS_NOTIFICATION_TIMEOUT_MS = 5000;
-/* -------------------------------------------------------------------------------------------------
- * Helpers
- * ------------------------------------------------------------------------------------------------- */
 function resolveRelatedTaskMeta(meta) {
     if (!meta)
         return undefined;
@@ -18,9 +11,6 @@ function resolveRelatedTaskMeta(meta) {
     const { taskId } = related;
     return typeof taskId === 'string' ? { taskId } : undefined;
 }
-/* -------------------------------------------------------------------------------------------------
- * Progress reporter
- * ------------------------------------------------------------------------------------------------- */
 class ToolProgressReporter {
     token;
     sendNotification;
@@ -45,6 +35,12 @@ class ToolProgressReporter {
         }
         return new ToolProgressReporter(token, sendNotification, relatedTaskMeta, onProgress);
     }
+    /**
+     * Report progress toward completion. Steps are monotonic (never decrease)
+     * and may be skipped under normal conditions (e.g., fast responses skip
+     * intermediate steps). Clients should treat progress as "at least this far"
+     * rather than expecting every step to fire sequentially.
+     */
     report(progress, message) {
         if (this.isTerminal)
             return;
@@ -126,4 +122,3 @@ class ToolProgressReporter {
 export function createProgressReporter(extra) {
     return ToolProgressReporter.create(extra);
 }
-//# sourceMappingURL=tool-progress.js.map

package/dist/lib/task-handlers.d.ts

@@ -0,0 +1,5 @@
+import { type McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+type CleanupCallback = () => void;
+export declare function registerServerLifecycleCleanup(server: McpServer, callback: CleanupCallback): void;
+export { cancelTasksForOwner, abortAllTaskExecutions, } from '../tasks/execution.js';
+export declare function registerTaskHandlers(server: McpServer): void;

package/dist/lib/{mcp.js → task-handlers.js}

@@ -1,15 +1,59 @@
-import { CallToolRequestSchema, ErrorCode, McpError, } from '@modelcontextprotocol/sdk/types.js';
 import { randomUUID } from 'node:crypto';
+import {} from '@modelcontextprotocol/sdk/server/mcp.js';
+import { CallToolRequestSchema, ErrorCode, McpError, } from '@modelcontextprotocol/sdk/types.js';
 import { z } from 'zod';
 import { abortTaskExecution, emitTaskStatusNotification, handleToolCallRequest, throwTaskNotFound, toTaskSummary, withRelatedTaskMeta, } from '../tasks/execution.js';
 import { taskManager } from '../tasks/manager.js';
 import { isServerResult, parseHandlerExtra, resolveTaskOwnerKey, resolveToolCallContext, } from '../tasks/owner.js';
 import { hasTaskCapableTool } from '../tasks/tool-registry.js';
-import { runWithRequestContext } from './observability.js';
-// Re-export public API so existing consumers (tests, other modules) keep working.
+import { logWarn, runWithRequestContext } from './core.js';
+const patchedCleanupServers = new WeakSet();
+const serverCleanupCallbacks = new WeakMap();
+function getServerCleanupCallbackSet(server) {
+    let callbacks = serverCleanupCallbacks.get(server);
+    if (!callbacks) {
+        callbacks = new Set();
+        serverCleanupCallbacks.set(server, callbacks);
+    }
+    return callbacks;
+}
+function drainServerCleanupCallbacks(server) {
+    const callbacks = serverCleanupCallbacks.get(server);
+    if (!callbacks || callbacks.size === 0)
+        return;
+    const pending = [...callbacks];
+    callbacks.clear();
+    for (const callback of pending) {
+        try {
+            callback();
+        }
+        catch (error) {
+            logWarn('Server cleanup callback failed', { error });
+        }
+    }
+}
+function ensureServerCleanupHooks(server) {
+    if (patchedCleanupServers.has(server))
+        return;
+    patchedCleanupServers.add(server);
+    const originalOnClose = server.server.onclose;
+    server.server.onclose = () => {
+        drainServerCleanupCallbacks(server);
+        originalOnClose?.();
+    };
+    const originalClose = server.close.bind(server);
+    server.close = async () => {
+        drainServerCleanupCallbacks(server);
+        await originalClose();
+    };
+}
+export function registerServerLifecycleCleanup(server, callback) {
+    ensureServerCleanupHooks(server);
+    getServerCleanupCallbackSet(server).add(callback);
+}
 export { cancelTasksForOwner, abortAllTaskExecutions, } from '../tasks/execution.js';
 /* -------------------------------------------------------------------------------------------------
- * Tasks API schemas
+ * Task handler schemas and registration
  * ------------------------------------------------------------------------------------------------- */
 const TaskGetSchema = z
     .object({
@@ -40,9 +84,6 @@ const TaskResultSchema = z
     params: z.object({ taskId: z.string() }).loose(),
 })
     .loose();
-/* -------------------------------------------------------------------------------------------------
- * Tool call interception (tools/call) with task support
- * ------------------------------------------------------------------------------------------------- */
 const MIN_TASK_TTL_MS = 1_000;
 const MAX_TASK_TTL_MS = 86_400_000;
 const ExtendedCallToolRequestSchema = z
@@ -81,7 +122,11 @@ function parseExtendedCallToolRequest(request) {
     const parsed = ExtendedCallToolRequestSchema.safeParse(request);
     if (parsed.success)
         return parsed.data;
-    throw new McpError(ErrorCode.InvalidParams, 'Invalid tool request');
+    const flat = z.flattenError(parsed.error);
+    const details = Object.entries(flat.fieldErrors)
+        .map(([k, v]) => `${k}: ${(v ?? []).join(', ')}`)
+        .join('; ') || flat.formErrors.join('; ');
+    throw new McpError(ErrorCode.InvalidParams, `Invalid tool request params: ${details}`);
 }
 function resolveOwnerScopedExtra(extra) {
     const parsedExtra = parseHandlerExtra(extra);
@@ -97,11 +142,11 @@ function getSdkCallToolHandler(server) {
     const handler = maybeHandlers.get('tools/call');
     return typeof handler === 'function' ? handler : null;
 }
-/* -------------------------------------------------------------------------------------------------
- * Register handlers
- * ------------------------------------------------------------------------------------------------- */
 export function registerTaskHandlers(server) {
     const sdkCallToolHandler = getSdkCallToolHandler(server);
+    if (!sdkCallToolHandler) {
+        logWarn('Task call interception disabled: SDK tools/call handler unavailable; task-capable tools require MCP SDK compatibility update', { sdkVersion: 'unknown' });
+    }
     if (sdkCallToolHandler) {
         server.server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
             const parsedExtra = parseHandlerExtra(extra);
@@ -192,4 +237,3 @@ export function registerTaskHandlers(server) {
         return toTaskSummary(task);
     });
 }
-//# sourceMappingURL=mcp.js.map

package/dist/lib/url.d.ts

@@ -0,0 +1,70 @@
+import { BlockList } from 'node:net';
+import { type config } from './core.js';
+export declare class SafeDnsResolver {
+    private readonly ipBlocker;
+    private readonly security;
+    private readonly blockedHostSuffixes;
+    constructor(ipBlocker: IpBlocker, security: SecurityConfig, blockedHostSuffixes: readonly string[]);
+    resolveAndValidate(hostname: string, signal?: AbortSignal): Promise<string>;
+    private isBlockedHostname;
+    private assertNoBlockedCname;
+    private resolveCname;
+}
+type HostnamePreflight = (url: string, signal?: AbortSignal) => Promise<string>;
+export declare function createDnsPreflight(dnsResolver: SafeDnsResolver): HostnamePreflight;
+export declare function normalizeHost(value: string): string | null;
+type IpFamily = 'ipv4' | 'ipv6';
+export declare function createDefaultBlockList(): BlockList;
+export declare function normalizeIpForBlockList(input: string): {
+    ip: string;
+    family: IpFamily;
+} | null;
+export interface TransformResult {
+    readonly url: string;
+    readonly transformed: boolean;
+    readonly platform?: string;
+}
+export declare class RawUrlTransformer {
+    private readonly logger;
+    constructor(logger: Logger);
+    transformToRawUrl(url: string): TransformResult;
+    isRawTextContentUrl(urlString: string): boolean;
+    private isRawUrl;
+    private splitParams;
+    private tryTransformWithUrl;
+    private transformGithubBlob;
+    private transformGithubGist;
+    private transformGitLab;
+    private transformBitbucket;
+}
+export interface Logger {
+    debug(message: string, data?: Record<string, unknown>): void;
+    warn(message: string, data?: Record<string, unknown>): void;
+    error(message: string, data?: Record<string, unknown>): void;
+}
+export declare const VALIDATION_ERROR_CODE = "VALIDATION_ERROR";
+export declare const BLOCKED_HOST_SUFFIXES: readonly string[];
+type SecurityConfig = typeof config.security;
+export declare class IpBlocker {
+    private readonly security;
+    private readonly blockList;
+    constructor(security: SecurityConfig);
+    isBlockedIp(candidate: string): boolean;
+}
+type ConstantsConfig = typeof config.constants;
+export declare class UrlNormalizer {
+    private readonly constants;
+    private readonly security;
+    private readonly ipBlocker;
+    private readonly blockedHostSuffixes;
+    constructor(constants: ConstantsConfig, security: SecurityConfig, ipBlocker: IpBlocker, blockedHostSuffixes: readonly string[]);
+    normalize(urlString: string): {
+        normalizedUrl: string;
+        hostname: string;
+    };
+    validateAndNormalize(urlString: string): string;
+    private requireTrimmedUrl;
+    private normalizeHostname;
+    private assertHostnameAllowed;
+}
+export {};