Apple MCP Tools

Instructions

Implementation Reference

• src/handlers/webSearchHandler.ts:12-38 (handler)

  The handleWebSearch function executes the tool logic: loads the webSearch module, calls its webSearch method with the query, formats the results into a text response, handles errors.

  export async function handleWebSearch(
    args: WebSearchArgs,
    loadModule: LoadModuleFunction
  ): Promise<ToolResult> {
    try {
      const webSearchModule = await loadModule('webSearch');
      const result = await webSearchModule.webSearch(args.query);
      
      return {
        content: [{
          type: "text",
          text: result.results.length > 0 ? 
            `Found ${result.results.length} results for "${args.query}". ${result.results.map(r => `[${r.displayUrl}] ${r.title} - ${r.snippet} \n content: ${r.content}`).join("\n")}` : 
            `No results found for "${args.query}".`
        }],
        isError: false
      };
    } catch (error) {
      return {
        content: [{
          type: "text",
          text: `Error performing web search: ${error instanceof Error ? error.message : String(error)}`
        }],
        isError: true
      };
    }
  }

• utils/webSearch.ts:340-394 (handler)

  The core webSearch function in the module that performs DuckDuckGo search, extracts results, fetches and extracts content from top 5 results using parallel requests.

  export async function webSearch(query: string): Promise<ContentResponse> {
    try {
      // Step 1: Get search results from DuckDuckGo
      const searchResults = await searchDuckDuckGo(query);
  
      if (searchResults.error || searchResults.results.length === 0) {
        return {
          query,
          error: searchResults.error || "No search results found",
          results: [],
        };
      }
  
      // Step 2: Fetch content for each result (limit to 5 results to improve performance)
      const resultsToProcess = searchResults.results.slice(0, 5);
      
      // Use Promise.allSettled to ensure all requests complete, even if some fail
      const settledPromises = await Promise.allSettled(
        resultsToProcess.map(result => fetchPageContent(result.url))
      );
  
      // Process results
      const fullResults = resultsToProcess.map((result, index) => {
        const promise = settledPromises[index];
        
        if (promise.status === "fulfilled") {
          return {
            ...result,
            content: promise.value.content,
            error: promise.value.error
          };
        } else {
          // For rejected promises, return the result with an error
          return {
            ...result,
            content: null,
            error: `Failed to fetch content: ${promise.reason}`
          };
        }
      });
  
      return {
        query,
        results: fullResults,
      };
    } catch (error) {
      const errorMessage = error instanceof Error ? error.message : String(error);
      console.error("Web search failed:", errorMessage);
      return {
        query,
        error: errorMessage,
        results: [],
      };
    }
  }

• src/handlers/webSearchHandler.ts:5-7 (schema)

  Zod schema for validating webSearch tool input arguments (query string).

  export const WebSearchArgsSchema = z.object({
    query: z.string().min(1),
  });

• index.ts:136-139 (registration)

  Registration in the main switch statement: parses args with schema and calls handleWebSearch.

  case "webSearch": {
    const validatedArgs = WebSearchArgsSchema.parse(args);
    return await handleWebSearch(validatedArgs, loadModule);
  }

• tools.ts:180-193 (registration)

  Tool specification/registration for listTools: defines name, description, and JSON input schema for webSearch.

  const WEB_SEARCH_TOOL: Tool = {
    name: "webSearch",
    description: "Search the web using DuckDuckGo and retrieve content from search results",
    inputSchema: {
      type: "object",
      properties: {
        query: {
          type: "string",
          description: "Search query to look up"
        }
      },
      required: ["query"]
    }
  };