testmo_find_folder_by_name

Instructions

Implementation Reference

• testmo/tools/folders.py:138-157 (handler)

  The actual implementation of the testmo_find_folder_by_name tool handler. It fetches all folders via the internal helper _get_all_folders, then searches by name (and optional parent_id), returning the matching folder dict or a not-found response.

  @mcp.tool()
  async def testmo_find_folder_by_name(
      project_id: int,
      name: str,
      parent_id: int | None = None,
  ) -> dict[str, Any]:
      """Find a folder by its name within a project.
  
      Args:
          project_id: The project ID.
          name: Folder name to search for.
          parent_id: Parent folder ID to search within (omit for root level).
      """
      all_folders = await _get_all_folders(project_id)
      for folder in all_folders:
          folder_parent = folder.get("parent_id") or 0
          search_parent = parent_id or 0
          if folder["name"] == name and folder_parent == search_parent:
              return folder
      return {"found": False, "message": f"Folder '{name}' not found"}

• testmo/tools/folders.py:1-1 (registration)

  The `@mcp.tool()` decorator on line 138 registers `testmo_find_folder_by_name` as an MCP tool on the FastMCP instance imported from `..server`.

  import asyncio

• testmo/tools/folders.py:138-157 (schema)

  The function signature defines the input schema: project_id (int), name (str), parent_id (int | None). The return type is dict[str, Any]. These are automatically interpreted by FastMCP as the tool's input/output schema.

  @mcp.tool()
  async def testmo_find_folder_by_name(
      project_id: int,
      name: str,
      parent_id: int | None = None,
  ) -> dict[str, Any]:
      """Find a folder by its name within a project.
  
      Args:
          project_id: The project ID.
          name: Folder name to search for.
          parent_id: Parent folder ID to search within (omit for root level).
      """
      all_folders = await _get_all_folders(project_id)
      for folder in all_folders:
          folder_parent = folder.get("parent_id") or 0
          search_parent = parent_id or 0
          if folder["name"] == name and folder_parent == search_parent:
              return folder
      return {"found": False, "message": f"Folder '{name}' not found"}

• testmo/tools/folders.py:9-24 (helper)

  Internal helper _get_all_folders used by testmo_find_folder_by_name to fetch all folders from the Testmo API with auto-pagination.

  async def _get_all_folders(project_id: int) -> list[dict[str, Any]]:
      """Fetch all folders with auto-pagination (internal helper)."""
      all_folders: list[dict[str, Any]] = []
      page = 1
      while True:
          result = await _request(
              "GET",
              f"/projects/{project_id}/folders",
              params={"page": page, "per_page": 100},
          )
          all_folders.extend(result.get("result", []))
          if result.get("next_page") is None:
              break
          page += 1
          await asyncio.sleep(RATE_LIMIT_DELAY)
      return all_folders

• testmo-mcp.py:11-12 (registration)

  Top-level entry point imports testmo.tools.folders, which triggers the @mcp.tool() decorators and registers all folder tools (including testmo_find_folder_by_name) on the mcp instance.

  import testmo.tools.projects  # noqa: F401
  import testmo.tools.folders  # noqa: F401