feat: refactor to trade one look up module tool for the 50+ dynamically registered tools

Signed-off-by: Liran Tal <liran.tal@gmail.com>

Author: lirantal

src/bin/cli.ts

@@ -1,7 +1,6 @@
-#!/usr/bin/env node
 import { debuglog } from 'node:util'
 import { startServer } from 'src/main.ts'
 const debug = debuglog('mcp-server-nodejs-api-docs')
 
 debug('Starting Server...')
-startServer()
+startServer()

src/main.ts

@@ -27,4 +27,4 @@ export async function startServer (): Promise<void> {
     console.error('Fatal error during server transport init.')
     process.exit(1)
   }
-}
+}

src/resources/index.ts

@@ -10,7 +10,7 @@ import type { ReadResourceRequest } from '@modelcontextprotocol/sdk/types.js'
 const logger: Logger = initLogger()
 const cacheService = new CacheService()
 
-export async function initializeResources(server: Server): Promise<void> {
+export async function initializeResources (server: Server): Promise<void> {
   logger.info({ msg: 'Initializing resources...' })
 
   const resources = [

src/services/api-docs-service.ts

@@ -78,7 +78,7 @@ export class ApiDocsService {
     // Remove entries without Class or Method
     const originalCount = apiDocs.modules?.length
     apiDocs.modules = apiDocs.modules.filter(module =>
-      module?.classes?.length && module.classes.length > 0 || 
+      module?.classes?.length && module.classes.length > 0 ||
       module?.methods?.length && module.methods.length > 0
     )
     this.logger.info({ msg: `Modules count: ${originalCount}` })

src/services/cache-service.ts

@@ -13,7 +13,7 @@ export class CacheService {
   private logger: Logger
   private cache: Map<string, CacheEntry<any>>
 
-  constructor() {
+  constructor () {
     this.logger = initLogger()
     this.cache = new Map()
   }
@@ -29,7 +29,7 @@ export class CacheService {
   ): Promise<T> {
     const { ttlDays = 7 } = options
     const now = Date.now()
-    
+
     // Check if we have valid cached data
     const cached = this.cache.get(key)
     if (cached && cached.expiresAt > now) {
@@ -41,19 +41,19 @@ export class CacheService {
     this.logger.info({ msg: `Cache miss for key: ${key}, fetching fresh data...` })
     try {
       const data = await fetcher()
-      
+
       // Calculate expiration time
       const expiresAt = now + (ttlDays * 24 * 60 * 60 * 1000)
-      
+
       // Store in cache
       this.cache.set(key, { data, expiresAt })
-      
-      this.logger.info({ 
-        msg: `Cached data for key: ${key}`, 
+
+      this.logger.info({
+        msg: `Cached data for key: ${key}`,
         expiresAt: new Date(expiresAt).toISOString(),
-        ttlDays 
+        ttlDays
       })
-      
+
       return data
     } catch (error) {
       this.logger.error({ err: error, msg: `Failed to fetch data for key: ${key}` })
@@ -64,22 +64,22 @@ export class CacheService {
   /**
    * Convenience method for fetching HTTP resources with caching
    */
-  async fetchHttpWithCache(
+  async fetchHttpWithCache (
     url: string,
     options: CacheOptions & { responseType?: 'json' | 'text' } = {}
   ): Promise<any> {
     const { responseType = 'json', ...cacheOptions } = options
-    
+
     return this.fetchWithCache(
       url,
       async () => {
         this.logger.info({ msg: `Fetching HTTP resource: ${url}` })
         const response = await fetch(url)
-        
+
         if (!response.ok) {
           throw new Error(`HTTP error! status: ${response.status} ${response.statusText}`)
         }
-        
+
         const data = responseType === 'json' ? await response.json() : await response.text()
         this.logger.info({ msg: `Successfully fetched HTTP resource: ${url}` })
         return data
@@ -91,25 +91,25 @@ export class CacheService {
   /**
    * Clear a specific cache entry
    */
-  clearCache(key: string): void {
+  clearCache (key: string): void {
     this.cache.delete(key)
     this.logger.info({ msg: `Cleared cache for key: ${key}` })
   }
 
   /**
    * Clear all expired cache entries
    */
-  clearExpiredCache(): void {
+  clearExpiredCache (): void {
     const now = Date.now()
     let clearedCount = 0
-    
+
     for (const [key, entry] of this.cache.entries()) {
       if (entry.expiresAt <= now) {
         this.cache.delete(key)
         clearedCount++
       }
     }
-    
+
     if (clearedCount > 0) {
       this.logger.info({ msg: `Cleared ${clearedCount} expired cache entries` })
     }
@@ -118,10 +118,10 @@ export class CacheService {
   /**
    * Get cache statistics
    */
-  getCacheStats(): { size: number; keys: string[] } {
+  getCacheStats (): { size: number; keys: string[] } {
     return {
       size: this.cache.size,
       keys: Array.from(this.cache.keys())
     }
   }
-}
+}

src/services/docs-formatter-service.ts

@@ -33,7 +33,6 @@ interface FormattingOptions {
  * Service responsible for formatting Node.js API documentation into readable markdown content
  */
 export class DocsFormatter {
-  // eslint-disable-next-line no-useless-constructor
   constructor () {
     // Initialize any needed properties here
   }
@@ -56,6 +55,7 @@ export class DocsFormatter {
 
   formatModuleSummary (module: ApiModule): string {
     let content = `## ${module.displayName || module.textRaw} (${module.name})\n`
+    content += `Module name or Class name: \`${module.name}\`\n\n`
 
     if (
       (module.methods && module.methods.length > 0) ||
@@ -64,12 +64,12 @@ export class DocsFormatter {
       content += '### Methods\n'
 
       module?.methods?.forEach((method) => {
-          content += `#### ${method.textRaw}\n`
+        content += `#### ${method.textRaw}\n`
       })
 
       module?.modules?.forEach((submodules) => {
         submodules?.methods?.forEach((method) => {
-            content += `#### ${method.textRaw}\n`
+          content += `#### ${method.textRaw}\n`
         })
       })
     }

src/tools/index.ts

@@ -4,19 +4,23 @@ import {
   CallToolRequestSchema,
 } from '@modelcontextprotocol/sdk/types.js'
 
-import { createSearchTool, createModuleTools } from './tools-factory.ts'
+import { createSearchTool, createModulesTool } from './tools-factory.ts'
 
 export async function initializeTools (server: Server): Promise<void> {
   // Create the search tool
   const searchTool = await createSearchTool()
 
-  // Create individual module tools
-  const moduleTools = await createModuleTools()
+  // Refactor to avoid the `createModuleTools` that created a single tool for each
+  // module which resulted in potentially too many tools being registered (about 50)
+  // and instead create a single tool that can handle all modules by using a sort of
+  // look up method
+  // const moduleTools = await createModuleTools()
+  const modulesTool = await createModulesTool()
 
   // Combine all tools
   const tools = {
     [searchTool.name]: searchTool,
-    ...moduleTools
+    ...modulesTool
   }
 
   // Create tool list for MCP

src/tools/tools-factory.ts

@@ -10,6 +10,7 @@ interface ToolDefinition {
   inputSchema: {
     type: string
     properties: Record<string, any>
+    required?: string[]
   }
   handler: (params: Record<string, any>) => Promise<{ content: { type: string; text: string }[] }>
 }
@@ -44,6 +45,72 @@ export async function createSearchTool (): Promise<ToolDefinition> {
   }
 }
 
+/**
+ * One tool that serves documentation for all modules
+ *
+ * Instead of overwhelming the LLM with as many tools as there are core modules
+ * in Node.js, this creates a single tool that accepts modules information
+ * and returns their data as a response.
+ */
+export async function createModulesTool () {
+  const toolName = 'api-docs-module-description'
+  const toolDescription = 'Use this tool to retrieve Node.js API documentation for a specific module or class, including its methods and descriptions.'
+
+  const tools: ToolsDictionary = {}
+
+  const tool: ToolDefinition = {
+    name: toolName,
+    description: toolDescription,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        module: {
+          type: 'string',
+          description: 'The module or class name to retrieve Node.js API documentation for',
+        },
+        method: {
+          type: 'string',
+          description: 'The method name to retrieve Node.js API documentation for',
+        },
+      },
+      required: ['module'],
+    },
+    async handler (params) {
+      logger.info({ msg: `Tool execution started: ${toolName}`, params })
+      try {
+        // TBD extract the module or class name out of all modules documentation
+        const { modules } = await apiDocsService.getApiDocsModules()
+
+        // @TODO the tool only uses the module name to find a matching module
+        // and doesn't match against the method name or the class name
+        // probably good enough for results but open to improvements, especially
+        // if there's more data points around methods and classes that should
+        // be returned
+        const module = modules.find((mod) => apiDocsService.normalizeModuleName(mod.name) === params.module)
+        if (!module) {
+          return {
+            content: [{ type: 'text', text: `Module not found: ${params.module}\n\nMaybe you spelled the module name wrong?` }],
+          }
+        }
+
+        const content = await apiDocsService.getFormattedModuleDoc(module, { class: params.module, method: params.method })
+        logger.info({ msg: `Tool execution successful: ${toolName}` })
+        return { content: [{ type: 'text', text: content }] }
+      } catch (error) {
+        logger.error({
+          err: error,
+          params,
+          msg: `Tool execution failed: ${toolName}`,
+        })
+        throw error
+      }
+    },
+  }
+
+  tools[toolName] = tool
+  return tools
+}
+
 export async function createModuleTools () {
   const tools: ToolsDictionary = {}
   const { modules } = await apiDocsService.getApiDocsModules()