terraform-cloud-mcp

Instructions

Implementation Reference

• terraform_cloud_mcp/tools/workspaces.py:140-181 (handler)

  The main handler function that executes the list_workspaces tool logic. It validates input using WorkspaceListRequest, constructs query parameters, and makes a GET request to the Terraform Cloud API endpoint /organizations/{organization}/workspaces.

  @handle_api_errors
  async def list_workspaces(
      organization: str,
      page_number: int = 1,
      page_size: int = 20,
      search: Optional[str] = None,
  ) -> APIResponse:
      """List workspaces in an organization.
  
      Retrieves a paginated list of all workspaces in a Terraform Cloud organization.
      Results can be filtered using a search string to find specific workspaces by name.
      Use this tool to discover existing workspaces, check workspace configurations,
      or find specific workspaces by partial name match.
  
      API endpoint: GET /organizations/{organization}/workspaces
  
      Args:
          organization: The name of the organization to list workspaces from
          page_number: The page number to return (default: 1)
          page_size: The number of items per page (default: 20, max: 100)
          search: Optional search string to filter workspaces by name
  
      Returns:
          Paginated list of workspaces with their configuration settings and metadata
  
      See:
          docs/tools/workspace.md for reference documentation
      """
      # Create request using Pydantic model for validation
      request = WorkspaceListRequest(
          organization=organization,
          page_number=page_number,
          page_size=page_size,
          search=search,
      )
  
      params = query_params(request)
  
      return await api_request(
          f"organizations/{organization}/workspaces", method="GET", params=params
      )

• terraform_cloud_mcp/server.py:53-53 (registration)

  Registration of the list_workspaces tool using FastMCP's mcp.tool() decorator, making it available in the MCP server.

  mcp.tool()(workspaces.list_workspaces)

• terraform_cloud_mcp/models/workspaces.py:56-78 (schema)

  Pydantic model defining the input schema for list_workspaces, used for validation of parameters like organization, page_number, page_size, and search.

  class WorkspaceListRequest(APIRequest):
      """Request parameters for listing workspaces in an organization.
  
      Defines the parameters for the workspace listing API including pagination
      and search filtering options.
  
      Reference: https://developer.hashicorp.com/terraform/cloud-docs/api-docs/workspaces#list-workspaces
  
      See:
          docs/models/workspace.md for reference
      """
  
      organization: str = Field(
          ...,
          # No alias needed as field name matches API field name
          description="The name of the organization to list workspaces from",
      )
      page_number: Optional[int] = Field(1, ge=1, description="Page number to fetch")
      page_size: Optional[int] = Field(
          20, ge=1, le=100, description="Number of results per page"
      )
      search: Optional[str] = Field(None, description="Substring to search for")