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)