feat: Add contextual documentation retrieval tool

Implements get_contextual_docs_tool for intelligent documentation
retrieval based on user context, code snippets, and error messages.

Features:
- Context-aware keyword extraction from text, code, and errors
- Intelligent relevance scoring with match explanations
- Troubleshooting tips for error messages
- Technology-specific filtering (mapbox-gl-js, iOS SDK, Android SDK)
- Suggested related topics
- Ranked results with excerpts and direct documentation links
- 1-hour caching for performance

Smarter than simple search - understands full context and provides
actionable, targeted documentation guidance.

Addresses: #70

Changes:
- Add GetContextualDocsTool implementation
- Register in toolRegistry.ts
- Add comprehensive test coverage (13 tests)
- Update CHANGELOG.md with feature details
- Update README.md with tool documentation and examples
- All 549 tests passing

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

Author: mattpodwysocki

CHANGELOG.md

@@ -1,5 +1,17 @@
 ## Unreleased
 
+### Features Added
+
+- **Contextual Documentation Tool**: New `get_contextual_docs_tool` provides intelligent documentation retrieval based on context (#70)
+  - Analyzes what you're working on, code snippets, and error messages
+  - Extracts keywords automatically from context, code, and errors
+  - Returns ranked, relevant documentation with explanations
+  - Provides troubleshooting tips for error messages
+  - Suggests related topics to explore
+  - Smarter than simple search - understands full context
+  - Technology-specific filtering (mapbox-gl-js, iOS SDK, Android SDK)
+  - 1-hour caching for performance
+
 ### Documentation
 
 - **PR Guidelines**: Added CHANGELOG requirement to CLAUDE.md (#67)

README.md

@@ -131,6 +131,25 @@ The `MAPBOX_ACCESS_TOKEN` environment variable is required. **Each tool requires
 
 📖 **[See more examples and interactive demo →](./docs/mapbox-docs-tool-demo.md)**
 
+**get_contextual_docs_tool** - Retrieve relevant Mapbox documentation based on your current context. This smart tool analyzes what you're working on, code snippets, and error messages to provide targeted, actionable documentation.
+
+**Features:**
+
+- Context-aware keyword extraction from descriptions, code, and errors
+- Intelligent relevance scoring with match explanations
+- Troubleshooting tips for error messages
+- Technology-specific filtering (mapbox-gl-js, iOS SDK, Android SDK)
+- Suggested related topics to explore
+- Ranked results with excerpts and direct links
+
+**Example prompts:**
+
+- "I'm trying to add custom markers with popups, here's my code: [snippet]"
+- "Getting this error: 'Style is not done loading' - what does it mean?"
+- "Working with mapbox-gl-js to show user location on a map"
+- "How do I handle rate limiting errors in the geocoding API?"
+- "Building a store locator with search functionality"
+
 ### Reference Tools
 
 **get_reference_tool** - Access static Mapbox reference documentation and schemas. This tool provides essential reference information that helps AI assistants understand Mapbox concepts and build correct styles and tokens.

src/tools/get-contextual-docs-tool/GetContextualDocsTool.input.schema.ts

@@ -0,0 +1,56 @@
+import { z } from 'zod';
+
+/**
+ * Input schema for GetContextualDocsTool
+ *
+ * This tool retrieves relevant Mapbox documentation based on the user's
+ * current context, including what they're working on, code snippets,
+ * and error messages.
+ */
+export const GetContextualDocsInputSchema = z.object({
+  context: z
+    .string()
+    .min(1)
+    .describe(
+      'Description of what the user is working on or trying to accomplish (e.g., "adding custom markers with popups")'
+    ),
+
+  codeSnippet: z
+    .string()
+    .optional()
+    .describe(
+      'Optional code snippet being worked with. Helps identify the specific APIs and patterns being used.'
+    ),
+
+  errorMessage: z
+    .string()
+    .optional()
+    .describe(
+      'Optional error message to help diagnose issues and find relevant troubleshooting documentation.'
+    ),
+
+  technology: z
+    .string()
+    .optional()
+    .describe(
+      'Specific SDK or platform being used (e.g., "mapbox-gl-js", "ios-sdk", "android-sdk")'
+    ),
+
+  limit: z
+    .number()
+    .int()
+    .min(1)
+    .max(10)
+    .optional()
+    .default(5)
+    .describe(
+      'Maximum number of documentation results to return (1-10, default: 5)'
+    )
+});
+
+/**
+ * Inferred TypeScript type for GetContextualDocsTool input
+ */
+export type GetContextualDocsInput = z.infer<
+  typeof GetContextualDocsInputSchema
+>;

src/tools/get-contextual-docs-tool/GetContextualDocsTool.output.schema.ts

@@ -0,0 +1,57 @@
+import { z } from 'zod';
+
+/**
+ * Schema for a single documentation result
+ */
+const DocResultSchema = z.object({
+  title: z.string().describe('Title of the documentation section'),
+  excerpt: z
+    .string()
+    .describe(
+      'Relevant excerpt from the documentation showing key information'
+    ),
+  category: z
+    .string()
+    .describe('Category of documentation (apis, sdks, guides, examples)'),
+  url: z.string().describe('Full URL to the documentation page'),
+  relevanceScore: z
+    .number()
+    .describe(
+      'Relevance score from 0-1 indicating how well this matches the context'
+    ),
+  matchReason: z
+    .string()
+    .optional()
+    .describe(
+      'Explanation of why this documentation is relevant to the context'
+    )
+});
+
+/**
+ * Output schema for GetContextualDocsTool
+ */
+export const GetContextualDocsOutputSchema = z.object({
+  results: z
+    .array(DocResultSchema)
+    .describe('Ranked list of relevant documentation sections'),
+  extractedKeywords: z
+    .array(z.string())
+    .describe('Key concepts extracted from the provided context'),
+  suggestedTopics: z
+    .array(z.string())
+    .optional()
+    .describe('Related topics the user might want to explore'),
+  troubleshootingTips: z
+    .array(z.string())
+    .optional()
+    .describe('Troubleshooting suggestions if an error message was provided'),
+  totalResults: z.number().describe('Total number of results found'),
+  context: z.string().describe('The original context provided')
+});
+
+/**
+ * Inferred TypeScript type for GetContextualDocsTool output
+ */
+export type GetContextualDocsOutput = z.infer<
+  typeof GetContextualDocsOutputSchema
+>;