Filesystem MCP Server

Instructions

Implementation Reference

• src/handlers/utility-handlers.ts:68-87 (handler)

  Main handler function that executes the tool: parses input arguments using the schema, validates the starting path, calls the helper function findFilesByExtension, and returns the list of matching files or a no-match message.

  export async function handleFindFilesByExtension(
    args: unknown,
    allowedDirectories: string[],
    symlinksMap: Map<string, string>,
    noFollowSymlinks: boolean
  ) {
    const parsed = parseArgs(FindFilesByExtensionArgsSchema, args, 'find_files_by_extension');
    const { path: startPath, extension, excludePatterns, maxDepth, maxResults } = parsed;
    const validPath = await validatePath(startPath, allowedDirectories, symlinksMap, noFollowSymlinks);
    const results = await findFilesByExtension(
      validPath,
      extension,
      excludePatterns,
      maxDepth,
      maxResults
    );
    return {
      content: [{ type: "text", text: results.length > 0 ? results.join("\n") : "No matching files found" }],
    };
  }

• src/schemas/utility-operations.ts:23-38 (schema)

  TypeBox schema definition for the tool's input arguments, including path, extension, optional excludePatterns, maxDepth, and maxResults. Also exports the corresponding TypeScript type.

  export const FindFilesByExtensionArgsSchema = Type.Object({
    path: Type.String(),
    extension: Type.String({ description: 'File extension to search for (e.g., "xml", "json", "ts")' }),
    excludePatterns: Type.Optional(
      Type.Array(Type.String(), { default: [] })
    ),
    maxDepth: Type.Integer({
      minimum: 1,
      description: 'Maximum directory depth to search. Must be a positive integer. Handler default: 2.'
    }),
    maxResults: Type.Integer({
      minimum: 1,
      description: 'Maximum number of results to return. Must be a positive integer. Handler default: 10.'
    })
  });
  export type FindFilesByExtensionArgs = Static<typeof FindFilesByExtensionArgsSchema>;

• src/utils/file-utils.ts:92-157 (helper)

  Core utility function that recursively searches for files with the given extension starting from rootPath, respecting maxDepth, maxResults, and excludePatterns using minimatch.

  export async function findFilesByExtension(
    rootPath: string,
    extension: string,
    excludePatterns: string[] = [],
    maxDepth: number = 2, // Default depth
    maxResults: number = 10 // Default results
  ): Promise<ReadonlyArray<string>> {
    const results: string[] = [];
    
    // Normalize the extension (remove leading dot if present)
    let normalizedExtension = extension.toLowerCase();
    if (normalizedExtension.startsWith('.')) {
      normalizedExtension = normalizedExtension.substring(1);
    }
    
    async function searchDirectory(currentPath: string, currentDepth: number) {
      // Stop if max depth is reached
      if (currentDepth >= maxDepth) {
        return;
      }
      
      // Stop if max results are reached
      if (results.length >= maxResults) {
        return;
      }
      const entries = await fsPromises.readdir(currentPath, { withFileTypes: true });
  
      for (const entry of entries) {
        const fullPath = path.join(currentPath, entry.name);
  
        // Check if path matches any exclude pattern
        const relativePath = path.relative(rootPath, fullPath);
        const shouldExclude = excludePatterns.some(pattern => {
          const globPattern = pattern.includes('*') ? pattern : `**/${pattern}/**`;
          return minimatch(relativePath, globPattern, { dot: true });
        });
  
        if (shouldExclude) {
          continue;
        }
  
        if (entry.isFile()) {
          // Check if file has the requested extension
          const fileExtension = path.extname(entry.name).toLowerCase().substring(1);
          if (fileExtension === normalizedExtension) {
            if (results.length < maxResults) {
              results.push(fullPath);
            }
            // Check again if max results reached after adding
            if (results.length >= maxResults) {
              return; // Stop searching this branch
            }
          }
        } else if (entry.isDirectory()) {
          // Recursively search subdirectories
          // Check results length before recursing
          if (results.length < maxResults) {
            await searchDirectory(fullPath, currentDepth + 1);
          }
        }
      }
    }
  
    await searchDirectory(rootPath, 0); // Start search at depth 0
    return results;
  }

• index.ts:238-244 (registration)

  Registration of the tool handler in the toolHandlers object, mapping 'find_files_by_extension' to the handleFindFilesByExtension function with server context parameters.

  find_files_by_extension: (a: unknown) =>
    handleFindFilesByExtension(
      a,
      allowedDirectories,
      symlinksMap,
      noFollowSymlinks,
    ),

• index.ts:310-310 (registration)

  Tool metadata registration in the allTools array, defining the name and description used when adding the tool to the MCP server.

  { name: "find_files_by_extension", description: "Find files by extension" },