search_documentation

Instructions

Implementation Reference

• src/handlers/search-documentation.ts:7-66 (handler)

  The SearchDocumentationHandler class contains the handle() method that executes the core tool logic: generates embeddings for the query, performs vector search in Qdrant, formats results with titles, URLs, scores, and content excerpts.

  export class SearchDocumentationHandler extends BaseHandler {
    async handle(args: any): Promise<McpToolResponse> {
      if (!args.query || typeof args.query !== 'string') {
        throw new McpError(ErrorCode.InvalidParams, 'Query is required');
      }
  
      const limit = args.limit || 5;
  
      try {
        const queryEmbedding = await this.apiClient.getEmbeddings(args.query);
        
        const searchResults = await this.apiClient.qdrantClient.search(COLLECTION_NAME, {
          vector: queryEmbedding,
          limit,
          with_payload: true,
          with_vector: false, // Optimize network transfer by not retrieving vectors
          score_threshold: 0.7, // Only return relevant results
        });
  
        const formattedResults = searchResults.map(result => {
          if (!isDocumentPayload(result.payload)) {
            throw new Error('Invalid payload type');
          }
          return `[${result.payload.title}](${result.payload.url})\nScore: ${result.score.toFixed(3)}\nContent: ${result.payload.text}\n`;
        }).join('\n---\n');
  
        return {
          content: [
            {
              type: 'text',
              text: formattedResults || 'No results found matching the query.',
            },
          ],
        };
      } catch (error) {
        if (error instanceof Error) {
          if (error.message.includes('unauthorized')) {
            throw new McpError(
              ErrorCode.InvalidRequest,
              'Failed to authenticate with Qdrant cloud while searching'
            );
          } else if (error.message.includes('ECONNREFUSED') || error.message.includes('ETIMEDOUT')) {
            throw new McpError(
              ErrorCode.InternalError,
              'Connection to Qdrant cloud failed while searching'
            );
          }
        }
        return {
          content: [
            {
              type: 'text',
              text: `Search failed: ${error}`,
            },
          ],
          isError: true,
        };
      }
    }
  }

• src/handler-registry.ts:38-38 (registration)

  Registers the SearchDocumentationHandler instance in the handlers map with the key 'search_documentation' for tool dispatch.

  this.handlers.set('search_documentation', new SearchDocumentationHandler(this.server, this.apiClient));

• src/handler-registry.ts:50-68 (schema)

  Defines the tool metadata including name, description, and inputSchema for 'search_documentation' in the ListTools response.

  {
    name: 'search_documentation',
    description: 'Search through stored documentation using natural language queries. Use this tool to find relevant information across all stored documentation sources. Returns matching excerpts with context, ranked by relevance. Useful for finding specific information, code examples, or related documentation.',
    inputSchema: {
      type: 'object',
      properties: {
        query: {
          type: 'string',
          description: 'The text to search for in the documentation. Can be a natural language query, specific terms, or code snippets.',
        },
        limit: {
          type: 'number',
          description: 'Maximum number of results to return (1-20). Higher limits provide more comprehensive results but may take longer to process. Default is 5.',
          default: 5,
        },
      },
      required: ['query'],
    },
  } as ToolDefinition,

• src/tools/search-documentation.ts:16-36 (schema)

  Alternative tool definition and schema in the client-side or base tool class.

  get definition(): ToolDefinition {
    return {
      name: 'search_documentation',
      description: 'Search through stored documentation',
      inputSchema: {
        type: 'object',
        properties: {
          query: {
            type: 'string',
            description: 'Search query',
          },
          limit: {
            type: 'number',
            description: 'Maximum number of results to return',
            default: 5,
          },
        },
        required: ['query'],
      },
    };
  }