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

Instructions

        List contents of a directory in a GitHub repository.

        USE THIS WHEN: You need to browse or explore the structure of a repository directory.

        BEST FOR: Discovering what files and folders exist in a specific location.
        Returns names, paths, types (file/dir), sizes for each item.

        Common workflow:
        1. Use github_repo_search() to find the repository
        2. Use get_repo_tree() to see the overall structure
        3. Use list_repo_contents() to browse specific directories
        4. Use get_file_content() to read individual files

        Args:
            repo: Repository in format "owner/repo" (e.g., "psf/requests")
            path: Path to directory (empty string for root, e.g., "src/utils")

        Returns:
            JSON with list of files and directories with metadata

        Example: list_repo_contents("psf/requests", "requests") → Lists files in requests/ directory
        

Implementation Reference

• src/RTFD/providers/github.py:777-813 (handler)

  Main handler for the list_repo_contents MCP tool. Parses 'owner/repo' format, validates input, calls internal helper, and serializes response.

  async def list_repo_contents(repo: str, path: str = "") -> CallToolResult:
      """
      List contents of a directory in a GitHub repository.
  
      USE THIS WHEN: You need to browse or explore the structure of a repository directory.
  
      BEST FOR: Discovering what files and folders exist in a specific location.
      Returns names, paths, types (file/dir), sizes for each item.
  
      Common workflow:
      1. Use github_repo_search() to find the repository
      2. Use get_repo_tree() to see the overall structure
      3. Use list_repo_contents() to browse specific directories
      4. Use get_file_content() to read individual files
  
      Args:
          repo: Repository in format "owner/repo" (e.g., "psf/requests")
          path: Path to directory (empty string for root, e.g., "src/utils")
  
      Returns:
          JSON with list of files and directories with metadata
  
      Example: list_repo_contents("psf/requests", "requests") → Lists files in requests/ directory
      """
      parts = repo.split("/", 1)
      if len(parts) != 2:
          error_result = {
              "repository": repo,
              "path": path,
              "contents": [],
              "error": "Invalid repo format. Use 'owner/repo'",
          }
          return serialize_response_with_meta(error_result)
  
      owner, repo_name = parts
      result = await self._list_repo_contents(owner, repo_name, path)
      return serialize_response_with_meta(result)

• src/RTFD/providers/github.py:220-282 (helper)

  Internal helper method that makes the GitHub Contents API request, processes the response into a standardized dict format, and handles HTTP errors.

  async def _list_repo_contents(self, owner: str, repo: str, path: str = "") -> dict[str, Any]:
      """
      List contents of a directory in a GitHub repository.
  
      Args:
          owner: Repository owner
          repo: Repository name
          path: Path to directory (empty string for root)
  
      Returns:
          Dict with list of files and directories
      """
      try:
          headers = self._get_headers()
          url = f"https://api.github.com/repos/{owner}/{repo}/contents/{path}"
  
          async with await self._http_client() as client:
              resp = await client.get(url, headers=headers)
              resp.raise_for_status()
              data = resp.json()
  
          # Handle single file vs directory
          if isinstance(data, dict):
              # Single file was requested
              items = [data]
          else:
              items = data
  
          contents = []
          for item in items:
              contents.append(
                  {
                      "name": item.get("name"),
                      "path": item.get("path"),
                      "type": item.get("type"),  # "file" or "dir"
                      "size": item.get("size"),
                      "sha": item.get("sha"),
                      "url": item.get("html_url"),
                      "download_url": item.get("download_url"),
                  }
              )
  
          return {
              "repository": f"{owner}/{repo}",
              "path": path or "/",
              "contents": contents,
              "count": len(contents),
          }
  
      except httpx.HTTPStatusError as exc:
          return {
              "repository": f"{owner}/{repo}",
              "path": path,
              "contents": [],
              "error": f"GitHub returned {exc.response.status_code}",
          }
      except Exception as exc:
          return {
              "repository": f"{owner}/{repo}",
              "path": path,
              "contents": [],
              "error": f"Failed to list contents: {exc!s}",
          }

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

  Registration of the list_repo_contents tool (and related fetch tools) in the provider's get_tools() dictionary, conditional on fetch being enabled.

  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

• src/RTFD/providers/github.py:23-34 (registration)

  Declaration of list_repo_contents in the provider metadata's tool_names list, conditional on fetch being 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",
      ]
  )