github_repo_reader

Reads source files from local repositories, excluding Git files, node_modules, binaries, and large files. Returns directory structure and file contents for development analysis.

Instructions

Recursively reads all source files in a local repository directory. Automatically ignores .git, node_modules, binary files, and large files (>500KB). Returns a directory tree and the full content of each readable file.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`repo_path`	Yes	Absolute path to the local repository root. Windows example: C:\Users\YourName\Projects\my-repo
`max_files`	No	Maximum number of files to return (default: 100, max: 500).

Implementation Reference

src/tools/repoReader.ts:144-194 (handler)

The handler function for the github_repo_reader tool. It reads the local repository, constructs a directory tree, and collects file contents while applying ignore rules.

async handler(args: { repo_path: string; max_files?: number }): Promise<string> {
  const repoPath = path.resolve(args.repo_path);
  const maxFiles = Math.min(args.max_files ?? 100, 500);

  if (!fs.existsSync(repoPath)) {
    return `ERROR: Path does not exist: ${repoPath}`;
  }

  const stat = fs.statSync(repoPath);
  if (!stat.isDirectory()) {
    return `ERROR: Path is not a directory: ${repoPath}`;
  }

  const tree = buildTree(repoPath);
  const files: FileEntry[] = [];
  const skipped = { count: 0 };

  collectFiles(repoPath, repoPath, files, skipped);

  const limitedFiles = files.slice(0, maxFiles);
  if (files.length > maxFiles) {
    skipped.count += files.length - maxFiles;
  }

  const result: RepoReadResult = {
    repoPath,
    totalFiles: limitedFiles.length,
    skippedFiles: skipped.count,
    files: limitedFiles,
    tree,
  };

  const sections: string[] = [
    `# Repository: ${path.basename(repoPath)}`,
    `**Path:** ${result.repoPath}`,
    `**Files Read:** ${result.totalFiles}  |  **Skipped:** ${result.skippedFiles}`,
    `\n## Directory Tree\n\`\`\`\n${result.tree}\n\`\`\``,
    `\n## File Contents`,
  ];

  for (const file of result.files) {
    const ext = path.extname(file.relativePath).slice(1) || "txt";
    sections.push(
      `\n### ${file.relativePath}\n` +
      `*Size: ${(file.sizeBytes / 1024).toFixed(1)} KB*\n` +
      `\`\`\`${ext}\n${file.content}\n\`\`\``
    );
  }

  return sections.join("\n");
},

src/tools/repoReader.ts:128-143 (schema)

Input schema definition for the github_repo_reader tool, specifying required and optional parameters.

inputSchema: {
  type: "object",
  properties: {
    repo_path: {
      type: "string",
      description:
        "Absolute path to the local repository root. " +
        "Windows example: C:\\Users\\YourName\\Projects\\my-repo",
    },
    max_files: {
      type: "number",
      description: "Maximum number of files to return (default: 100, max: 500).",
    },
  },
  required: ["repo_path"],
},

src/tools/repoReader.ts:122-127 (registration)

Tool metadata including name and description for the github_repo_reader tool.

return {
  name: "github_repo_reader",
  description:
    "Recursively reads all source files in a local repository directory. " +
    "Automatically ignores `.git`, `node_modules`, binary files, and large files (>500KB). " +
    "Returns a directory tree and the full content of each readable file.",

AI Dev Assistant