RTFD (Read The F*****g Docs)

Instructions

        Get the full file tree of a GitHub repository.

        USE THIS WHEN: You need to see the overall structure and organization of a repository.

        BEST FOR: Understanding project layout, finding specific files, or getting a complete directory listing.
        Returns all file paths, types (file/directory), and sizes in a single call.

        Use recursive=True for complete tree (all files in all subdirectories).
        Use recursive=False for just top-level overview (faster, less data).

        After getting the tree, use:
        - get_file_content() to read specific files you identified
        - list_repo_contents() to browse specific directories in detail

        Args:
            repo: Repository in format "owner/repo" (e.g., "psf/requests")
            recursive: Whether to get full tree recursively (default False)
            max_items: Maximum number of items to return (default 1000)

        Returns:
            JSON with complete file tree structure, branch, and count

        Example: get_repo_tree("psf/requests", recursive=True) → Returns complete file listing
        

Implementation Reference

• src/RTFD/providers/github.py:853-892 (handler)

  Primary MCP tool handler for get_repo_tree. Validates input repo format, delegates to internal helper _get_repo_tree, and serializes the CallToolResult response.

  async def get_repo_tree(
      repo: str, recursive: bool = False, max_items: int = 1000
  ) -> CallToolResult:
      """
      Get the full file tree of a GitHub repository.
  
      USE THIS WHEN: You need to see the overall structure and organization of a repository.
  
      BEST FOR: Understanding project layout, finding specific files, or getting a complete directory listing.
      Returns all file paths, types (file/directory), and sizes in a single call.
  
      Use recursive=True for complete tree (all files in all subdirectories).
      Use recursive=False for just top-level overview (faster, less data).
  
      After getting the tree, use:
      - get_file_content() to read specific files you identified
      - list_repo_contents() to browse specific directories in detail
  
      Args:
          repo: Repository in format "owner/repo" (e.g., "psf/requests")
          recursive: Whether to get full tree recursively (default False)
          max_items: Maximum number of items to return (default 1000)
  
      Returns:
          JSON with complete file tree structure, branch, and count
  
      Example: get_repo_tree("psf/requests", recursive=True) → Returns complete file listing
      """
      parts = repo.split("/", 1)
      if len(parts) != 2:
          error_result = {
              "repository": repo,
              "tree": [],
              "error": "Invalid repo format. Use 'owner/repo'",
          }
          return serialize_response_with_meta(error_result)
  
      owner, repo_name = parts
      result = await self._get_repo_tree(owner, repo_name, recursive, max_items)
      return serialize_response_with_meta(result)

• src/RTFD/providers/github.py:368-437 (helper)

  Internal helper method that performs the core logic: fetches default branch, retrieves GitHub git/trees API (recursive option), processes tree items, handles errors and truncation.

  async def _get_repo_tree(
      self, owner: str, repo: str, recursive: bool = False, max_items: int = 1000
  ) -> dict[str, Any]:
      """
      Get the full file tree of a GitHub repository.
  
      Args:
          owner: Repository owner
          repo: Repository name
          recursive: Whether to get full tree recursively
          max_items: Maximum number of items to return
  
      Returns:
          Dict with file tree structure
      """
      try:
          headers = self._get_headers()
  
          # First get the default branch
          repo_url = f"https://api.github.com/repos/{owner}/{repo}"
          async with await self._http_client() as client:
              repo_resp = await client.get(repo_url, headers=headers)
              repo_resp.raise_for_status()
              repo_data = repo_resp.json()
              default_branch = repo_data.get("default_branch", "main")
  
          # Get the tree
          tree_url = f"https://api.github.com/repos/{owner}/{repo}/git/trees/{default_branch}"
          if recursive:
              tree_url += "?recursive=1"
  
          async with await self._http_client() as client:
              resp = await client.get(tree_url, headers=headers)
              resp.raise_for_status()
              data = resp.json()
  
          tree_items = data.get("tree", [])[:max_items]
  
          tree = []
          for item in tree_items:
              tree.append(
                  {
                      "path": item.get("path"),
                      "type": item.get("type"),  # "blob" (file) or "tree" (dir)
                      "size": item.get("size"),
                      "sha": item.get("sha"),
                      "url": item.get("url"),
                  }
              )
  
          return {
              "repository": f"{owner}/{repo}",
              "branch": default_branch,
              "tree": tree,
              "count": len(tree),
              "truncated": data.get("truncated", False) or len(tree_items) >= max_items,
          }
  
      except httpx.HTTPStatusError as exc:
          return {
              "repository": f"{owner}/{repo}",
              "tree": [],
              "error": f"GitHub returned {exc.response.status_code}",
          }
      except Exception as exc:
          return {
              "repository": f"{owner}/{repo}",
              "tree": [],
              "error": f"Failed to get repository tree: {exc!s}",
          }

• src/RTFD/providers/github.py:21-33 (registration)

  Tool name registration in get_metadata(): conditionally adds 'get_repo_tree' to the list of exposed tool names when fetch is enabled.

  tool_names = ["github_repo_search", "github_code_search"]
  if is_fetch_enabled():
      tool_names.extend(
          [
              "fetch_github_readme",
              "list_repo_contents",
              "get_file_content",
              "get_repo_tree",
              "get_commit_diff",
              "list_github_packages",
              "get_package_versions",
          ]
      )

• src/RTFD/providers/github.py:934-939 (registration)

  Actual tool function registration: assigns the get_repo_tree handler to tools["get_repo_tree"] conditionally in get_tools().

  if is_fetch_enabled():
      tools["fetch_github_readme"] = fetch_github_readme
      tools["list_repo_contents"] = list_repo_contents
      tools["get_file_content"] = get_file_content
      tools["get_repo_tree"] = get_repo_tree
      tools["get_commit_diff"] = get_commit_diff