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

Instructions

        Get content of a specific file from a GitHub repository.

        USE THIS WHEN: You need to read the actual source code or contents of a specific file.

        BEST FOR: Examining implementation details, understanding how code works, or reading configuration files.
        Returns the full file content (UTF-8 text only, binary files are rejected).

        Automatically handles:
        - Base64 decoding from GitHub API
        - UTF-8 conversion with safe truncation
        - Binary file detection

        Args:
            repo: Repository in format "owner/repo" (e.g., "psf/requests")
            path: Path to file (e.g., "requests/api.py")
            max_bytes: Maximum content size (default 100KB, increase for large files)

        Returns:
            JSON with file content, size, truncation status, and metadata

        Example: get_file_content("psf/requests", "requests/api.py") → Returns source code of api.py
        

Implementation Reference

• src/RTFD/providers/github.py:815-852 (handler)

  The primary handler function for the 'get_file_content' MCP tool. It validates the repository format, delegates to the private _get_file_content helper, and serializes the response as a CallToolResult.

  async def get_file_content(repo: str, path: str, max_bytes: int = 102400) -> CallToolResult:
      """
      Get content of a specific file from a GitHub repository.
  
      USE THIS WHEN: You need to read the actual source code or contents of a specific file.
  
      BEST FOR: Examining implementation details, understanding how code works, or reading configuration files.
      Returns the full file content (UTF-8 text only, binary files are rejected).
  
      Automatically handles:
      - Base64 decoding from GitHub API
      - UTF-8 conversion with safe truncation
      - Binary file detection
  
      Args:
          repo: Repository in format "owner/repo" (e.g., "psf/requests")
          path: Path to file (e.g., "requests/api.py")
          max_bytes: Maximum content size (default 100KB, increase for large files)
  
      Returns:
          JSON with file content, size, truncation status, and metadata
  
      Example: get_file_content("psf/requests", "requests/api.py") → Returns source code of api.py
      """
      parts = repo.split("/", 1)
      if len(parts) != 2:
          error_result = {
              "repository": repo,
              "path": path,
              "content": "",
              "error": "Invalid repo format. Use 'owner/repo'",
          }
          return serialize_response_with_meta(error_result)
  
      owner, repo_name = parts
      result = await self._get_file_content(owner, repo_name, path, max_bytes)
      return serialize_response_with_meta(result)

• src/RTFD/providers/github.py:284-367 (helper)

  Private helper method implementing the core logic: GitHub API request, base64 decoding, binary detection, UTF-8 handling, truncation, and error management.

  async def _get_file_content(
      self, owner: str, repo: str, path: str, max_bytes: int = 102400
  ) -> dict[str, Any]:
      """
      Get content of a specific file from a GitHub repository.
  
      Args:
          owner: Repository owner
          repo: Repository name
          path: Path to file
          max_bytes: Maximum content size (default 100KB)
  
      Returns:
          Dict with file content and metadata
      """
      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()
  
          # Check if it's a file
          if data.get("type") != "file":
              return {
                  "repository": f"{owner}/{repo}",
                  "path": path,
                  "content": "",
                  "error": f"Path is a {data.get('type')}, not a file",
              }
  
          # Decode base64 content
          try:
              content = base64.b64decode(data["content"]).decode("utf-8")
          except UnicodeDecodeError:
              # Binary file
              return {
                  "repository": f"{owner}/{repo}",
                  "path": path,
                  "content": "",
                  "error": "File appears to be binary",
                  "size_bytes": data.get("size", 0),
                  "encoding": data.get("encoding"),
              }
  
          # Truncate if needed
          truncated = False
          if len(content.encode("utf-8")) > max_bytes:
              encoded = content.encode("utf-8")[:max_bytes]
              while len(encoded) > 0:
                  try:
                      content = encoded.decode("utf-8")
                      break
                  except UnicodeDecodeError:
                      encoded = encoded[:-1]
              truncated = True
  
          return {
              "repository": f"{owner}/{repo}",
              "path": path,
              "content": content,
              "size_bytes": len(content.encode("utf-8")),
              "truncated": truncated,
              "sha": data.get("sha"),
              "url": data.get("html_url"),
          }
  
      except httpx.HTTPStatusError as exc:
          return {
              "repository": f"{owner}/{repo}",
              "path": path,
              "content": "",
              "error": f"GitHub returned {exc.response.status_code}",
          }
      except Exception as exc:
          return {
              "repository": f"{owner}/{repo}",
              "path": path,
              "content": "",
              "error": f"Failed to get file content: {exc!s}",
          }

• src/RTFD/providers/github.py:623-941 (registration)

  The get_tools method registers the get_file_content tool (conditionally if fetch is enabled) into the tools dictionary returned for MCP.

  def get_tools(self) -> dict[str, Callable]:
      """Return MCP tool functions."""
  
      async def github_repo_search(
          query: str, limit: int = 5, language: str | None = "Python"
      ) -> CallToolResult:
          """
          Search for GitHub repositories by keyword or topic.
  
          USE THIS WHEN: You need to find repositories for a library, framework, or topic.
  
          BEST FOR: Discovering which repository contains a specific project.
          Returns repository names, descriptions, stars, and URLs - but NOT the code itself.
  
          To explore code after finding a repo, use:
          - get_repo_tree() to see all files
          - list_repo_contents() to browse directories
          - get_file_content() to read specific files
  
          Args:
              query: Search keywords (e.g., "machine learning", "web framework")
              limit: Maximum number of results (default 5)
              language: Filter by programming language (default "Python")
  
          Example: github_repo_search("requests") → Finds psf/requests repository
          """
          result = await self._search_repos(query, limit=limit, language=language)
          return serialize_response_with_meta(result)
  
      async def github_code_search(
          query: str, repo: str | None = None, limit: int = 5
      ) -> CallToolResult:
          """
          Search for code snippets across GitHub or within a specific repository.
  
          USE THIS WHEN: You need to find code examples, function definitions, or usage patterns.
  
          RETURNS: File paths and locations where code was found - NOT the actual file contents.
          To read the files, use get_file_content() with the returned paths.
  
          NOTE: Requires authentication - rate limited without GITHUB_TOKEN.
  
          Args:
              query: Code search query (e.g., "def parse_args", "class HTTPClient")
              repo: Optional repository filter in "owner/repo" format
              limit: Maximum number of results (default 5)
  
          Example: github_code_search("async def fetch", repo="psf/requests")
          """
          result = await self._search_code(query, repo=repo, limit=limit)
          return serialize_response_with_meta(result)
  
      async def list_github_packages(
          owner: str, package_type: str = "container"
      ) -> CallToolResult:
          """
          List packages (including GHCR images) for a GitHub user or organization.
  
          USE THIS WHEN: You want to find Docker images or other packages hosted on GitHub for a specific user/org.
          Note: GitHub does not support global package search; you must provide an owner.
  
          Args:
              owner: GitHub username or organization name (e.g. "github", "octocat")
              package_type: Type of package to list. Defaults to "container" (GHCR).
                            Options: "container", "npm", "maven", "rubygems", "nuget", "docker" (legacy)
  
          Returns:
              JSON list of packages with metadata (name, repository, version count, etc.)
          """
          try:
              data = await self._list_github_packages(owner, package_type)
              result = {
                  "owner": owner,
                  "package_type": package_type,
                  "packages": data,
                  "count": len(data),
              }
              return serialize_response_with_meta(result)
          except Exception as exc:
              return serialize_response_with_meta(
                  {"owner": owner, "error": f"Failed to list packages: {exc!s}"}
              )
  
      async def get_package_versions(
          owner: str, package_type: str, package_name: str
      ) -> CallToolResult:
          """
          Get versions for a specific GitHub package.
  
          USE THIS WHEN: You found a package using list_github_packages and want to see available tags/versions.
  
          Args:
              owner: GitHub username or organization name
              package_type: Type of package (e.g., "container")
              package_name: Name of the package (e.g., "rtfd")
  
          Returns:
              JSON list of versions/tags.
          """
          try:
              data = await self._get_package_versions(owner, package_type, package_name)
              result = {
                  "owner": owner,
                  "package_name": package_name,
                  "versions": data,
                  "count": len(data),
              }
              return serialize_response_with_meta(result)
          except Exception as exc:
              return serialize_response_with_meta(
                  {
                      "owner": owner,
                      "package_name": package_name,
                      "error": f"Failed to get versions: {exc!s}",
                  }
              )
  
      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)
  
      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)
  
      async def get_file_content(repo: str, path: str, max_bytes: int = 102400) -> CallToolResult:
          """
          Get content of a specific file from a GitHub repository.
  
          USE THIS WHEN: You need to read the actual source code or contents of a specific file.
  
          BEST FOR: Examining implementation details, understanding how code works, or reading configuration files.
          Returns the full file content (UTF-8 text only, binary files are rejected).
  
          Automatically handles:
          - Base64 decoding from GitHub API
          - UTF-8 conversion with safe truncation
          - Binary file detection
  
          Args:
              repo: Repository in format "owner/repo" (e.g., "psf/requests")
              path: Path to file (e.g., "requests/api.py")
              max_bytes: Maximum content size (default 100KB, increase for large files)
  
          Returns:
              JSON with file content, size, truncation status, and metadata
  
          Example: get_file_content("psf/requests", "requests/api.py") → Returns source code of api.py
          """
          parts = repo.split("/", 1)
          if len(parts) != 2:
              error_result = {
                  "repository": repo,
                  "path": path,
                  "content": "",
                  "error": "Invalid repo format. Use 'owner/repo'",
              }
              return serialize_response_with_meta(error_result)
  
          owner, repo_name = parts
          result = await self._get_file_content(owner, repo_name, path, max_bytes)
          return serialize_response_with_meta(result)
  
      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)
  
      async def get_commit_diff(repo: str, base: str, head: str) -> CallToolResult:
          """
          Get the diff between two commits, branches, or tags in a GitHub repository.
  
          USE THIS WHEN: You need to see what changed between two versions of code.
  
          BEST FOR: Analyzing changes, reviewing pull requests (by comparing branches), or checking version differences.
          Returns the raw git diff output.
  
          Args:
              repo: Repository in format "owner/repo" (e.g., "psf/requests")
              base: Base commit SHA, branch name, or tag (e.g., "main", "v1.0.0", "a1b2c3d")
              head: Head commit SHA, branch name, or tag (e.g., "feature-branch", "v1.1.0", "e5f6g7h")
  
          Returns:
              JSON with the raw git diff content.
  
          Example: get_commit_diff("psf/requests", "v2.28.0", "v2.28.1") → Returns diff between versions
          """
          parts = repo.split("/", 1)
          if len(parts) != 2:
              error_result = {
                  "repository": repo,
                  "base": base,
                  "head": head,
                  "diff": "",
                  "error": "Invalid repo format. Use 'owner/repo'",
              }
              return serialize_response_with_meta(error_result)
  
          owner, repo_name = parts
          result = await self._get_commit_diff(owner, repo_name, base, head)
          return serialize_response_with_meta(result)
  
      tools = {
          "github_repo_search": github_repo_search,
          "github_code_search": github_code_search,
          "list_github_packages": list_github_packages,
          "get_package_versions": get_package_versions,
      }
      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
  
      return tools