Open MCP Server

Implementation Reference

• src/tools/file-tools.ts:94-111 (handler)

  The handler function that executes the list_directory tool logic: validates the directory path, recursively lists files/directories using the helper function, and returns the formatted list as text content.

  async ({ path: dirPath, includeHidden, recursive }) => {
    return wrapToolExecution(async () => {
      const validatedPath = await validatePathExists(dirPath);
      const results: string[] = [];
  
      await listDirectoryRecursive(validatedPath, "", includeHidden, recursive, results);
  
      return {
        content: [{
          type: "text" as const,
          text: results.length > 0 ? results.join("\n") : "Directory is empty"
        }]
      };
    }, {
      errorCode: ERROR_CODES.FILE_OPERATION,
      context: "Failed to list directory"
    });
  }

• src/tools/file-tools.ts:89-93 (schema)

  Zod input schema defining parameters for the list_directory tool: path (required string), includeHidden (optional boolean), recursive (optional boolean).

  {
    path: z.string().min(1, "Path is required"),
    includeHidden: z.boolean().optional().default(DEFAULTS.INCLUDE_HIDDEN_FILES),
    recursive: z.boolean().optional().default(DEFAULTS.RECURSIVE_SEARCH)
  },

• src/tools/file-tools.ts:87-113 (registration)

  Registers the list_directory tool on the MCP server using server.tool(), including schema and handler.

  function registerListDirectory(server: McpServer): void {
    server.tool("list_directory",
      {
        path: z.string().min(1, "Path is required"),
        includeHidden: z.boolean().optional().default(DEFAULTS.INCLUDE_HIDDEN_FILES),
        recursive: z.boolean().optional().default(DEFAULTS.RECURSIVE_SEARCH)
      },
      async ({ path: dirPath, includeHidden, recursive }) => {
        return wrapToolExecution(async () => {
          const validatedPath = await validatePathExists(dirPath);
          const results: string[] = [];
  
          await listDirectoryRecursive(validatedPath, "", includeHidden, recursive, results);
  
          return {
            content: [{
              type: "text" as const,
              text: results.length > 0 ? results.join("\n") : "Directory is empty"
            }]
          };
        }, {
          errorCode: ERROR_CODES.FILE_OPERATION,
          context: "Failed to list directory"
        });
      }
    );
  }

• src/tools/file-tools.ts:118-142 (helper)

  Recursive helper function that traverses directories, filters hidden files if not included, and collects file/directory listings with prefixes.

  async function listDirectoryRecursive(
    currentPath: string,
    baseRelative: string,
    includeHidden: boolean,
    recursive: boolean,
    results: string[]
  ): Promise<void> {
    const entries = await readdir(currentPath, { withFileTypes: true });
  
    for (const entry of entries) {
      if (!includeHidden && entry.name.startsWith('.')) {
        continue;
      }
  
      const relativePath = path.join(baseRelative, entry.name);
      const fullPath = path.join(currentPath, entry.name);
  
      const prefix = entry.isDirectory() ? "[DIR]" : "[FILE]";
      results.push(`${prefix} ${relativePath}`);
  
      if (recursive && entry.isDirectory()) {
        await listDirectoryRecursive(fullPath, relativePath, includeHidden, recursive, results);
      }
    }
  }

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

  Calls registerFileTools which includes registration of list_directory among file tools.

  registerFileTools(server);