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);