search_docs

Instructions

Implementation Reference

• src/tools/searchDocs/tool.ts:34-110 (handler)

  The main handler function 'tool' for the 'search_docs' MCP tool. Fetches search index from Powertools docs, builds Lunr index, searches for query, filters by confidence threshold, returns list of relevant doc pages with title, url, score.

  const tool = async (props: ToolProps): Promise<CallToolResult> => {
    const { search, runtime, version } = props;
    logger.appendKeys({ tool: 'searchDocs' });
    logger.appendKeys({ search, runtime, version });
  
    const urlParts =
      runtime === 'python' || runtime === 'typescript' || runtime === 'java'
        ? [runtime, version]
        : [runtime];
    const baseUrl = `${POWERTOOLS_BASE_URL}/${urlParts.join('/')}`;
    const url = new URL(baseUrl);
    const urlSuffix = '/search/search_index.json';
    url.pathname = `${url.pathname}${urlSuffix}`;
  
    let searchIndexContent: {
      docs: { location: string; title: string; text: string }[];
    };
    try {
      const content = await fetchWithCache({
        url,
        contentType: 'application/json',
      });
      searchIndexContent = JSON.parse(content);
      if (
        isNullOrUndefined(searchIndexContent.docs) ||
        !Array.isArray(searchIndexContent.docs)
      ) {
        throw new Error(
          `Invalid search index format for ${runtime} ${version}: missing 'docs' property`
        );
      }
    } catch (error) {
      logger.error('Failed to fetch search index', {
        error: (error as Error).message,
      });
      return buildResponse({
        content: `Failed to fetch search index for ${runtime} ${version}: ${(error as Error).message}`,
        isError: true,
      });
    }
  
    // TODO: consume built/exported search index - #79
    const index = lunr(function () {
      this.ref('location');
      this.field('title', { boost: 1000 });
      this.field('text', { boost: 1 });
      this.field('tags', { boost: 1000000 });
  
      for (const doc of searchIndexContent.docs) {
        if (!doc.location || !doc.title || !doc.text) continue;
  
        this.add({
          location: doc.location,
          title: doc.title,
          text: doc.text,
        });
      }
    });
  
    const results = [];
    for (const result of index.search(search)) {
      if (result.score < SEARCH_CONFIDENCE_THRESHOLD) break; // Results are sorted by score, so we can stop early
      results.push({
        title: result.ref,
        url: `${baseUrl}/${result.ref}`,
        score: result.score,
      });
    }
  
    logger.debug(
      `Search results with confidence >= ${SEARCH_CONFIDENCE_THRESHOLD} found: ${results.length}`
    );
  
    return buildResponse({
      content: results,
    });
  };

• src/tools/searchDocs/schemas.ts:9-23 (schema)

  Zod schema defining and validating the input parameters for the search_docs tool: search (required string), runtime (enum), version (optional string, default 'latest').

  const schema = {
    search: z
      .string()
      .transform((val) => val.toLowerCase().trim())
      .describe('what to search for'),
    runtime: z
      .enum(runtimes)
      .describe('the Powertools for AWS runtime to search the documentation for'),
    version: z
      .string()
      .transform((val) => val.toLowerCase().trim())
      .optional()
      .describe('version is always semantic 3 digit in the form x.y.z')
      .default('latest'),
  };

• src/server.ts:24-28 (registration)

  Registers the 'search_docs' tool on the MCP server using the imported name, description, input schema, and handler function.

    searchDocsName,
    searchDocsDescription,
    searchDocsSchema,
    searchDocs
  );

• src/tools/searchDocs/constants.ts:1-8 (helper)

  Defines the constant name 'search_docs' and detailed description used for tool registration.

  const name = 'search_docs' as const;
  const description =
    'Search Powertools for AWS Lambda documentation to learn about Serverless best practices. ' +
    "Try searching for features like 'Logger', 'Tracer', 'Metrics', 'Idempotency', 'batchProcessor', event handler, etc. " +
    'Powertools is available for the following runtimes: python, typescript, java, dotnet. ' +
    'When searching, always specify the version of Powertools you are interested in, if unsure, try to read it from the workspace configuration, otherwise use "latest".';
  
  export { name, description };

• src/tools/searchDocs/index.ts:1-3 (helper)

  Index file re-exporting name, description, schema, and tool handler for convenient import in server.ts.

  export { description, name } from './constants.ts';
  export { schema } from './schemas.ts';
  export { tool } from './tool.ts';