Perplexity MCP Server

Instructions

Implementation Reference

• src/server/PerplexityServer.ts:146-154 (handler)

  The handler function for the MCP 'search' tool. It extracts the query from arguments (ignoring optional detail_level and stream) and delegates execution to the SearchEngine.performSearch method.

  private async handleSearch(args: Record<string, unknown>): Promise<string> {
    const typedArgs = args as {
      query: string;
      detail_level?: "brief" | "normal" | "detailed";
      stream?: boolean;
    };
  
    return await this.searchEngine.performSearch(typedArgs.query);
  }

• src/schema/toolSchemas.ts:343-403 (schema)

  The input/output schema definition and metadata for the 'search' tool, including description, parameters, examples, and use cases.

  {
    name: "search",
    description:
      "Performs a web search using Perplexity AI based on the provided query and desired detail level. Useful for general knowledge questions, finding information, or getting different perspectives.",
    category: "Web Search",
    keywords: ["search", "web", "internet", "query", "find", "information", "lookup", "perplexity"],
    use_cases: [
      "Answering general knowledge questions.",
      "Finding specific information online.",
      "Getting quick summaries or detailed explanations.",
      "Researching topics.",
    ],
    inputSchema: {
      type: "object",
      properties: {
        query: {
          type: "string",
          description: "The search query or question to ask Perplexity.",
          examples: ["What is the capital of France?", "Explain black holes"],
        },
        detail_level: {
          type: "string",
          enum: ["brief", "normal", "detailed"],
          description: "Optional: Controls the level of detail in the response (default: normal).",
          examples: ["brief", "detailed"],
        },
        stream: {
          type: "boolean",
          description:
            "Optional: Enable streaming response for large documentation queries (default: false).",
          examples: [true, false],
        },
      },
      required: ["query"],
    },
    outputSchema: {
      type: "object",
      properties: {
        response: {
          type: "string",
          description: "The search result text provided by Perplexity AI.",
        },
      },
    },
    examples: [
      {
        description: "Simple search query",
        input: { query: "What is the weather in London?" },
        output: { response: "The weather in London is currently..." },
      },
      {
        description: "Detailed search query",
        input: { query: "Explain the theory of relativity", detail_level: "detailed" },
        output: {
          response:
            "Albert Einstein's theory of relativity includes Special Relativity and General Relativity...",
        },
      },
    ],
    related_tools: ["chat_perplexity", "get_documentation", "find_apis"],
  },

• src/server/PerplexityServer.ts:175-186 (registration)

  Registers all MCP tools including 'search' by creating a registry mapping 'search' to its handler and calling setupToolHandlers.

  private setupToolHandlers(): void {
    const toolHandlers = createToolHandlersRegistry({
      chat_perplexity: this.handleChatPerplexity.bind(this),
      get_documentation: this.handleGetDocumentation.bind(this),
      find_apis: this.handleFindApis.bind(this),
      check_deprecated_code: this.handleCheckDeprecatedCode.bind(this),
      search: this.handleSearch.bind(this),
      extract_url_content: this.handleExtractUrlContent.bind(this),
    });
  
    setupToolHandlers(this.server, toolHandlers);
  }

• src/server/modules/SearchEngine.ts:14-99 (helper)

  Core implementation of the search functionality using Puppeteer to interact with Perplexity AI, including navigation, query submission, answer extraction, retries, and error recovery. Called by the 'search' tool handler.

  async performSearch(query: string): Promise<string> {
    // Set a global timeout for the entire operation with buffer for MCP
    const operationTimeout = setTimeout(() => {
      logError("Global operation timeout reached, initiating recovery...");
      this.browserManager.performRecovery().catch((err: unknown) => {
        logError("Recovery after timeout failed:", {
          error: err instanceof Error ? err.message : String(err),
        });
      });
    }, CONFIG.PAGE_TIMEOUT - CONFIG.MCP_TIMEOUT_BUFFER);
  
    try {
      // Ensure browser is ready
      if (!this.browserManager.isReady()) {
        logInfo("Browser not ready, initializing...");
        await this.browserManager.initialize();
      }
  
      // Reset idle timeout
      this.browserManager.resetIdleTimeout();
  
      // Use retry operation for the entire search process with increased retries
      const ctx = this.browserManager.getPuppeteerContext();
      
      return await retryOperation(ctx, async () => {
        logInfo(`Navigating to Perplexity for query: "${query.substring(0, 30)}${query.length > 30 ? '...' : ''}"`);
        await this.browserManager.navigateToPerplexity();
  
        // Validate main frame is attached
        const page = this.browserManager.getPage();
        if (!page || page.mainFrame().isDetached()) {
          logError("Main frame is detached, will retry with new browser instance");
          throw new Error("Main frame is detached");
        }
  
        logInfo("Waiting for search input...");
        const selector = await this.browserManager.waitForSearchInput();
        if (!selector) {
          logError("Search input not found, taking screenshot for debugging");
          if (page) {
            await page.screenshot({ path: "debug_search_input_not_found.png", fullPage: true });
          }
          throw new Error("Search input not found");
        }
  
        logInfo(`Found search input with selector: ${selector}`);
  
        // Perform the search
        await this.executeSearch(page, selector, query);
  
        // Wait for and extract the answer
        const answer = await this.waitForCompleteAnswer(page);
        return answer;
      }, CONFIG.MAX_RETRIES);
    } catch (error) {
      logError("Search operation failed after all retries:", {
        error: error instanceof Error ? error.message : String(error),
      });
  
      // Handle specific error cases with user-friendly messages
      if (error instanceof Error) {
        if (error.message.includes("detached") || error.message.includes("Detached")) {
          logError("Frame detachment detected, attempting recovery...");
          await this.browserManager.performRecovery();
          return "The search operation encountered a technical issue. Please try again with a more specific query.";
        }
  
        if (error.message.includes("timeout") || error.message.includes("Timed out")) {
          logError("Timeout detected, attempting recovery...");
          await this.browserManager.performRecovery();
          return "The search operation is taking longer than expected. This might be due to high server load. Your query has been submitted and we're waiting for results. Please try again with a more specific query if needed.";
        }
  
        if (error.message.includes("navigation") || error.message.includes("Navigation")) {
          logError("Navigation error detected, attempting recovery...");
          await this.browserManager.performRecovery();
          return "The search operation encountered a navigation issue. This might be due to network connectivity problems. Please try again later.";
        }
      }
  
      // For any other errors, return a user-friendly message
      return `The search operation could not be completed. Error: ${error instanceof Error ? error.message : 'Unknown error'}. Please try again later with a more specific query.`;
    } finally {
      clearTimeout(operationTimeout);
    }
  }