Pydantic AI Documentation Server

Instructions

Implementation Reference

• pydantic_ai_docs_server/server.py:105-152 (handler)

  The handler implementation for the `list_topics` tool, which lists files and directories in the Pydantic docs repository.

  @app.tool()
  async def list_topics(path: Optional[str] = None) -> List[TopicItem]:
      """
      Lists files and directories non-recursively within the Pydantic documentation.
      The path is relative to the 'docs/' directory in the cloned Pydantic repository.
      """
      logger.info(f"Listing topics for path: {path if path else 'root'}")
  
      try:
          repo_root = get_repo_path()
          docs_root = repo_root / "docs"
  
          if not docs_root.exists() or not docs_root.is_dir():
              logger.error(f"Pydantic docs directory not found at {docs_root}")
              return []
  
          current_path = docs_root
          if path:
              target_path = (docs_root / path).resolve(strict=False)
  
              if not str(target_path).startswith(str(docs_root.resolve())):
                  logger.warning(f"Path traversal attempt or invalid path: {path}")
                  return []
  
              if not target_path.exists() or not target_path.is_dir():
                  logger.info(
                      f"Specified path does not exist or is not a directory: {target_path}"
                  )
                  return []
              current_path = target_path
  
          items: List[TopicItem] = []
          for item in current_path.iterdir():
              if item.name.startswith("."):
                  continue
  
              item_relative_path = item.relative_to(docs_root).as_posix()
  
              items.append(
                  TopicItem(
                      name=item.name, path=item_relative_path, is_directory=item.is_dir()
                  )
              )
  
          items.sort(key=lambda x: (not x.is_directory, x.name.lower()))
  
          return items