URL-Context-MCP MCP

Instructions

Implementation Reference

• src/index.ts:264-283 (handler)

  MCP CallTool request handler specifically for the 'google_search' tool. Extracts and validates input arguments, invokes the callGoogleSearch helper, and formats the response as MCP content.

  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:87-148 (helper)

  Helper function that executes the Google Search logic: builds a specialized prompt, calls the Gemini API with 'google_search' and 'url_context' tools enabled, processes the response to extract text output and appends search queries and source 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:204-227 (registration)

  Registers the 'google_search' tool in the MCP tools list, including name, description, and input schema. This is returned in response to ListTools requests.

    {
      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:208-225 (schema)

  Input schema definition for the 'google_search' tool, specifying required 'query' parameter and optional 'instruction' and 'model'.

  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"],
  },