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

Instructions

Implementation Reference

• src/RTFD/providers/pypi.py:193-215 (handler)

  The main execution logic for the pypi_metadata tool, fetching PyPI metadata and returning it as CallToolResult.
  async def pypi_metadata(package: str, ignore_verification: bool = False) -> CallToolResult: """ Get Python package metadata from PyPI (name, version, URLs, summary). USE THIS WHEN: You need basic package info, version numbers, or links to external documentation. RETURNS: Package metadata ONLY - does NOT include actual documentation content. For full documentation, use fetch_pypi_docs instead. The response includes: - Package name, version, summary - Documentation URL (docs_url) - can be passed to WebFetch for external docs - Project URLs (homepage, repository, etc.) Args: package: PyPI package name (e.g., "requests", "flask", "django") ignore_verification: Skip PyPI verification check if VERIFIED_BY_PYPI is enabled Example: pypi_metadata("requests") → Returns metadata with docs_url pointing to readthedocs """ result = await self._fetch_metadata(package, ignore_verification) return serialize_response_with_meta(result)
• src/RTFD/providers/pypi.py:20-33 (registration)

  Provider metadata registration that declares 'pypi_metadata' as an available tool.
  def get_metadata(self) -> ProviderMetadata: tool_names = ["pypi_metadata"] if is_fetch_enabled(): tool_names.append("fetch_pypi_docs") return ProviderMetadata( name="pypi", description="PyPI package metadata and documentation", expose_as_tool=True, tool_names=tool_names, supports_library_search=True, required_env_vars=[], optional_env_vars=["VERIFIED_BY_PYPI"], )
• src/RTFD/providers/pypi.py:190-249 (registration)

  Registration of the pypi_metadata tool function in the provider's get_tools method.
  def get_tools(self) -> dict[str, Callable]: """Return MCP tool functions.""" async def pypi_metadata(package: str, ignore_verification: bool = False) -> CallToolResult: """ Get Python package metadata from PyPI (name, version, URLs, summary). USE THIS WHEN: You need basic package info, version numbers, or links to external documentation. RETURNS: Package metadata ONLY - does NOT include actual documentation content. For full documentation, use fetch_pypi_docs instead. The response includes: - Package name, version, summary - Documentation URL (docs_url) - can be passed to WebFetch for external docs - Project URLs (homepage, repository, etc.) Args: package: PyPI package name (e.g., "requests", "flask", "django") ignore_verification: Skip PyPI verification check if VERIFIED_BY_PYPI is enabled Example: pypi_metadata("requests") → Returns metadata with docs_url pointing to readthedocs """ result = await self._fetch_metadata(package, ignore_verification) return serialize_response_with_meta(result) async def fetch_pypi_docs( package: str, max_bytes: int = 20480, ignore_verification: bool = False ) -> CallToolResult: """ Fetch actual Python package documentation from PyPI README/description. USE THIS WHEN: You need installation instructions, usage examples, API reference, or quickstart guides. BEST FOR: Getting complete, formatted documentation for Python packages. Better than using curl or WebFetch because it: - Automatically extracts relevant sections (Installation, Usage, Examples) - Converts reStructuredText to Markdown - Prioritizes most useful content sections - Falls back to GitHub README if PyPI description is minimal NOT SUITABLE FOR: External documentation sites (use docs_url from pypi_metadata + WebFetch) Args: package: PyPI package name (e.g., "requests", "numpy", "pandas") max_bytes: Maximum content size, default 20KB (increase for large packages) ignore_verification: Skip PyPI verification check if VERIFIED_BY_PYPI is enabled Returns: JSON with actual documentation content, size, truncation status Example: fetch_pypi_docs("requests") → Returns formatted README with installation and usage """ result = await self._fetch_pypi_docs(package, max_bytes, ignore_verification) return serialize_response_with_meta(result) tools = {"pypi_metadata": pypi_metadata} if is_fetch_enabled(): tools["fetch_pypi_docs"] = fetch_pypi_docs return tools
• src/RTFD/providers/pypi.py:65-98 (helper)

  Core helper function that fetches the actual PyPI JSON metadata, performs verification, and formats the response.
  async def _fetch_metadata( self, package: str, ignore_verification: bool = False ) -> dict[str, Any]: """Pull package metadata from the PyPI JSON API.""" # Check verification if enabled if os.getenv("VERIFIED_BY_PYPI", "").lower() == "true" and not ignore_verification: is_verified = await self._check_verification(package) if not is_verified: return { "name": package, "error": f"Project '{package}' is not verified by PyPI. " "Please ask the user if they want to trust this project.", "is_unverified": True, } url = f"https://pypi.org/pypi/{package}/json" async with await self._http_client() as client: resp = await client.get(url) resp.raise_for_status() payload = resp.json() info = payload.get("info", {}) return { "name": info.get("name"), "summary": info.get("summary") or "", "version": info.get("version"), "home_page": info.get("home_page"), "docs_url": info.get("project_urls", {}).get("Documentation") if isinstance(info.get("project_urls"), dict) else None, "project_urls": info.get("project_urls") or {}, "description": info.get("description") or "", }