superFetch MCP Server

Instructions

Implementation Reference

• src/tools/fetch-url.ts:450-458 (handler)

  Main tool handler function - fetchUrlToolHandler is the primary entry point that wraps executeFetch with error handling and logging

  export async function fetchUrlToolHandler(
    input: FetchUrlInput,
    extra?: ToolHandlerExtra
  ): Promise<ToolResponseBase> {
    return executeFetch(input, extra).catch((error: unknown) => {
      logError('fetch-url tool error', toError(error));
      return handleToolError(error, input.url, 'Failed to fetch URL');
    });
  }

• src/tools/fetch-url.ts:411-448 (handler)

  Core execution logic - executeFetch function orchestrates the URL fetching, progress reporting, and response building

  async function executeFetch(
    input: FetchUrlInput,
    extra?: ToolHandlerExtra
  ): Promise<ToolResponseBase> {
    const { url } = input;
    const signal = buildToolAbortSignal(extra?.signal);
    const progress = createProgressReporter(extra);
  
    const contextStr = getUrlContext(url);
    progress.report(0, `fetch-url: ${contextStr} [starting]`);
    logDebug('Fetching URL', { url });
  
    try {
      progress.report(1, `fetch-url: ${contextStr} [fetching HTML]`);
      const { pipeline, inlineResult } = await fetchPipeline(
        url,
        signal,
        progress,
        input.skipNoiseRemoval,
        input.forceRefresh,
        input.maxInlineChars
      );
  
      if (pipeline.fromCache) {
        progress.report(3, `fetch-url: ${contextStr} [loaded from cache]`);
      }
  
      progress.report(4, `fetch-url: ${contextStr} • completed`);
      return buildResponse(pipeline, inlineResult, url);
    } catch (error) {
      const isAbort = isAbortError(error);
      progress.report(
        4,
        `fetch-url: ${contextStr} • ${isAbort ? 'cancelled' : 'failed'}`
      );
      throw error;
    }
  }

• src/schemas/inputs.ts:5-28 (schema)

  Input validation schema - defines the URL, skipNoiseRemoval, forceRefresh, and maxInlineChars parameters for fetch-url tool

  export const fetchUrlInputSchema = z.strictObject({
    url: z
      .url({ protocol: /^https?$/i })
      .min(1)
      .max(config.constants.maxUrlLength)
      .describe(`Target URL. Max ${config.constants.maxUrlLength} chars.`),
    skipNoiseRemoval: z
      .boolean()
      .optional()
      .describe('Preserve navigation/footers (disable noise filtering).'),
    forceRefresh: z
      .boolean()
      .optional()
      .describe('Bypass cache and fetch fresh content.'),
    maxInlineChars: z
      .number()
      .int()
      .min(0)
      .max(config.constants.maxHtmlSize)
      .optional()
      .describe(
        `Inline markdown limit (0-${config.constants.maxHtmlSize}, 0=unlimited). Lower of this or global limit applies.`
      ),
  });

• src/schemas/outputs.ts:5-80 (schema)

  Output validation schema - defines the structure of the response including url, markdown, metadata, cacheResourceUri, and truncation fields

  export const fetchUrlOutputSchema = z.strictObject({
    url: z
      .string()
      .min(1)
      .max(config.constants.maxUrlLength)
      .describe('Fetched URL.'),
    inputUrl: z
      .string()
      .max(config.constants.maxUrlLength)
      .optional()
      .describe('Original requested URL.'),
    resolvedUrl: z
      .string()
      .max(config.constants.maxUrlLength)
      .optional()
      .describe('Final URL after raw-content transformations.'),
    finalUrl: z
      .string()
      .max(config.constants.maxUrlLength)
      .optional()
      .describe('Final URL after HTTP redirects.'),
    cacheResourceUri: z
      .string()
      .max(config.constants.maxUrlLength)
      .optional()
      .describe('URI for resources/read to get full markdown.'),
    title: z.string().max(512).optional().describe('Page title.'),
    metadata: z
      .strictObject({
        title: z.string().max(512).optional().describe('Detected page title.'),
        description: z
          .string()
          .max(2048)
          .optional()
          .describe('Detected page description.'),
        author: z.string().max(512).optional().describe('Detected page author.'),
        image: z
          .string()
          .max(config.constants.maxUrlLength)
          .optional()
          .describe('Detected page preview image URL.'),
        favicon: z
          .string()
          .max(config.constants.maxUrlLength)
          .optional()
          .describe('Detected page favicon URL.'),
        publishedAt: z
          .string()
          .max(64)
          .optional()
          .describe('Detected publication date.'),
        modifiedAt: z
          .string()
          .max(64)
          .optional()
          .describe('Detected last modified date.'),
      })
      .optional()
      .describe('Extracted page metadata.'),
    markdown: (config.constants.maxInlineContentChars > 0
      ? z.string().max(config.constants.maxInlineContentChars)
      : z.string()
    )
      .optional()
      .describe('Extracted Markdown. May be truncated (check truncated field).'),
    fromCache: z.boolean().optional().describe('True if served from cache.'),
    fetchedAt: z.string().max(64).optional().describe('ISO timestamp of fetch.'),
    contentSize: z
      .number()
      .int()
      .min(0)
      .max(config.constants.maxHtmlSize * 4)
      .optional()
      .describe('Full markdown size before truncation.'),
    truncated: z.boolean().optional().describe('True if markdown was truncated.'),
  });

• src/tools/fetch-url.ts:571-611 (registration)

  Tool registration - registerTools function registers fetch-url with the MCP server, including input/output schemas and handler

  export function registerTools(server: McpServer): void {
    if (!config.tools.enabled.includes(FETCH_URL_TOOL_NAME)) {
      unregisterTaskCapableTool(FETCH_URL_TOOL_NAME);
      return;
    }
  
    registerTaskCapableTool({
      name: FETCH_URL_TOOL_NAME,
      parseArguments: (args) => {
        const parsed = fetchUrlInputSchema.safeParse(args);
        if (!parsed.success) {
          throw new McpError(
            ErrorCode.InvalidParams,
            'Invalid arguments for fetch-url'
          );
        }
        return parsed.data;
      },
      execute: fetchUrlToolHandler,
    });
  
    const registeredTool = 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,
        execution: TOOL_DEFINITION.execution,
        icons: [TOOL_ICON],
      } as { inputSchema: typeof fetchUrlInputSchema } & Record<string, unknown>,
      withRequestContextIfMissing(TOOL_DEFINITION.handler)
    );
    // SDK typing gap workaround: preserve runtime `execution` metadata until the
    // registered tool type includes this field.
    applyRegisteredToolExecutionMetadata(
      registeredTool,
      TOOL_DEFINITION.execution
    );
  }