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

Instructions

        Search Zig programming language documentation.

        USE THIS WHEN: You need information about Zig language features, syntax, stdlib, or concepts.

        BEST FOR: Learning Zig language specifics and finding relevant documentation sections.
        Searches the official Zig documentation (ziglang.org/documentation/master/) and returns
        matching sections with titles, summaries, and relevance scores.

        Good for queries about:
        - Language features (e.g., "comptime", "async", "optionals")
        - Standard library (e.g., "ArrayList", "HashMap", "allocators")
        - Memory management (e.g., "allocator", "defer", "errdefer")
        - Error handling (e.g., "error sets", "try", "catch")
        - Build system (e.g., "build.zig", "zig build")

        NOT SUITABLE FOR: Third-party Zig packages (use GitHub provider for that)

        Args:
            query: Search keywords (e.g., "comptime", "async", "ArrayList", "error handling")

        Returns:
            JSON with matching documentation sections, relevance scores, and source URL

        Example: zig_docs("comptime") → Returns sections about compile-time code execution
        

Implementation Reference

• src/RTFD/providers/zig.py:41-70 (handler)

  The main zig_docs tool handler: async function that takes a query string, calls the private _search_zig_docs helper, and serializes the result into CallToolResult using serialize_response_with_meta.

  async def zig_docs(query: str) -> CallToolResult:
      """
      Search Zig programming language documentation.
  
      USE THIS WHEN: You need information about Zig language features, syntax, stdlib, or concepts.
  
      BEST FOR: Learning Zig language specifics and finding relevant documentation sections.
      Searches the official Zig documentation (ziglang.org/documentation/master/) and returns
      matching sections with titles, summaries, and relevance scores.
  
      Good for queries about:
      - Language features (e.g., "comptime", "async", "optionals")
      - Standard library (e.g., "ArrayList", "HashMap", "allocators")
      - Memory management (e.g., "allocator", "defer", "errdefer")
      - Error handling (e.g., "error sets", "try", "catch")
      - Build system (e.g., "build.zig", "zig build")
  
      NOT SUITABLE FOR: Third-party Zig packages (use GitHub provider for that)
  
      Args:
          query: Search keywords (e.g., "comptime", "async", "ArrayList", "error handling")
  
      Returns:
          JSON with matching documentation sections, relevance scores, and source URL
  
      Example: zig_docs("comptime") → Returns sections about compile-time code execution
      """
      result = await self._search_zig_docs(query)
      return serialize_response_with_meta(result)

• src/RTFD/providers/zig.py:19-28 (registration)

  Registration in provider metadata: declares tool_names=["zig_docs"] in get_metadata().

  def get_metadata(self) -> ProviderMetadata:
      return ProviderMetadata(
          name="zig",
          description="Zig programming language documentation",
          expose_as_tool=True,
          tool_names=["zig_docs"],
          supports_library_search=False,  # Zig docs are not a library/package search
          required_env_vars=[],
          optional_env_vars=[],
      )

• src/RTFD/providers/zig.py:38-71 (registration)

  Registration of the tool function: defines and returns {"zig_docs": zig_docs} in get_tools().

  def get_tools(self) -> dict[str, Callable]:
      """Return MCP tool functions."""
  
      async def zig_docs(query: str) -> CallToolResult:
          """
          Search Zig programming language documentation.
  
          USE THIS WHEN: You need information about Zig language features, syntax, stdlib, or concepts.
  
          BEST FOR: Learning Zig language specifics and finding relevant documentation sections.
          Searches the official Zig documentation (ziglang.org/documentation/master/) and returns
          matching sections with titles, summaries, and relevance scores.
  
          Good for queries about:
          - Language features (e.g., "comptime", "async", "optionals")
          - Standard library (e.g., "ArrayList", "HashMap", "allocators")
          - Memory management (e.g., "allocator", "defer", "errdefer")
          - Error handling (e.g., "error sets", "try", "catch")
          - Build system (e.g., "build.zig", "zig build")
  
          NOT SUITABLE FOR: Third-party Zig packages (use GitHub provider for that)
  
          Args:
              query: Search keywords (e.g., "comptime", "async", "ArrayList", "error handling")
  
          Returns:
              JSON with matching documentation sections, relevance scores, and source URL
  
          Example: zig_docs("comptime") → Returns sections about compile-time code execution
          """
          result = await self._search_zig_docs(query)
          return serialize_response_with_meta(result)
  
      return {"zig_docs": zig_docs}

• src/RTFD/providers/zig.py:73-107 (helper)

  Core helper _search_zig_docs: fetches Zig docs from https://ziglang.org/documentation/master/, extracts sections, searches for query matches, returns structured results with relevance scores.

  async def _search_zig_docs(self, query: str) -> dict[str, Any]:
      """Search Zig documentation and return relevant sections."""
      try:
          # Fetch the master documentation page
          url = "https://ziglang.org/documentation/master/"
          async with await self._http_client() as client:
              resp = await client.get(url, follow_redirects=True)
              resp.raise_for_status()
              soup = BeautifulSoup(resp.text, "html.parser")
  
          # Build a search index of documentation sections
          sections = self._extract_doc_sections(soup)
  
          # Find matching sections based on query
          matches = self._search_sections(sections, query.lower())
  
          return {
              "query": query,
              "source": "https://ziglang.org/documentation/master/",
              "matches": matches[:5],  # Limit to top 5 results
              "total_matches": len(matches),
          }
  
      except httpx.HTTPError as exc:
          return {
              "query": query,
              "error": f"Failed to fetch Zig documentation: {exc}",
              "source": "https://ziglang.org/documentation/master/",
          }
      except Exception as exc:
          return {
              "query": query,
              "error": f"Error searching Zig documentation: {exc}",
              "source": "https://ziglang.org/documentation/master/",
          }

• src/RTFD/providers/zig.py:145-173 (helper)

  Helper _search_sections: scores documentation sections based on query word matches in title and summary, sorts by relevance.

  def _search_sections(self, sections: list[dict[str, str]], query: str) -> list[dict[str, Any]]:
      """Search sections for matches based on query string."""
      matches = []
      query_words = query.lower().split()
  
      for section in sections:
          title_lower = section["title"].lower()
          summary_lower = section["summary"].lower()
  
          # Score based on word matches (individual words from query)
          total_score = 0
          for word in query_words:
              # Title matches are weighted higher
              title_score = title_lower.count(word)
              summary_score = summary_lower.count(word)
              total_score += (title_score * 2) + summary_score
  
          if total_score > 0:
              matches.append(
                  {
                      "title": section["title"],
                      "summary": section["summary"],
                      "relevance_score": total_score,
                  }
              )
  
      # Sort by relevance score
      matches.sort(key=lambda x: x["relevance_score"], reverse=True)
      return matches