URL-Context-MCP MCP

Instructions

Implementation Reference

• src/index.ts:87-148 (handler)

  Core handler function for the google_search tool. Calls the Gemini API with google_search and url_context tools enabled, constructs a detailed research prompt, fetches the response, extracts text output, and appends search queries and grounding sources metadata.
  async function callGoogleSearch(params: GoogleSearchParams): Promise<string> { const apiKey = process.env.GOOGLE_API_KEY; if (!apiKey) { throw new Error("GOOGLE_API_KEY is not set"); } const model = params.model ?? "gemini-2.5-flash"; const endpoint = `https://generativelanguage.googleapis.com/v1beta/models/${encodeURIComponent(model)}:generateContent`; const promptText = `Role: You are a meticulous web researcher.\n\nPrimary directive:\n- If the user provides explicit URLs in the request, SKIP web search and use URL Context to analyze ONLY those URLs.\n- Otherwise, perform grounded Google Search and for ANY URL you cite, you MUST fetch it via URL Context and synthesize findings.\n- Prefer authoritative, up-to-date sources.\n- If coverage is insufficient, refine the query and continue internally up to 5 rounds. Stop once adequate.\n\nTask:${params.instruction ? `\n${params.instruction}` : ``}\n\nResearch focus: ${params.query}`; const tools: any[] = [{ google_search: {} }, { url_context: {} }]; const body = { contents: [ { parts: [{ text: promptText }], }, ], tools, } as const; const response = await fetch(endpoint + `?key=${encodeURIComponent(apiKey)}`, { method: "POST", headers: { "Content-Type": "application/json", }, body: JSON.stringify(body), }); if (!response.ok) { const text = await response.text(); throw new Error(`Gemini API error ${response.status}: ${text}`); } const json = (await response.json()) as any; // Try to get the primary text output const candidate = json?.candidates?.[0]; const textOut = candidate?.content?.parts?.map((p: any) => p?.text).filter(Boolean).join("\n"); // Collect grounding metadata for search results const groundingMeta = candidate?.grounding_metadata; const searchQueries = groundingMeta?.web_search_queries || []; const groundingChunks = groundingMeta?.grounding_chunks || []; let sourcesSection = ""; if (searchQueries.length > 0) { sourcesSection += "\n\nSearch Queries:\n" + searchQueries.map((q: string) => `- ${q}`).join("\n"); } if (groundingChunks.length > 0) { sourcesSection += "\n\nSources (Google Search):\n" + groundingChunks .map((chunk: any) => `- ${chunk.web?.title || "(no title)"}: ${chunk.web?.uri || "(no URL)"})`) .join("\n"); } if (textOut) { return textOut + sourcesSection; } // Fallback: return raw JSON if text not found return JSON.stringify(json, null, 2); }
• src/index.ts:264-283 (handler)

  Dispatch handler within CallToolRequestSchema for google_search. Validates input arguments, calls the core callGoogleSearch function, and formats the response.
  if (name === "google_search") { const { query, instruction, model, } = (args ?? {}) as { query?: string; instruction?: string; model?: string; }; if (!query || typeof query !== "string" || query.trim() === "") { throw new Error("'query' must be provided as a non-empty string"); } const text = await callGoogleSearch({ query: query.trim(), instruction, model, }); return { content: [{ type: "text", text }] }; }
• src/index.ts:205-226 (registration)

  Registration of the google_search tool in the tools list provided to ListToolsRequestHandler, including name, description, and inputSchema.
  name: "google_search", description: "Search the web using Google Search grounding via Gemini API. Provides search results with sources and citations.", inputSchema: { type: "object", properties: { query: { type: "string", description: "Search query to find information on the web", }, instruction: { type: "string", description: "Optional instruction for processing search results", }, model: { type: "string", description: "Gemini model id (e.g., gemini-2.5-flash)", }, }, required: ["query"], }, },
• src/index.ts:18-22 (schema)

  TypeScript type definition for GoogleSearchParams used in the callGoogleSearch handler.
  type GoogleSearchParams = { query: string; instruction?: string; model?: string; };