feat: refactor search docs tool (#83)

Co-authored-by: Stefano Vozza <[email protected]>

Author: dreamorosi

.github/workflows/make-release.yml

@@ -23,18 +23,16 @@ concurrency:
   group: on-release-publish
 
 jobs:
-  # temporarily disabled until we address #48
-  # run-unit-tests:
-  #  uses: ./.github/workflows/reusable-code-quality.yml
+  run-unit-tests:
+    uses: ./.github/workflows/reusable-code-quality.yml
   run-e2e-tests:
-    # needs: run-unit-tests # uncomment when we re-enable the unit tests #48
     uses: ./.github/workflows/reusable-e2e.yml
   # This job publishes the packages to npm.
   # It uses the latest git commit sha as the version and ensures provenance with NPM_CONFIG_PROVENANCE flag.
   # We don't bump the version because we do that in the `make-version` workflow.
   # It also sets the RELEASE_VERSION output to be used by the next job to create a git tag.
   publish-npm:
-    needs: run-e2e-tests
+    needs: [run-e2e-tests, run-unit-tests]
     # Needed as recommended by npm docs on publishing with provenance https://docs.npmjs.com/generating-provenance-statements
     permissions:
       id-token: write

biome.json

@@ -31,7 +31,8 @@
       "lib",
       "cdk.out",
       "site",
-      ".aws-sam"
+      ".aws-sam",
+      "dist"
     ]
   }
 }

package-lock.json

@@ -57,7 +57,6 @@
     "@types/node": "^24.0.0",
     "cacache": "^19.0.1",
     "lunr": "^2.3.9",
-    "lunr-languages": "^1.14.0",
     "zod": "^3.25.57"
   },
   "devDependencies": {

package.json

@@ -1,6 +1,9 @@
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
-import { getStringFromEnv } from '@aws-lambda-powertools/commons/utils/env';
+import {
+  getNumberFromEnv,
+  getStringFromEnv,
+} from '@aws-lambda-powertools/commons/utils/env';
 
 const MCP_SERVER_NAME = 'powertools-for-aws-mcp' as const;
 
@@ -18,11 +21,20 @@ const CACHE_BASE_PATH = getStringFromEnv({
   defaultValue: join(tmpdir(), 'powertools-mcp'),
 });
 
+/**
+ * Threshold for search confidence out of 100.
+ */
+const SEARCH_CONFIDENCE_THRESHOLD = getNumberFromEnv({
+  key: 'SEARCH_CONFIDENCE_THRESHOLD',
+  defaultValue: 30,
+});
+
 export {
   MCP_SERVER_NAME,
   ALLOWED_DOMAIN,
   FETCH_TIMEOUT_MS,
   runtimes,
   POWERTOOLS_BASE_URL,
   CACHE_BASE_PATH,
+  SEARCH_CONFIDENCE_THRESHOLD,
 };

src/constants.ts

@@ -1,105 +1,36 @@
-import { join } from 'node:path';
-import { isNull } from '@aws-lambda-powertools/commons/typeutils';
 import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
-import { get as getFromCache, put as writeToCache } from 'cacache';
-import type { z } from 'zod';
-import { CACHE_BASE_PATH } from '../../constants.ts';
 import { logger } from '../../logger.ts';
 import { buildResponse } from '../shared/buildResponse.ts';
+import { fetchWithCache } from '../shared/fetchWithCache.ts';
 import { name as toolName } from './constants.ts';
-import { CacheError } from './errors.ts';
-import type { schema } from './schemas.ts';
-import { getRemotePage, getRemotePageETag } from './utils.ts';
+import type { ToolProps } from './types.ts';
 
 /**
  * Fetch a documentation page from remote or local cache.
  *
- * When using this function, we first check if the page is available in the local cache
- * by using the page url as the cache key prefix.
- *
- * If none is found, we fetch the page from the remote server and cache it locally,
- * then return its markdown content.
- *
- * If the local cache includes a potential match, we make a `HEAD` request to the remote server
- * and compare the ETag with the one stored in the local cache.
- *
- * If the ETag matches, we return the cached markdown content. If it doesn't match,
- * we fetch the entire page using a `GET` request and update the local cache with the new content.
+ * @see - {@link fetchWithCache | `fetchWithCache`} for the implementation details on caching and fetching.
  *
  * @param props - options for fetching a documentation page
- * @param props.pageUrl - the URL of the documentation page to fetch
+ * @param props.url - the URL of the documentation page to fetch
  */
-const tool = async (props: {
-  url: z.infer<typeof schema.url>;
-}): Promise<CallToolResult> => {
+const tool = async (props: ToolProps): Promise<CallToolResult> => {
   const { url } = props;
   logger.appendKeys({ tool: toolName });
   logger.appendKeys({ url: url.toString() });
 
-  const cachePath = join(CACHE_BASE_PATH, 'markdown-cache');
-  const cacheKey = url.pathname;
-  logger.debug('Generated cache key', { cacheKey });
-
   try {
-    const [cachedETagPromise, remoteETagPromise] = await Promise.allSettled([
-      getFromCache(cachePath, `${cacheKey}-etag`),
-      getRemotePageETag(url),
-    ]);
-    const cachedETag =
-      cachedETagPromise.status === 'fulfilled'
-        ? cachedETagPromise.value.data.toString()
-        : null;
-    const remoteETag =
-      remoteETagPromise.status === 'fulfilled' ? remoteETagPromise.value : null;
-
-    if (isNull(cachedETag) && isNull(remoteETag)) {
-      throw new CacheError(
-        'No cached ETag and remote ETag found, fetching remote page'
-      );
-    }
-
-    if (cachedETag === remoteETag) {
-      logger.debug('cached eTag matches, returning cached markdown');
-      try {
-        const cachedMarkdown = await getFromCache(cachePath, cacheKey);
-        return buildResponse({
-          content: cachedMarkdown.data.toString(),
-        });
-      } catch (error) {
-        throw new CacheError(
-          'Cached markdown not found even though ETag matches; cache may be corrupted'
-        );
-      }
-    }
-    throw new CacheError(
-      `ETag mismatch: local ${cachedETag} vs remote ${remoteETag}; fetching remote page`
-    );
+    return buildResponse({
+      content: await fetchWithCache({ url, contentType: 'text/markdown' }),
+    });
   } catch (error) {
-    if (error instanceof CacheError) {
-      logger.debug(error.message, { cacheKey });
-    }
-    try {
-      const { markdown, eTag: newEtag } = await getRemotePage(url);
-
-      await writeToCache(cachePath, `${cacheKey}-etag`, newEtag);
-      await writeToCache(cachePath, cacheKey, markdown);
-
-      return buildResponse({
-        content: markdown,
-      });
-    } catch (fetchError) {
-      logger.error('Failed to fetch remote page', {
-        error: fetchError,
-      });
-      return buildResponse({
-        content: `${(fetchError as Error).message}`,
-        isError: true,
-      });
-    }
+    return buildResponse({
+      content: `${(error as Error).message}`,
+      isError: true,
+    });
     /* v8 ignore start */
   } finally {
-    /* v8 ignore end */
-    logger.removeKeys(['url', 'tool']);
+    /* v8 ignore stop */
+    logger.removeKeys(['tool', 'url']);
   }
 };