read_project_structure

Analyzes project directory structure to generate tree-like file and folder layouts for README documentation creation.

Instructions

Read the directory structure of a project. Returns a tree-like structure of files and folders.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`path`	Yes	The absolute path to the project directory
`maxDepth`	No	Maximum depth to traverse (default: 3)

Implementation Reference

src/index.ts:470-484 (handler)

Handler for the 'read_project_structure' tool. Destructures input arguments, calls the getDirectoryStructure helper function, stringifies the result as JSON, and returns it as text content in the MCP response format.

case "read_project_structure": {
  const { path, maxDepth = 3 } = args as {
    path: string;
    maxDepth?: number;
  };
  const structure = await getDirectoryStructure(path, maxDepth);
  return {
    content: [
      {
        type: "text",
        text: JSON.stringify(structure, null, 2),
      },
    ],
  };
}

src/index.ts:395-408 (schema)

Input schema definition for the 'read_project_structure' tool, specifying the required 'path' parameter and optional 'maxDepth'.

  type: "object",
  properties: {
    path: {
      type: "string",
      description: "The absolute path to the project directory",
    },
    maxDepth: {
      type: "number",
      description: "Maximum depth to traverse (default: 3)",
      default: 3,
    },
  },
  required: ["path"],
},

src/index.ts:391-409 (registration)

Registration of the 'read_project_structure' tool in the ListTools response, including name, description, and input schema.

  name: "read_project_structure",
  description:
    "Read the directory structure of a project. Returns a tree-like structure of files and folders.",
  inputSchema: {
    type: "object",
    properties: {
      path: {
        type: "string",
        description: "The absolute path to the project directory",
      },
      maxDepth: {
        type: "number",
        description: "Maximum depth to traverse (default: 3)",
        default: 3,
      },
    },
    required: ["path"],
  },
},

src/index.ts:68-123 (helper)

Core helper function that recursively reads the directory structure up to a maximum depth, ignoring common patterns like node_modules, and builds a tree-like object representation.

async function getDirectoryStructure(
  dirPath: string,
  maxDepth: number = 3,
  currentDepth: number = 0,
  ignorePatterns: string[] = [
    "node_modules",
    ".git",
    "dist",
    "build",
    ".next",
    "coverage",
  ],
): Promise<any> {
  if (currentDepth >= maxDepth) {
    return null;
  }

  try {
    const entries = await readdir(dirPath, { withFileTypes: true });
    const structure: any = {
      type: "directory",
      name: parse(dirPath).base || dirPath,
      children: [],
    };

    for (const entry of entries) {
      if (ignorePatterns.some((pattern) => entry.name.includes(pattern))) {
        continue;
      }

      const fullPath = join(dirPath, entry.name);

      if (entry.isDirectory()) {
        const subStructure = await getDirectoryStructure(
          fullPath,
          maxDepth,
          currentDepth + 1,
          ignorePatterns,
        );
        if (subStructure) {
          structure.children.push(subStructure);
        }
      } else {
        structure.children.push({
          type: "file",
          name: entry.name,
          path: fullPath,
        });
      }
    }

    return structure;
  } catch (error) {
    throw new Error(`Failed to read directory: ${error}`);
  }
}

README Generator MCP Server