DocsScraper

Instructions

Implementation Reference

• src/index.ts:115-200 (handler)

  The handler function for the 'search_docs' tool. It extracts parameters, validates input, calls the DocsScraper API for semantic search, formats results, and handles errors.

      case "search_docs": {
        const query = String(request.params.arguments?.query || "");
        const top = Number(request.params.arguments?.top || 5);
        const service = request.params.arguments?.service ? String(request.params.arguments.service) : undefined;
  
        if (!query.trim()) {
          throw new Error("Query parameter is required and cannot be empty");
        }
  
        // Clamp top to safe range
        const clampedTop = Math.max(1, Math.min(10, top));
  
        try {
          // Build request parameters
          const params: any = {
            query: query,
            top: clampedTop
          };
          
          // Include service parameter if provided
          if (service && service.trim()) {
            params.service = service.trim();
          }
  
          // Make request to DocsScraper API
          const response = await axios.get(`${API_BASE_URL}/api/chunks/search`, {
            params,
            headers: {
              'X-API-Key': API_KEY,
              'Content-Type': 'application/json'
            },
            timeout: 180000 // 30 second timeout
          });
  
          const results = response.data;
  
          if (Array.isArray(results) && results.length > 0) {
            // Format results for display
            const formattedResults = results.map((result: SearchResult, index: number) => {
              const chunk = result.chunk;
              const score = result.score ? ` (Score: ${result.score.toFixed(3)})` : '';
              const source = result.source ? ` [Source: ${result.source}]` : '';
              
              return `**Result ${index + 1}${score}${source}**
  Service: ${chunk.service}
  URL: ${chunk.url}
  Summary: ${chunk.oneLiner}
  
  Content:
  ${chunk.fullContent}
  
  ---`;
            }).join('\n\n');
  
            return {
              content: [{
                type: "text",
                text: `Found ${results.length} relevant documentation chunk(s) for query: "${query}"\n\n${formattedResults}`
              }]
            };
          } else {
            return {
              content: [{
                type: "text",
                text: `No documentation chunks found for query: "${query}". The search may have found no relevant results, or the scraper sources may not have returned any matches.`
              }]
            };
          }
        } catch (error) {
          if (axios.isAxiosError(error)) {
            if (error.response?.status === 401) {
              throw new Error("Authentication failed. Please check your API key.");
            } else if (error.response?.status === 400) {
              throw new Error(`Bad request: ${error.response.data?.message || 'Invalid query parameters'}`);
            } else if (error.response?.status === 404) {
              throw new Error("DocsScraper API endpoint not found. Please check the base URL.");
            } else if (error.code === 'ECONNREFUSED') {
              throw new Error(`Cannot connect to DocsScraper API at ${API_BASE_URL}. Please ensure the service is running.`);
            } else {
              throw new Error(`API request failed: ${error.response?.status} ${error.response?.statusText || error.message}`);
            }
          } else {
            throw new Error(`Search failed: ${error instanceof Error ? error.message : 'Unknown error'}`);
          }
        }
      }

• src/index.ts:83-102 (schema)

  Input schema defining parameters for the search_docs tool: query (required string), top (optional number 1-10), service (required string).

  inputSchema: {
    type: "object",
    properties: {
      query: {
        type: "string",
        description: "The search query to find relevant documentation"
      },
      top: {
        type: "number",
        description: "Maximum number of results to return (1-10, default: 5)",
        minimum: 1,
        maximum: 10,
        default: 5
      },
      service: {
        type: "string",
        description: "Service name to filter results by (case-insensitive)"
      }
    },
    required: ["query", "service"]

• src/index.ts:80-104 (registration)

  Registration of the search_docs tool in the ListTools response, including name, description, and input schema.

  {
    name: "search_docs",
    description: "Search through documentation chunks using semantic search. Make sure your query is specific to get the best results. Forgetting to add 'api' to the query will return ui results etc.",
    inputSchema: {
      type: "object",
      properties: {
        query: {
          type: "string",
          description: "The search query to find relevant documentation"
        },
        top: {
          type: "number",
          description: "Maximum number of results to return (1-10, default: 5)",
          minimum: 1,
          maximum: 10,
          default: 5
        },
        service: {
          type: "string",
          description: "Service name to filter results by (case-insensitive)"
        }
      },
      required: ["query", "service"]
    }
  }