MCP File System

Implementation Reference

• src/index.ts:187-221 (handler)

  The asynchronous handler function for the 'search_files' tool. It validates the path, recursively traverses the directory tree, skips excluded patterns, collects files matching the pattern by name (case-insensitive substring match), and returns a list of matching full paths or an error message.

  async ({ path: dirPath, pattern, excludePatterns = [] }: { path: string, pattern: string, excludePatterns?: string[] }) => {
      try {
          const validPath = validatePath(dirPath);
          const results: string[] = [];
  
          async function searchDir(currentPath: string) {
              const entries = await fs.readdir(currentPath, { withFileTypes: true });
              
              for (const entry of entries) {
                  const fullPath = path.join(currentPath, entry.name);
                  
                  // Check exclude patterns
                  if (excludePatterns.some(exclude => 
                      fullPath.toLowerCase().includes(exclude.toLowerCase()))) {
                      continue;
                  }
  
                  // Check if name matches pattern
                  if (entry.name.toLowerCase().includes(pattern.toLowerCase())) {
                      results.push(fullPath);
                  }
  
                  // Recursively search directories
                  if (entry.isDirectory()) {
                      await searchDir(fullPath);
                  }
              }
          }
  
          await searchDir(validPath);
          return { content: [{ type: 'text', text: results.join('\n') }] };
      } catch (error: any) {
          return { content: [{ type: 'text', text: `Error searching files: ${error.message}` }] };
      }
  }

• src/index.ts:186-186 (schema)

  Zod schema for 'search_files' tool inputs: required 'path' (starting directory), 'pattern' (search string), optional 'excludePatterns' array.

  { path: z.string().describe("Starting directory"), pattern: z.string().describe("Search pattern"), excludePatterns: z.array(z.string()).optional().describe("Patterns to exclude") },

• src/index.ts:184-185 (registration)

  Registration of the 'search_files' tool on the MCP server instance using server.tool(name, schema, handler).

  server.tool(
      "search_files",