fetch

Instructions

Implementation Reference

• index.ts:37-42 (schema)

  Input schema (Zod) for the 'fetch' tool defining parameters: url, maxLength, startIndex, raw.

  const FetchArgsSchema = z.object({
  	url: z.string().url(),
  	maxLength: z.number().positive().max(1000000).default(20000),
  	startIndex: z.number().min(0).default(0),
  	raw: z.boolean().default(false),
  })

• index.ts:366-374 (registration)

  Registration of the 'fetch' tool in the tools/list response, providing name, description, and JSON schema derived from FetchArgsSchema.

  const tools = [
  	{
  		name: "fetch",
  		description:
  			"Retrieves URLs from the Internet and extracts their content as markdown. If images are found, they are merged vertically (max 6 images per group, max height 8000px, max size 30MB per group) and copied to the clipboard of the user's host machine. You will need to paste (Cmd+V) to insert the images.",
  		inputSchema: zodToJsonSchema(FetchArgsSchema),
  	},
  ]
  return { tools }

• index.ts:378-443 (handler)

  The tools/call request handler implementing the 'fetch' tool: validates input with FetchArgsSchema, invokes fetchUrl, handles truncation based on maxLength and startIndex, lists image URLs, and returns formatted text content or error.

  server.setRequestHandler(
  	CallToolSchema,
  	async (
  		request: {
  			method: "tools/call"
  			params: { name: string; arguments?: Record<string, unknown> }
  		},
  		extra: RequestHandlerExtra,
  	) => {
  		try {
  			const { name, arguments: args } = request.params
  
  			if (name !== "fetch") {
  				throw new Error(`Unknown tool: ${name}`)
  			}
  
  			const parsed = FetchArgsSchema.safeParse(args)
  			if (!parsed.success) {
  				throw new Error(`Invalid arguments: ${parsed.error}`)
  			}
  
  			const { content, prefix, imageUrls } = await fetchUrl(
  				parsed.data.url,
  				DEFAULT_USER_AGENT_AUTONOMOUS,
  				parsed.data.raw,
  			)
  
  			let finalContent = content
  			if (finalContent.length > parsed.data.maxLength) {
  				finalContent = finalContent.slice(
  					parsed.data.startIndex,
  					parsed.data.startIndex + parsed.data.maxLength,
  				)
  				finalContent += `\n\n<e>Content truncated. Call the fetch tool with a start_index of ${
  					parsed.data.startIndex + parsed.data.maxLength
  				} to get more content.</e>`
  			}
  
  			let imagesSection = ""
  			if (imageUrls && imageUrls.length > 0) {
  				imagesSection =
  					"\n\nImages found in article:\n" +
  					imageUrls.map((url) => `- ${url}`).join("\n")
  			}
  
  			return {
  				content: [
  					{
  						type: "text",
  						text: `${prefix}Contents of ${parsed.data.url}:\n${finalContent}${imagesSection}`,
  					},
  				],
  			}
  		} catch (error) {
  			return {
  				content: [
  					{
  						type: "text",
  						text: `Error: ${error instanceof Error ? error.message : String(error)}`,
  					},
  				],
  				isError: true,
  			}
  		}
  	},
  )

• index.ts:286-344 (handler)

  Core logic function for fetching URL content, parsing HTML to markdown with image extraction and clipboard copying using internal helpers.

  async function fetchUrl(
  	url: string,
  	userAgent: string,
  	forceRaw = false,
  ): Promise<FetchResult> {
  	const response = await fetch(url, {
  		headers: { "User-Agent": userAgent },
  	})
  
  	if (!response.ok) {
  		throw new Error(`Failed to fetch ${url} - status code ${response.status}`)
  	}
  
  	const contentType = response.headers.get("content-type") || ""
  	const text = await response.text()
  	const isHtml =
  		text.toLowerCase().includes("<html") || contentType.includes("text/html")
  
  	if (isHtml && !forceRaw) {
  		const result = extractContentFromHtml(text, url)
  		if (typeof result === "string") {
  			return {
  				content: result,
  				prefix: "",
  			}
  		}
  
  		const { markdown, images } = result
  		const fetchedImages = await fetchImages(images)
  		const imageUrls = fetchedImages.map((img) => img.src)
  
  		if (fetchedImages.length > 0) {
  			try {
  				await addImagesToClipboard(fetchedImages)
  				return {
  					content: markdown,
  					prefix: `Found and processed ${fetchedImages.length} images. Images have been merged vertically (max 6 images per group) and copied to your clipboard. Please paste (Cmd+V) to combine with the retrieved content.\n`,
  					imageUrls,
  				}
  			} catch (err) {
  				return {
  					content: markdown,
  					prefix: `Found ${fetchedImages.length} images but failed to copy them to the clipboard.\nError: ${err instanceof Error ? err.message : String(err)}\n`,
  					imageUrls,
  				}
  			}
  		}
  		return {
  			content: markdown,
  			prefix: "",
  			imageUrls,
  		}
  	}
  
  	return {
  		content: text,
  		prefix: `Content type ${contentType} cannot be simplified to markdown, but here is the raw content:\n`,
  	}
  }