terraform-cloud-mcp

Instructions

Implementation Reference

• terraform_cloud_mcp/tools/state_versions.py:132-196 (handler)

  The core handler function that executes the logic for creating a state version by constructing the API payload and making a POST request to the Terraform Cloud API.

  async def create_state_version(
      workspace_id: str,
      serial: int,
      md5: str,
      params: Optional[StateVersionParams] = None,
  ) -> APIResponse:
      """Create a state version in a workspace.
  
      Creates a new state version and sets it as the current state version for the
      given workspace. The workspace must be locked by the user creating a state version.
      This is most useful for migrating existing state from Terraform Community edition
      into a new HCP Terraform workspace.
  
      API endpoint: POST /workspaces/:workspace_id/state-versions
  
      Args:
          workspace_id: The ID of the workspace (format: "ws-xxxxxxxx")
          serial: The serial number of this state instance
          md5: An MD5 hash of the raw state version
          params: Additional state version parameters (optional):
              - state: Base64 encoded raw state file
              - lineage: Lineage of the state version
              - json_state: Base64 encoded JSON state
              - json_state_outputs: Base64 encoded JSON state outputs
              - run_id: The ID of the run to associate with the state version
  
      Returns:
          The created state version data including download URLs and status information
  
      See:
          docs/tools/state_versions.md for reference documentation
      """
      # Extract parameters from params object
      param_dict = params.model_dump(exclude_none=True, by_alias=False) if params else {}
  
      # Add required parameters
      param_dict["serial"] = serial
      param_dict["md5"] = md5
  
      # Create request using Pydantic model
      request_params = StateVersionCreateRequest(workspace_id=workspace_id, **param_dict)
  
      # Create API payload using utility function
      payload = create_api_payload(
          resource_type="state-versions",
          model=request_params,
          exclude_fields={"workspace_id"},
      )
  
      # Add relationship if run_id is provided
      if param_dict.get("run_id"):
          payload = add_relationship(
              payload=payload,
              relation_name="run",
              resource_type="runs",
              resource_id=param_dict["run_id"],
          )
  
      # Make API request
      return await api_request(
          f"workspaces/{request_params.workspace_id}/state-versions",
          method="POST",
          data=payload,
      )

• terraform_cloud_mcp/models/state_versions.py:111-161 (schema)

  Pydantic model providing input validation and structure for the state version creation request, used directly in the handler.

  class StateVersionCreateRequest(APIRequest):
      """Request model for creating a state version.
  
      Validates and structures the request according to the Terraform Cloud API
      requirements for creating state versions.
  
      Reference: https://developer.hashicorp.com/terraform/cloud-docs/api-docs/state-versions#create-a-state-version
  
      See:
          docs/models/state_versions.md for reference
      """
  
      workspace_id: str = Field(
          ...,
          description="The ID of the workspace to create a state version in",
          pattern=r"^ws-[a-zA-Z0-9]{16}$",  # Standard workspace ID pattern
      )
      serial: int = Field(
          ...,
          description="The serial of the state version",
          ge=0,
      )
      md5: str = Field(
          ...,
          description="An MD5 hash of the raw state version",
          pattern=r"^[a-fA-F0-9]{32}$",  # MD5 hash pattern
      )
      state: Optional[str] = Field(
          None,
          description="Base64 encoded raw state file",
      )
      lineage: Optional[str] = Field(
          None,
          description="Lineage of the state version",
      )
      json_state: Optional[str] = Field(
          None,
          alias="json-state",
          description='Base64 encoded json state, as expressed by "terraform show -json"',
      )
      json_state_outputs: Optional[str] = Field(
          None,
          alias="json-state-outputs",
          description='Base64 encoded output values as represented by "terraform show -json"',
      )
      run_id: Optional[str] = Field(
          None,
          description="The ID of the run to associate with the state version",
          pattern=r"^run-[a-zA-Z0-9]{16}$",  # Standard run ID pattern
      )

• terraform_cloud_mcp/models/state_versions.py:163-209 (schema)

  Pydantic model for optional parameters passed to the create_state_version handler, excluding routing fields like workspace_id.

  class StateVersionParams(APIRequest):
      """Parameters for state version operations without routing fields.
  
      This model provides all optional parameters for creating state versions,
      reusing field definitions from StateVersionCreateRequest. It separates configuration
      parameters from routing information.
  
      Reference: https://developer.hashicorp.com/terraform/cloud-docs/api-docs/state-versions
  
      See:
          docs/models/state_versions.md for reference
      """
  
      serial: Optional[int] = Field(
          None,
          description="The serial of the state version",
          ge=0,
      )
      md5: Optional[str] = Field(
          None,
          description="An MD5 hash of the raw state version",
          pattern=r"^[a-fA-F0-9]{32}$",  # MD5 hash pattern
      )
      state: Optional[str] = Field(
          None,
          description="Base64 encoded raw state file",
      )
      lineage: Optional[str] = Field(
          None,
          description="Lineage of the state version",
      )
      json_state: Optional[str] = Field(
          None,
          alias="json-state",
          description='Base64 encoded json state, as expressed by "terraform show -json"',
      )
      json_state_outputs: Optional[str] = Field(
          None,
          alias="json-state-outputs",
          description='Base64 encoded output values as represented by "terraform show -json"',
      )
      run_id: Optional[str] = Field(
          None,
          description="The ID of the run to associate with the state version",
          pattern=r"^run-[a-zA-Z0-9]{16}$",  # Standard run ID pattern
      )

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

  Registers the create_state_version handler as an MCP tool with write permissions configuration.

  mcp.tool(**write_tool_config)(state_versions.create_state_version)