Jina AI Remote MCP Server

Instructions

Implementation Reference

• src/tools/jina-tools.ts:148-270 (handler)

  The function that executes the read_url tool logic: normalizes the input URL, constructs headers based on options, fetches content from https://r.jina.ai/, handles errors, extracts structured data (title, links, images if requested), and returns markdown content and YAML-structured metadata.
  async ({ url, withAllLinks, withAllImages }: { url: string; withAllLinks?: boolean; withAllImages?: boolean }) => { try { const props = getProps(); // Normalize the URL first const normalizedUrl = normalizeUrl(url); if (!normalizedUrl) { return { content: [ { type: "text" as const, text: "Error: Invalid or unsupported URL", }, ], isError: true, }; } const headers: Record<string, string> = { 'Accept': 'application/json', 'Content-Type': 'application/json', 'X-Md-Link-Style': 'discarded', }; // Add Authorization header if bearer token is available if (props.bearerToken) { headers['Authorization'] = `Bearer ${props.bearerToken}`; } if (withAllLinks) { headers['X-With-Links-Summary'] = 'all'; } if (withAllImages) { headers['X-With-Images-Summary'] = 'true'; } else { headers['X-Retain-Images'] = 'none'; } const response = await fetch('https://r.jina.ai/', { method: 'POST', headers, body: JSON.stringify({ url: normalizedUrl }), }); if (!response.ok) { return handleApiError(response, "URL conversion"); } const data = await response.json() as any; if (!data.data) { return { content: [ { type: "text" as const, text: "Error: Invalid response data from r.jina.ai", }, ], isError: true, }; } const responseContent = []; // Add structured data as JSON if requested via parameters const structuredData: any = {}; if (data.data.url) { structuredData.url = data.data.url; } if (data.data.title) { structuredData.title = data.data.title; } if (withAllLinks && data.data.links) { // Transform links from [anchorText, url] arrays to {anchorText, url} objects structuredData.links = data.data.links.map((link: [string, string]) => ({ anchorText: link[0], url: link[1] })); } if (withAllImages && data.data.images) { structuredData.images = data.data.images; } // Add structured data if any exists if (Object.keys(structuredData).length > 0) { responseContent.push({ type: "text" as const, text: yamlStringify(structuredData), }); } // Add main content if (data.data.content) { responseContent.push({ type: "text" as const, text: String(data.data.content), }); } return { content: responseContent.length > 0 ? responseContent : [ { type: "text" as const, text: "No content available", }, ], }; } catch (error) { return { content: [ { type: "text" as const, text: `Error: ${error instanceof Error ? error.message : String(error)}`, }, ], isError: true, }; }
• src/tools/jina-tools.ts:143-147 (schema)

  Input schema using Zod for validating tool parameters: url (required string URL), optional booleans for including all links and images.
  { url: z.string().url().describe("The complete URL of the webpage or PDF file to read and convert (e.g., 'https://example.com/article')"), withAllLinks: z.boolean().optional().describe("Set to true to extract and return all hyperlinks found on the page as structured data"), withAllImages: z.boolean().optional().describe("Set to true to extract and return all images found on the page as structured data") },
• src/index.ts:19-22 (registration)

  In the MCP agent's init method, calls registerJinaTools to register all tools, including read_url, on the MCP server.
  async init() { // Register all Jina AI tools registerJinaTools(this.server, () => this.props); }
• src/utils/url-normalizer.ts:2-71 (helper)

  Supporting utility normalizeUrl cleans and standardizes input URLs by removing tracking params, utm, sessions, anchors, www prefix, etc., before sending to the API.
  export function normalizeUrl(urlString: string, options = { removeAnchors: true, removeSessionIDs: true, removeUTMParams: true, removeTrackingParams: true, removeXAnalytics: true }) { try { urlString = urlString.replace(/\s+/g, '').trim(); if (!urlString?.trim()) { throw new Error('Empty URL'); } // Handle x.com and twitter.com URLs with /analytics if (options.removeXAnalytics) { const xComPattern = /^(https?:\/\/(www\.)?(x\.com|twitter\.com)\/([^/]+)\/status\/(\d+))\/analytics(\/)?(\?.*)?(#.*)?$/i; const xMatch = urlString.match(xComPattern); if (xMatch) { let cleanUrl = xMatch[1]; if (xMatch[7]) cleanUrl += xMatch[7]; if (xMatch[8]) cleanUrl += xMatch[8]; urlString = cleanUrl; } } const url = new URL(urlString); if (url.protocol !== 'http:' && url.protocol !== 'https:') { throw new Error('Unsupported protocol'); } url.hostname = url.hostname.toLowerCase(); if (url.hostname.startsWith('www.')) { url.hostname = url.hostname.slice(4); } if ((url.protocol === 'http:' && url.port === '80') || (url.protocol === 'https:' && url.port === '443')) { url.port = ''; } // Query parameter filtering const searchParams = new URLSearchParams(url.search); const filteredParams = Array.from(searchParams.entries()) .filter(([key]) => { if (key === '') return false; if (options.removeSessionIDs && /^(s|session|sid|sessionid|phpsessid|jsessionid|aspsessionid|asp\.net_sessionid)$/i.test(key)) { return false; } if (options.removeUTMParams && /^utm_/i.test(key)) { return false; } if (options.removeTrackingParams && /^(ref|referrer|fbclid|gclid|cid|mcid|source|medium|campaign|term|content|sc_rid|mc_[a-z]+)$/i.test(key)) { return false; } return true; }) .sort(([keyA], [keyB]) => keyA.localeCompare(keyB)); url.search = new URLSearchParams(filteredParams).toString(); if (options.removeAnchors) { url.hash = ''; } return url.toString(); } catch (error) { return undefined; } }
• src/utils/api-error-handler.ts:5-51 (helper)

  Supporting utility handleApiError returns standardized MCP error responses for common HTTP status codes (401,402,429) from the Jina API.
  export function handleApiError(response: Response, context: string = "API request") { if (response.status === 401) { return { content: [ { type: "text" as const, text: "Authentication failed. Please set your API key in the Jina AI MCP settings. You can get a free API key by visiting https://jina.ai and signing up for an account.", }, ], isError: true, }; } if (response.status === 402) { return { content: [ { type: "text" as const, text: "This key is out of quota. Please top up this key at https://jina.ai", }, ], isError: true, }; } if (response.status === 429) { return { content: [ { type: "text" as const, text: "Rate limit exceeded. Please upgrade your API key to get higher rate limits. Visit https://jina.ai to manage your subscription and increase your usage limits.", }, ], isError: true, }; } // Default error message for other HTTP errors return { content: [ { type: "text" as const, text: `Error: ${context} failed - ${response.status} ${response.statusText}`, }, ], isError: true, }; }