Gemini URL Context & Search MCP Server

Instructions

Implementation Reference

• src/adapter/GoogleSearchGenAI.ts:21-67 (handler)

  Core handler function that performs the Google Search by calling the Gemini API with grounding tools (google_search and url_context). This is the exact implementation executing the tool logic.
  async search(input: GoogleSearchInput): Promise<GoogleSearchResponse> { const endpoint = `https://generativelanguage.googleapis.com/v1beta/models/${encodeURIComponent(input.model)}:generateContent`; const promptText = `Role: You are a meticulous web researcher. Primary directive: - Perform grounded Google Search and for ANY URL you cite, you MUST fetch it via URL Context and synthesize findings. - Prefer authoritative, up-to-date sources. - If coverage is insufficient, refine the query and continue internally up to 5 rounds. Stop once adequate. Task:${input.instruction ? `\n${input.instruction}` : ''} Research focus: ${input.query}`; const tools = [{ google_search: {} }, { url_context: {} }]; const body = { contents: [ { parts: [{ text: promptText }], }, ], tools, }; try { const response = await fetch(endpoint + `?key=${encodeURIComponent(this.apiKey)}`, { method: "POST", headers: { "Content-Type": "application/json", }, body: JSON.stringify(body), }); if (!response.ok) { const text = await response.text(); this.mapAndThrowError(new Error(`Gemini API error ${response.status}: ${text}`)); } const json = await response.json(); return this.parseSearchResponse(json); } catch (error) { this.mapAndThrowError(error as Error); throw error; // This won't be reached due to mapAndThrowError throwing } }
• src/usecase/GoogleSearchUseCase.ts:4-21 (handler)

  Use case handler that prepares the input and delegates to the GoogleSearchGenAI implementation.
  export class GoogleSearchUseCase { constructor(private readonly googleSearchGenAI: GoogleSearchGenAI) {} async execute( query: string, instruction?: string, model?: ModelName ): Promise<GoogleSearchResponse> { const modelName = model || ModelName.create(); const input: GoogleSearchInput = { query: query.trim(), instruction, model: modelName.toString() }; return await this.googleSearchGenAI.search(input); }
• src/index.ts:155-202 (handler)

  MCP CallToolRequest handler dispatch for 'google_search' tool, including validation and response formatting.
  if (request.params.name === 'google_search') { try { const { query, instruction, model } = request.params.arguments as { query?: string; instruction?: string; model?: string; }; if (!query || typeof query !== 'string' || query.trim() === '') { throw new McpError( ErrorCode.InvalidParams, 'query must be a non-empty string' ); } const modelName = model ? ModelName.create(model) : ModelName.create(); const result = await this.googleSearchUseCase.execute(query.trim(), instruction, modelName); // Format response similar to other implementation let responseText = result.result; if (result.searchQueries.length > 0) { responseText += "\n\nSearch Queries:\n" + result.searchQueries.map(q => `- ${q}`).join("\n"); } if (result.sources.length > 0) { responseText += "\n\nSources (Google Search):\n" + result.sources.map(source => `- ${source.title}: ${source.url}`).join("\n"); } return { content: [ { type: 'text', text: responseText, }, ], }; } catch (error) { if (error instanceof McpError) { throw error; } throw new McpError( ErrorCode.InternalError, `Failed to perform Google search: ${(error as Error).message}` ); }
• src/index.ts:74-95 (schema)

  Input schema definition for the 'google_search' tool as exposed in MCP ListTools response.
  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 name to use (optional, defaults to gemini-2.0-flash-exp)', }, }, required: ['query'], }, },
• src/index.ts:227-227 (registration)

  Initialization and registration of the GoogleSearchUseCase instance in the main server class.
  this.googleSearchUseCase = new GoogleSearchUseCase(googleSearchGenAI);