fetch_github_readme
Retrieve README files from GitHub repositories to access project overviews, installation guides, and usage examples for understanding codebases.
Instructions
Fetch README file from a GitHub repository.
USE THIS WHEN: You need the project overview, quick start, or basic documentation.
BEST FOR: Getting a high-level understanding of a project.
The README typically contains installation, usage examples, and project description.
For deeper code exploration, use:
- get_repo_tree() to see the complete file structure
- get_file_content() to read specific source files
Args:
repo: Repository in "owner/repo" format (e.g., "psf/requests")
max_bytes: Maximum content size, default 20KB
Returns: JSON with README content, size, and metadata
Example: fetch_github_readme("psf/requests") → Returns the requests README
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| repo | Yes | ||
| max_bytes | No |
Implementation Reference
- src/RTFD/providers/github.py:740-775 (handler)The main handler function for the 'fetch_github_readme' MCP tool. It parses the repository string, handles validation, delegates to the internal helper method, and serializes the result as a CallToolResult.
async def fetch_github_readme(repo: str, max_bytes: int = 20480) -> CallToolResult: """ Fetch README file from a GitHub repository. USE THIS WHEN: You need the project overview, quick start, or basic documentation. BEST FOR: Getting a high-level understanding of a project. The README typically contains installation, usage examples, and project description. For deeper code exploration, use: - get_repo_tree() to see the complete file structure - get_file_content() to read specific source files Args: repo: Repository in "owner/repo" format (e.g., "psf/requests") max_bytes: Maximum content size, default 20KB Returns: JSON with README content, size, and metadata Example: fetch_github_readme("psf/requests") → Returns the requests README """ # Parse owner/repo format parts = repo.split("/", 1) if len(parts) != 2: error_result = { "repository": repo, "content": "", "error": "Invalid repo format. Use 'owner/repo'", "size_bytes": 0, "source": None, } return serialize_response_with_meta(error_result) owner, repo_name = parts result = await self._fetch_github_readme(owner, repo_name, max_bytes) return serialize_response_with_meta(result) - src/RTFD/providers/github.py:139-219 (helper)The internal helper method that performs the core logic of fetching the README from the GitHub API, decoding content, converting relative URLs, truncating if necessary, and handling errors.
async def _fetch_github_readme( self, owner: str, repo: str, max_bytes: int = 20480 ) -> dict[str, Any]: """ Fetch README from GitHub repository. Args: owner: Repository owner repo: Repository name max_bytes: Maximum content size Returns: Dict with content, size, source info """ try: headers = self._get_headers() url = f"https://api.github.com/repos/{owner}/{repo}/readme" async with await self._http_client() as client: resp = await client.get(url, headers=headers) resp.raise_for_status() data = resp.json() # Decode base64 content content = base64.b64decode(data["content"]).decode("utf-8") # Convert relative URLs to absolute # Use the blob URL for the specific branch/path data.get("name", "README.md") readme_path = data.get("path", "") default_branch = "main" # Could be fetched from repo metadata if needed base_url = f"https://github.com/{owner}/{repo}/blob/{default_branch}" if readme_path and "/" in readme_path: # If README is in a subdirectory dir_path = "/".join(readme_path.split("/")[:-1]) base_url = f"{base_url}/{dir_path}" content = convert_relative_urls(content, base_url) # Truncate if needed if len(content.encode("utf-8")) > max_bytes: # Simple truncation for now - could use smart_truncate encoded = content.encode("utf-8")[:max_bytes] # Handle potential multi-byte character splits while len(encoded) > 0: try: content = encoded.decode("utf-8") break except UnicodeDecodeError: encoded = encoded[:-1] truncated = True else: truncated = False return { "repository": f"{owner}/{repo}", "content": content, "size_bytes": len(content.encode("utf-8")), "source": "github_readme", "readme_path": readme_path, "truncated": truncated, } except httpx.HTTPStatusError as exc: return { "repository": f"{owner}/{repo}", "content": "", "error": f"GitHub returned {exc.response.status_code}", "size_bytes": 0, "source": None, } except Exception as exc: return { "repository": f"{owner}/{repo}", "content": "", "error": f"Failed to fetch README: {exc!s}", "size_bytes": 0, "source": None, } - src/RTFD/providers/github.py:934-939 (registration)Registration of the 'fetch_github_readme' tool (and related fetch tools) in the GitHubProvider's get_tools() method, 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-33 (registration)The 'fetch_github_readme' tool is listed in the provider metadata's tool_names (conditionally), indicating it will be exposed as an MCP tool.
tool_names.extend( [ "fetch_github_readme", "list_repo_contents", "get_file_content", "get_repo_tree", "get_commit_diff", "list_github_packages", "get_package_versions", ] )