Add documentation search tool for AI-powered doc discovery

CHANGELOG.md

@@ -1,5 +1,15 @@
 ## Unreleased
 
+### Features Added
+
+- **Documentation Search Tool**: Added AI-powered search for Mapbox documentation (#68)
+  - New `search_mapbox_docs_tool` enables targeted documentation queries
+  - Returns ranked, relevant documentation sections instead of entire corpus
+  - Supports filtering by category (apis, sdks, guides, examples)
+  - Implements caching (1 hour TTL) for performance
+  - Follows Google Developer Knowledge API pattern for better AI assistance
+  - Includes comprehensive test suite (12 tests)
+
 ### Documentation
 
 - **PR Guidelines**: Added CHANGELOG requirement to CLAUDE.md (#67)

src/tools/search-mapbox-docs-tool/SearchMapboxDocsTool.input.schema.ts

@@ -0,0 +1,35 @@
+import { z } from 'zod';
+
+/**
+ * Input schema for SearchMapboxDocsTool
+ *
+ * Enables AI-powered search of Mapbox documentation for specific topics,
+ * providing targeted, relevant documentation instead of loading entire corpus.
+ */
+export const SearchMapboxDocsInputSchema = z.object({
+  query: z
+    .string()
+    .min(1)
+    .describe(
+      'Search query for finding relevant Mapbox documentation (e.g., "geocoding rate limits", "custom markers")'
+    ),
+  category: z
+    .enum(['apis', 'sdks', 'guides', 'examples', 'all'])
+    .optional()
+    .describe(
+      'Filter results by documentation category: "apis" (REST APIs), "sdks" (Mobile/Web SDKs), "guides" (tutorials/how-tos), "examples" (code samples), or "all" (default)'
+    ),
+  limit: z
+    .number()
+    .int()
+    .min(1)
+    .max(20)
+    .optional()
+    .default(5)
+    .describe('Maximum number of results to return (default: 5, max: 20)')
+});
+
+/**
+ * Inferred TypeScript type for SearchMapboxDocsTool input
+ */
+export type SearchMapboxDocsInput = z.infer<typeof SearchMapboxDocsInputSchema>;

src/tools/search-mapbox-docs-tool/SearchMapboxDocsTool.output.schema.ts

@@ -0,0 +1,56 @@
+import { z } from 'zod';
+
+/**
+ * Schema for a single search result
+ */
+export const SearchResultSchema = z.object({
+  title: z.string().describe('Title or heading of the documentation section'),
+  excerpt: z
+    .string()
+    .describe('Relevant excerpt or snippet from the documentation'),
+  category: z
+    .string()
+    .describe('Category of the result (apis, sdks, guides, examples)'),
+  url: z
+    .string()
+    .optional()
+    .describe('Link to full documentation (if available)'),
+  relevanceScore: z
+    .number()
+    .min(0)
+    .max(1)
+    .describe('Relevance score from 0 to 1')
+});
+
+/**
+ * Output schema for SearchMapboxDocsTool
+ *
+ * Returns an array of ranked, relevant documentation sections matching the search query.
+ */
+export const SearchMapboxDocsOutputSchema = z.object({
+  results: z
+    .array(SearchResultSchema)
+    .describe('Array of matching documentation sections, ranked by relevance'),
+  query: z.string().describe('The original search query'),
+  totalResults: z
+    .number()
+    .int()
+    .min(0)
+    .describe('Total number of results found (before limit applied)'),
+  category: z
+    .string()
+    .optional()
+    .describe('Category filter that was applied (if any)')
+});
+
+/**
+ * Type inference for SearchMapboxDocsOutput
+ */
+export type SearchMapboxDocsOutput = z.infer<
+  typeof SearchMapboxDocsOutputSchema
+>;
+
+/**
+ * Type inference for a single search result
+ */
+export type SearchResult = z.infer<typeof SearchResultSchema>;