Jina AI Remote MCP Server

Instructions

Implementation Reference

• src/tools/jina-tools.ts:92-164 (handler)

  Full implementation of the capture_screenshot_url tool handler, including input schema validation with Zod, API call to r.jina.ai for screenshot generation, optional image downloading/processing with downloadImages utility, and error handling. This is the core execution logic.

  server.tool(
  	"capture_screenshot_url",
  	"Capture high-quality screenshots of web pages in base64 encoded JPEG format. Use this tool when you need to visually inspect a website, take a snapshot for analysis, or show users what a webpage looks like.",
  	{
  		url: z.string().url().describe("The complete HTTP/HTTPS URL of the webpage to capture (e.g., 'https://example.com')"),
  		firstScreenOnly: z.boolean().default(false).describe("Set to true for a single screen capture (faster), false for full page capture including content below the fold"),
  		return_url: z.boolean().default(false).describe("Set to true to return screenshot URLs instead of downloading images as base64")
  	},
  	async ({ url, firstScreenOnly, return_url }: { url: string; firstScreenOnly: boolean; return_url: boolean }) => {
  		try {
  			const props = getProps();
  			const headers: Record<string, string> = {
  				'Accept': 'application/json',
  				'Content-Type': 'application/json',
  				'X-Return-Format': firstScreenOnly === true ? 'screenshot' : 'pageshot',
  			};
  
  			// Add Authorization header if bearer token is available
  			if (props.bearerToken) {
  				headers['Authorization'] = `Bearer ${props.bearerToken}`;
  			}
  
  			const response = await fetch('https://r.jina.ai/', {
  				method: 'POST',
  				headers,
  				body: JSON.stringify({ url }),
  			});
  
  			if (!response.ok) {
  				return handleApiError(response, "Screenshot capture");
  			}
  
  			const data = await response.json() as any;
  
  			// Get the screenshot URL from the response
  			const imageUrl = data.data.screenshotUrl || data.data.pageshotUrl;
  			if (!imageUrl) {
  				throw new Error("No screenshot URL received from API");
  			}
  
  			// Prepare response content - always return as list structure for consistency
  			const contentItems: Array<{ type: 'text'; text: string } | { type: 'image'; data: string; mimeType: string }> = [];
  
  			if (return_url) {
  				// Return the URL as text
  				contentItems.push({
  					type: "text" as const,
  					text: imageUrl,
  				});
  			} else {
  				// Download and process the image (resize to max 800px, convert to JPEG)
  				const processedResults = await downloadImages(imageUrl, 1, 10000);
  				const processedResult = processedResults[0];
  
  				if (!processedResult.success) {
  					throw new Error(`Failed to process screenshot: ${processedResult.error}`);
  				}
  
  				contentItems.push({
  					type: "image" as const,
  					data: processedResult.data!,
  					mimeType: "image/jpeg",
  				});
  			}
  
  			return {
  				content: contentItems,
  			};
  		} catch (error) {
  			return createErrorResponse(`Error: ${error instanceof Error ? error.message : String(error)}`);
  		}
  	},
  );

• src/tools/jina-tools.ts:95-99 (schema)

  Zod schema for input parameters of capture_screenshot_url tool: url (required URL), firstScreenOnly (boolean, default false for full page), return_url (boolean, default false for base64 image).

  {
  	url: z.string().url().describe("The complete HTTP/HTTPS URL of the webpage to capture (e.g., 'https://example.com')"),
  	firstScreenOnly: z.boolean().default(false).describe("Set to true for a single screen capture (faster), false for full page capture including content below the fold"),
  	return_url: z.boolean().default(false).describe("Set to true to return screenshot URLs instead of downloading images as base64")
  },

• src/index.ts:21-21 (registration)

  Top-level registration of all Jina tools, including capture_screenshot_url, by calling registerJinaTools on the MCP server instance.

  registerJinaTools(this.server, () => this.props);