Powertools MCP Search Server

Instructions

Implementation Reference

• src/tools/fetchDocPage/tool.ts:16-35 (handler)

  The main handler function for the 'fetch_doc_page' tool. It takes a URL, fetches the documentation page content using `fetchWithCache`, logs the operation, handles errors, and returns a `CallToolResult`.

  const tool = async (props: ToolProps): Promise<CallToolResult> => {
    const { url } = props;
    logger.appendKeys({ tool: toolName });
    logger.appendKeys({ url: url.toString() });
  
    try {
      return buildResponse({
        content: await fetchWithCache({ url, contentType: 'text/markdown' }),
      });
    } catch (error) {
      return buildResponse({
        content: `${(error as Error).message}`,
        isError: true,
      });
      /* v8 ignore start */
    } finally {
      /* v8 ignore stop */
      logger.removeKeys(['tool', 'url']);
    }
  };

• src/tools/fetchDocPage/schemas.ts:12-47 (schema)

  Zod schema for input validation and transformation of the URL parameter, ensuring it matches allowed domains, runtimes, and versions, and appending '/index.md'.

  const schema = {
    url: z
      .string()
      .url()
      .refine((url) => {
        const parsedUrl = new URL(url);
        if (parsedUrl.hostname !== ALLOWED_DOMAIN) {
          return false;
        }
        const pathParts = parsedUrl.pathname.split('/').filter(Boolean);
        const runtime = pathParts[1];
        if (!runtimes.includes(runtime as (typeof runtimes)[number])) {
          return false;
        }
        if (
          runtime === 'typescript' ||
          runtime === 'python' ||
          runtime === 'java'
        ) {
          const version = pathParts[2];
          const isValidSemver = /^\d+\.\d+\.\d+$/.test(version);
          const isLatest = version === 'latest';
          if (isValidSemver === false && isLatest === false) {
            return false;
          }
        }
  
        return true;
      })
      .transform((url) => {
        const parsedUrl = new URL(url);
        parsedUrl.pathname = parsedUrl.pathname.replace(/\/$/, '');
        parsedUrl.pathname = `${parsedUrl.pathname}/index.md`;
        return parsedUrl;
      }),
  };

• src/server.ts:30-35 (registration)

  Registration of the 'fetch_doc_page' tool with the MCP server using `server.tool()`, providing name, description, input schema, and handler.

  server.tool(
    fetchDocPageName,
    fetchDocPageDescription,
    fetchDocPageInputSchema,
    fetchDocPage
  );

• src/tools/fetchDocPage/constants.ts:1-6 (helper)

  Constants defining the tool name 'fetch_doc_page' and its description.

  const name = 'fetch_doc_page' as const;
  const description =
    'Fetches the content of a Powertools documentation page and returns it as markdown.' +
    'Use this after finding relevant pages with search_docs to get detailed information.';
  
  export { name, description };