docs/src/components/layout/custom-search-dialog.tsx (5)

191-191: Fix browser typing for setTimeout ref (avoid NodeJS.Timeout).

Typing useRef<NodeJS.Timeout>() in a client component can cause TS friction in the browser (setTimeout returns a number). Prefer ReturnType.

-  const searchTimeoutRef = useRef<NodeJS.Timeout>();
+  const searchTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);

---

122-137: Harden PlatformBadge against unknown platforms (prevent undefined styles/text).

When platform is not in PLATFORM_COLORS/NAMES, color/name become undefined resulting in invalid CSS. Add safe fallbacks.

-  const color = PLATFORM_COLORS[platform as keyof typeof PLATFORM_COLORS];
-  const name = PLATFORM_NAMES[platform as keyof typeof PLATFORM_NAMES];
+  const fallbackColor = '#64748B'; // slate-500
+  const color = PLATFORM_COLORS[platform as keyof typeof PLATFORM_COLORS] ?? fallbackColor;
+  const name =
+    PLATFORM_NAMES[platform as keyof typeof PLATFORM_NAMES] ??
+    (platform ? platform.charAt(0).toUpperCase() + platform.slice(1) : 'Unknown');

---

43-48: Avoid defaulting to 'api' when platform is undetectable.

Defaulting to 'api' risks misclassification and odd grouping. Prefer 'all' (or 'unknown') and handle it in grouping.

 function extractPlatformFromUrl(url: string): string {
   if (url.startsWith('/api/')) return 'api';
   const match = url.match(/\/docs\/([^\/]+)/);
-  const platform = match?.[1] || 'api';
-  return platform;
+  const platform = match?.[1];
+  return platform ?? 'all';
 }

Optionally, in groupResultsByPage, when platform === 'all', fall back to the page URL sans hash as the baseUrl.

---

316-323: Use Next.js router for navigation on Enter (avoid full page reload).

Use router.push instead of assigning window.location.href for smoother SPA navigation.

-import { usePathname } from 'next/navigation';
+import { usePathname, useRouter } from 'next/navigation';
...
 export function CustomSearchDialog({ open, onOpenChange }: CustomSearchDialogProps) {
+  const router = useRouter();
...
       case 'Enter': {
         if (!dropdownOpen) {
           e.preventDefault();
           const selectedResult = flatResults[selectedIndex];
-          window.location.href = selectedResult.url;
+          router.push(selectedResult.url);
           onOpenChange(false);
         }
         break;
       }

Also applies to: 5-6, 180-190

---

271-281: Avoid in-place sort mutating derived data (safer immutability).

Sorting filteredResults in place can surprise future readers. Copy before sorting.

-    filteredResults = filteredResults.sort((a, b) => {
+    filteredResults = [...filteredResults].sort((a, b) => {

docs/src/app/api/internal/[transport]/route.ts (2)

121-245: Good: Useful MCP tool with ranking + snippets. Consider perf and result shape improvements.

Sequentially reading every content file on each query will not scale. Consider caching/pre-indexing, async pooling, or limiting file reads once score > 0 from title/desc and early-continue after pushing.

If helpful, I can sketch a lightweight in-memory inverted index builder for dev and a build-time index for prod.

---

350-371: Expose search_docs in capabilities for proper tool introspection.

The tool is registered, but not advertised in the capabilities payload. Add it for clients that enumerate tools.

       tools: {
         listAvailableDocs: {
           description:
             "Use this tool to learn about what Stack Auth is, available documentation, and see if you can use it for what you're working on. It returns a list of all available Stack Auth Documentation pages.",
         },
         getDocById: {
           description:
             "Use this tool to retrieve a specific Stack Auth Documentation page by its ID. It gives you the full content of the page so you can know exactly how to use specific Stack Auth APIs. Whenever using Stack Auth, you should always check the documentation first to have the most up-to-date information. When you write code using Stack Auth documentation you should reference the content you used in your comments.",
           parameters: {
             type: "object",
             properties: {
               id: {
                 type: "string",
                 description: "The ID of the documentation page to retrieve.",
               },
             },
             required: ["id"],
           },
         },
+        searchDocs: {
+          description:
+            "Search through all Stack Auth documentation including API docs, guides, and examples. Returns ranked results with snippets and relevance scores.",
+          parameters: {
+            type: "object",
+            properties: {
+              query: { type: "string", description: "The search query to find relevant documentation" },
+              limit: { type: "number", description: "Maximum number of results to return (default: 10)" },
+            },
+            required: ["query"],
+          },
+        },
       },

docs/src/app/api/search/route.ts (3)

107-116: Include '/docs/javascript/' in platform priority mapping.

UI supports both 'js' and 'javascript'. Add the alias to keep ordering consistent.

   if (url.includes('/docs/js/')) return 70;
+  if (url.includes('/docs/javascript/')) return 70;

---

135-141: Optional: stable sort to preserve MCP relevance on ties.

Use a tiebreaker preserving original order to avoid reordering equal-priority items.

-    const sortedResults = filteredResults.sort((a, b) => {
-      return getPlatformPriority(b.url) - getPlatformPriority(a.url);
-    });
+    const sortedResults = filteredResults
+      .map((r, i) => ({ r, i }))
+      .sort((x, y) => {
+        const d = getPlatformPriority(y.r.url) - getPlatformPriority(x.r.url);
+        return d !== 0 ? d : x.i - y.i; // stable
+      })
+      .map(({ r }) => r);

---

90-97: Type fidelity: preserve MCP ‘type’ when possible.

All non-api results are forced to 'page', losing heading/text nuance. If MCP returns richer types later, pass them through.

-          type: type === 'api' ? 'api' : 'page',
+          type: (type === 'api' || type === 'heading' || type === 'text') ? (type as any) : 'page',

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

docs/src/app/api/internal/[transport]/route.ts (2)

137-147: Expose search_docs in capabilities and align tool names.

Capabilities list omits search_docs and uses camelCase names that don’t match registered tools; clients may not discover tools.

Add/update capabilities (outside this hunk):

   capabilities: {
     tools: {
-      listAvailableDocs: {
+      list_available_docs: {
         description:
           "Use this tool to learn about what Stack Auth is, available documentation, and see if you can use it for what you're working on. It returns a list of all available Stack Auth Documentation pages.",
       },
+      search_docs: {
+        description:
+          "Search through all Stack Auth documentation including API docs, guides, and examples. Returns ranked results with snippets and relevance scores.",
+        parameters: {
+          type: "object",
+          properties: {
+            search_query: { type: "string", description: "The search query to find relevant documentation" },
+            result_limit: { type: "number", description: "Maximum number of results to return (default: 50)" }
+          },
+          required: ["search_query"]
+        }
+      },
-      getDocById: {
+      get_docs_by_id: {
         description:
           "Use this tool to retrieve a specific Stack Auth Documentation page by its ID. It gives you the full content of the page so you can know exactly how to use specific Stack Auth APIs. Whenever using Stack Auth, you should always check the documentation first to have the most up-to-date information. When you write code using Stack Auth documentation you should reference the content you used in your comments.",
         parameters: {
           type: "object",
           properties: {
             id: {
               type: "string",
               description: "The ID of the documentation page to retrieve.",
             },
           },
           required: ["id"],
         },
       },
-      getStackAuthSetupInstructions: {
+      get_stack_auth_setup_instructions: {
         description:
           "Use this tool when the user wants to set up Stack Auth in a new project. It provides step-by-step instructions for installing and configuring Stack Auth authentication, including environment setup, file scaffolding, and verification steps.",
         parameters: {
           type: "object",
           properties: {},
           required: [],
         },
       },
     },
   },

---

187-244: Consider parallelizing reads with bounded concurrency.

Loop does N sequential reads; for many pages this is slow. Use a pool (e.g., 8) with Promise.allSettled.

If helpful, I can provide a small in-file concurrency helper.

docs/src/app/api/search/route.ts (4)

68-96: Preserve MCP relevance by parsing Score and carrying it through.

You currently drop score and later sort only by platform. Parse “Score:” and include it.

-      let snippet = '';
+      let snippet = '';
+      let score: number | undefined = undefined;
...
-        } else if (line.startsWith('Snippet: ')) {
+        } else if (line.startsWith('Snippet: ')) {
           snippet = line.substring(9);
+        } else if (line.startsWith('Score: ')) {
+          const n = Number(line.substring(7).trim());
+          if (Number.isFinite(n)) score = n;
         }
...
-      if (title && url) {
+      if (title && url) {
         results.push({
           id: `${url}-${type}`,
-          type: type === 'api' ? 'api' : 'page',
-          content: snippet || description || title,
+          type: type === 'api' ? 'api' : 'page',
+          content: snippet || description || title,
+          // @ts-expect-error: add optional field; update type as per comment below
+          score,
           url: url,
         });
       }

Also update type (outside this hunk):

 type SearchResult = {
   id: string,
   type: 'page' | 'heading' | 'text' | 'api',
   content: string,
   url: string,
+  score?: number,
 };

---

138-140: Use score as primary sort, platform as tiebreaker.

-    const sortedResults = filteredResults.sort((a, b) => {
-      return getPlatformPriority(b.url) - getPlatformPriority(a.url);
-    });
+    const sortedResults = filteredResults.sort((a, b) => {
+      const scoreDiff = (b.score ?? 0) - (a.score ?? 0);
+      if (scoreDiff !== 0) return scoreDiff;
+      return getPlatformPriority(b.url) - getPlatformPriority(a.url);
+    });

---

135-136: Tighten admin filter to avoid false positives.

Match '/api/admin/' prefix only.

-    const filteredResults = results.filter(result => !result.url.startsWith('/api/admin'));
+    const filteredResults = results.filter(result => !result.url.startsWith('/api/admin/'));

---

58-66: Fragile text parsing from MCP; prefer JSON payload.

Switch search_docs to return structured JSON in content[0].text to avoid parsing drift.

I can provide coordinated patches in both files to emit/consume JSON if you’d like.

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

docs/src/app/api/internal/[transport]/route.ts (3)

155-244: Avoid N× awaited disk reads on the hot path; use limited concurrency or pre‑index/cache.

Current per-page await readFile can bottleneck search.

• Option A: Pre-index content once (startup) and reuse in-memory text for searches.
• Option B: Use a small concurrency pool (e.g., 8) for file reads; push tasks and await with a limiter.
• Option C: Cache normalized textContent in a Map keyed by file path+mtime.

---

15-20: Make EnhancedAPIPage parsing robust to multiline props.

The current regex fails when props span lines.

-  const componentMatch = content.match(/<EnhancedAPIPage\s+([^>]+)>/);
+  const componentMatch = content.match(/<EnhancedAPIPage\b([\s\S]*?)>/);
   if (componentMatch) {
     const props = componentMatch[1];
     const documentMatch = props.match(/document=\{"([^"]+)"\}/);
-    const operationsMatch = props.match(/operations=\{(\[[^\]]+\])\}/);
+    const operationsMatch = props.match(/operations=\{(\[[\s\S]*?\])\}/);

---

435-438: Gate verbose logs by environment.

Avoid noisy logs in production.

-    verboseLogs: true,
+    verboseLogs: process.env.NODE_ENV !== "production",

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

docs/src/app/api/internal/[transport]/route.ts (5)

141-142: Address parameter naming convention.

Past reviews flagged that search_query and result_limit should follow the project's REST API naming convention. Since this has been previously raised, please refer to those comments for details.

---

145-149: Privacy concern with logging raw search queries.

A previous review flagged that capturing raw search_query values could raise privacy/compliance concerns. Consider logging metadata (e.g., query_length) instead of the actual query text.

---

181-185: Guard against undefined TOC.

A previous review flagged that page.data.toc might be undefined, causing a runtime error. This issue remains unaddressed.

---

189-191: Path traversal vulnerability in file reading.

Previous reviews flagged two critical security/reliability concerns here:

1. Path traversal: page.file.path is used directly without validation
2. Missing runAsynchronously wrapper for the async file read

Both issues remain unaddressed.

---

154-244: Sequential file reads may impact performance.

A previous review noted that file reads are performed sequentially in the loop. For many pages, consider parallelizing with Promise.all() to improve performance.

docs/src/app/api/internal/[transport]/route.ts (1)

142-142: Add Zod validation bounds for result_limit.

The schema describes a default of 50 but doesn't enforce it via .default(50) or validate reasonable bounds. Consider adding .int().min(1).max(100).default(50) to prevent invalid values and make the default explicit in the schema.

Apply this diff:

-        result_limit: z.number().optional().describe("Maximum number of results to return (default: 50)")
+        result_limit: z.number().int().min(1).max(100).default(50).describe("Maximum number of results to return (default: 50)")

Then remove the handler default to rely on the schema:

-      async ({ search_query, result_limit = 50 }) => {
+      async ({ search_query, result_limit }) => {

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro