feat: Add contextual documentation retrieval tool

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.

package.json

@@ -59,6 +59,7 @@
     "@opentelemetry/sdk-node": "^0.56.0",
     "@opentelemetry/sdk-trace-base": "^1.30.1",
     "@opentelemetry/semantic-conventions": "^1.30.1",
+    "linkedom": "^0.18.12",
     "zod": "^3.25.42"
   },
   "devDependencies": {
@@ -77,13 +78,13 @@
     "globals": "^16.3.0",
     "husky": "^9.0.0",
     "lint-staged": "^16.1.0",
+    "patch-package": "^8.0.1",
     "plop": "^4.0.1",
     "prettier": "^3.0.0",
     "tshy": "^3.0.2",
     "typescript": "^5.8.3",
     "typescript-eslint": "^8.42.0",
-    "vitest": "^3.2.4",
-    "patch-package": "^8.0.1"
+    "vitest": "^3.2.4"
   },
   "prettier": {
     "singleQuote": true,

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
+>;