Kagi Search

Instructions

Implementation Reference

• src/tools/search.js:30-102 (handler)

  Main handler function for the kagi_search_fetch tool. Executes concurrent searches using kagi-ken, applies timeout, processes results (fulfilled/rejected), formats output, and returns MCP-compatible response.

  export async function kagiSearchFetch({ queries, limit = 10 }) {
    try {
      if (!queries || queries.length === 0) {
        throw new Error("Search called with no queries.");
      }
  
      const { token } = getEnvironmentConfig();
  
      // Execute searches concurrently (similar to ThreadPoolExecutor in original)
      const searchPromises = queries.map((query) => {
        if (typeof query !== "string" || query.trim() === "") {
          throw new Error("All queries must be non-empty strings");
        }
        return search(query.trim(), token, limit);
      });
  
      // Wait for all searches to complete with 10 second timeout per search
      const results = await Promise.allSettled(
        searchPromises.map((promise) =>
          Promise.race([
            promise,
            new Promise((_, reject) =>
              setTimeout(() => reject(new Error("Search timeout")), 10000)
            ),
          ])
        ),
      );
  
      // Process results and handle any failures
      const responses = [];
      const errors = [];
  
      for (let i = 0; i < results.length; i++) {
        const result = results[i];
        if (result.status === "fulfilled") {
          responses.push(result.value);
        } else {
          errors.push(
            `Query "${queries[i]}": ${result.reason?.message || result.reason}`,
          );
          // Add empty response to maintain index alignment
          responses.push({ results: [] });
        }
      }
  
      // Format results using the same formatting as official MCP
      const formattedResults = formatSearchResults(queries, responses);
  
      // Include any errors in the response
      let finalResponse = formattedResults;
      if (errors.length > 0) {
        finalResponse += "\n\nErrors encountered:\n" + errors.join("\n");
      }
  
      return {
        content: [
          {
            type: "text",
            text: finalResponse,
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: formatError(error),
          },
        ],
      };
    }
  }

• src/tools/search.js:12-19 (schema)

  Input schema for kagi_search_fetch tool using Zod. Defines 'queries' (array of strings, min 1) and optional 'limit' (int 1-50, default 10).

  export const searchInputSchema = {
    queries: z.array(z.string()).min(1).describe(
      "One or more concise, keyword-focused search queries. Include essential context within each query for standalone use.",
    ),
    limit: z.number().int().min(1).max(50).optional().describe(
      "Maximum number of search results per query (default: 10, max: 50)",
    ),
  };

• src/tools/search.js:107-116 (registration)

  Tool configuration object (searchToolConfig) that registers the tool name 'kagi_search_fetch' along with its description and inputSchema.

  export const searchToolConfig = {
    name: "kagi_search_fetch",
    description: `
      Fetch web results based on one or more queries using the Kagi.com web search engine. Use for
      general search and when the user explicitly tells you to 'fetch' results/information. Results are
      from all queries given. They are numbered continuously, so that a user may be able to refer to a
      result by a specific number. Supports optional limit parameter to control results per query.
      `.replace(/\s+/gs, " ").trim(),
    inputSchema: searchInputSchema,
  };

• src/index.js:33-41 (registration)

  MCP server registration of kagi_search_fetch tool using searchToolConfig.name and binding the kagiSearchFetch handler via server.registerTool().

  this.server.registerTool(
    searchToolConfig.name,
    {
      title: "Kagi Search",
      description: searchToolConfig.description,
      inputSchema: searchToolConfig.inputSchema,
    },
    async (args) => await kagiSearchFetch(args),
  );

• src/utils/formatting.js:13-56 (helper)

  Helper function formatSearchResults that formats raw search results from kagi-ken into the official Kagi MCP output format, numbering results continuously across queries.

  export function formatSearchResults(queries, responses) {
    const resultTemplate = (resultNumber, title, url, published, snippet) =>
      `${resultNumber}: ${title}
  ${url}
  Published Date: ${published}
  ${snippet}`;
  
    const queryResponseTemplate = (query, formattedSearchResults) =>
      `-----
  Results for search query "${query}":
  -----
  ${formattedSearchResults}`;
  
    const perQueryResponseStrs = [];
    let startIndex = 1;
  
    for (let i = 0; i < queries.length; i++) {
      const query = queries[i];
      const response = responses[i];
  
      // Filter for actual search results only (t === 0), excluding related searches (t === 1)
      const results = (response?.results || response?.data || [])
        .filter((item) => item.t === 0);
  
      const formattedResultsList = results.map((result, index) => {
        const resultNumber = startIndex + index;
        return resultTemplate(
          resultNumber,
          result.title || "No Title",
          result.url || "",
          result.published || result.publishedDate || "Not Available",
          result.snippet || result.description || "No snippet available",
        );
      });
  
      startIndex += results.length;
  
      const formattedResultsStr = formattedResultsList.join("\n\n");
      const queryResponseStr = queryResponseTemplate(query, formattedResultsStr);
      perQueryResponseStrs.push(queryResponseStr);
    }
  
    return perQueryResponseStrs.join("\n\n");
  }