file_list

Instructions

Implementation Reference

• src/tools/file-operations.ts:175-281 (handler)

  The registerFileListTool function registers and implements the `file_list` MCP tool. It reads a directory, supports recursive listing with depth control, filters by extension, skips hidden files and node_modules, and returns structured JSON with file/directory metadata.

  export function registerFileListTool(server: McpServer): void {
    server.tool(
      "file_list",
      `List files and directories at a given path.
  
  Features:
    - List contents of any directory
    - Recursive listing with configurable depth
    - Filter results by file extension
    - Returns file sizes and types
  
  Use cases:
    - Exploring project structures
    - Finding specific file types
    - Auditing directory contents`,
      {
        dirPath: z
          .string()
          .describe("Path to the directory to list (defaults to current directory)."),
        recursive: z
          .boolean()
          .default(false)
          .describe("Whether to list subdirectories recursively."),
        extension: z
          .string()
          .optional()
          .describe("Optional file extension filter (e.g., '.ts', '.json')."),
      },
      async ({ dirPath, recursive, extension }) => {
        try {
          const resolvedPath = path.resolve(dirPath || ".");
          const entries: Array<{
            name: string;
            path: string;
            type: "file" | "directory";
            size?: number;
          }> = [];
  
          async function walk(currentPath: string, depth: number): Promise<void> {
            const MAX_DEPTH = 10;
            if (depth > MAX_DEPTH) return;
  
            const items = await fs.readdir(currentPath, {
              withFileTypes: true,
            });
  
            for (const item of items) {
              // Skip hidden files and node_modules
              if (item.name.startsWith(".") || item.name === "node_modules") {
                continue;
              }
  
              const fullPath = path.join(currentPath, item.name);
              const entry: (typeof entries)[number] = {
                name: item.name,
                path: fullPath,
                type: item.isDirectory() ? "directory" : "file",
              };
  
              if (item.isFile()) {
                if (extension && !item.name.endsWith(extension)) continue;
                const stat = await fs.stat(fullPath);
                entry.size = stat.size;
              }
  
              entries.push(entry);
  
              if (item.isDirectory() && recursive) {
                await walk(fullPath, depth + 1);
              }
            }
          }
  
          await walk(resolvedPath, 0);
  
          return {
            content: [
              {
                type: "text" as const,
                text: JSON.stringify(
                  {
                    path: resolvedPath,
                    totalEntries: entries.length,
                    files: entries.filter((e) => e.type === "file").length,
                    directories: entries.filter((e) => e.type === "directory").length,
                    entries,
                  },
                  null,
                  2
                ),
              },
            ],
          };
        } catch (err: any) {
          return {
            content: [
              {
                type: "text" as const,
                text: `File List Error: ${err.message}`,
              },
            ],
            isError: true,
          };
        }
      }
    );
  }

• src/tools/file-operations.ts:190-202 (schema)

  Zod schema defining the input parameters: dirPath (string, required), recursive (boolean, default false), extension (optional string filter).

  {
    dirPath: z
      .string()
      .describe("Path to the directory to list (defaults to current directory)."),
    recursive: z
      .boolean()
      .default(false)
      .describe("Whether to list subdirectories recursively."),
    extension: z
      .string()
      .optional()
      .describe("Optional file extension filter (e.g., '.ts', '.json')."),
  },

• src/index.ts:49-49 (registration)

  The tool is registered on the MCP server in the McpToolkitServer.registerTools() method via registerFileListTool(this.server).

  registerFileListTool(this.server);

• src/utils/helpers.ts:1-35 (helper)

  Shared helper types (ToolResult) and utility functions (textResult, errorResult, jsonResult) used across all tool handlers.

  /**
   * Shared utility types and helpers for MCP Toolkit Server tools.
   */
  
  /** Standard success response shape returned by tool handlers. */
  export interface ToolResult {
    content: Array<{ type: "text"; text: string }>;
    isError?: boolean;
  }
  
  /** Helper to build a success text response. */
  export function textResult(text: string): ToolResult {
    return { content: [{ type: "text" as const, text }] };
  }
  
  /** Helper to build an error text response. */
  export function errorResult(message: string): ToolResult {
    return {
      content: [{ type: "text" as const, text: message }],
      isError: true,
    };
  }
  
  /** Helper to JSON-stringify and wrap in a text result. */
  export function jsonResult(data: unknown, pretty = true): ToolResult {
    return {
      content: [
        {
          type: "text" as const,
          text: JSON.stringify(data, null, pretty ? 2 : 0),
        },
      ],
    };
  }