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

Instructions

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", ] )