terraform-cloud-mcp

Instructions

Implementation Reference

• terraform_cloud_mcp/tools/state_versions.py:26-79 (handler)

  The core handler function implementing the list_state_versions tool. It validates inputs using Pydantic models, converts filter status to enum, builds query parameters, and makes the API request to list state versions.

  @handle_api_errors
  async def list_state_versions(
      organization: str,
      workspace_name: str,
      page_number: int = 1,
      page_size: int = 20,
      filter_status: Optional[str] = None,
  ) -> APIResponse:
      """List state versions in a workspace.
  
      Retrieves a paginated list of all state versions in a Terraform Cloud workspace.
      Results can be filtered using status to find specific state versions.
  
      API endpoint: GET /state-versions
  
      Args:
          organization: The name of the organization that owns the workspace
          workspace_name: The name of the workspace to list state versions from
          page_number: The page number to return (default: 1)
          page_size: The number of items per page (default: 20, max: 100)
          filter_status: Filter state versions by status: 'pending', 'finalized', or 'discarded'
  
      Returns:
          Paginated list of state versions with their configuration settings and metadata
  
      See:
          docs/tools/state_versions.md for reference documentation
      """
      # Convert filter_status string to enum if provided
      status_enum = None
      if filter_status:
          try:
              status_enum = StateVersionStatus(filter_status)
          except ValueError:
              valid_values = ", ".join([s.value for s in StateVersionStatus])
              raise ValueError(
                  f"Invalid filter_status value: {filter_status}. Valid values: {valid_values}"
              )
  
      # Validate parameters
      params = StateVersionListRequest(
          filter_workspace_name=workspace_name,
          filter_organization_name=organization,
          page_number=page_number,
          page_size=page_size,
          filter_status=status_enum,
      )
  
      # Build query parameters using utility function
      query = query_params(params)
  
      # Make API request
      return await api_request("state-versions", params=query)

• terraform_cloud_mcp/models/state_versions.py:38-73 (schema)

  Pydantic schema/model for input parameters to the list_state_versions tool, defining validation for organization/workspace filters, pagination, and status filtering.

  class StateVersionListRequest(APIRequest):
      """Request parameters for listing state versions.
  
      Defines the parameters for the state version listing API including pagination
      and filtering options.
  
      Reference: https://developer.hashicorp.com/terraform/cloud-docs/api-docs/state-versions#list-state-versions
  
      See:
          docs/models/state_versions.md for reference
      """
  
      filter_workspace_name: Optional[str] = Field(
          None,
          description="Filter by workspace name",
      )
      filter_organization_name: Optional[str] = Field(
          None,
          description="Filter by organization name",
      )
      filter_status: Optional[StateVersionStatus] = Field(
          None,
          description="Filter state versions by status",
      )
      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",
      )

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

  Registration of the list_state_versions tool in the MCP server using the FastMCP decorator.

  mcp.tool()(state_versions.list_state_versions)

• terraform_cloud_mcp/models/state_versions.py:15-36 (schema)

  Enum schema defining possible status values for filtering state versions in the list_state_versions tool.

  class StateVersionStatus(str, Enum):
      """Status options for state versions in Terraform Cloud.
  
      Defines the various states a state version can be in during its lifecycle:
      - PENDING: State version has been created but state data is not encoded within the request
      - FINALIZED: State version has been successfully uploaded or created with valid state attribute
      - DISCARDED: State version was discarded because it was superseded by a newer version
      - BACKING_DATA_SOFT_DELETED: Enterprise only - backing files are marked for garbage collection
      - BACKING_DATA_PERMANENTLY_DELETED: Enterprise only - backing files have been permanently deleted
  
      Reference: https://developer.hashicorp.com/terraform/cloud-docs/api-docs/state-versions#state-version-status
  
      See:
          docs/models/state_versions.md for reference
      """
  
      PENDING = "pending"
      FINALIZED = "finalized"
      DISCARDED = "discarded"
      BACKING_DATA_SOFT_DELETED = "backing_data_soft_deleted"
      BACKING_DATA_PERMANENTLY_DELETED = "backing_data_permanently_deleted"

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

  Import of the state_versions module containing the list_state_versions handler for registration.

  from terraform_cloud_mcp.tools import state_versions