terraform-cloud-mcp

Instructions

Implementation Reference

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

  The main asynchronous handler function that implements the create_state_version tool. It constructs the API payload using Pydantic models and sends a POST request to the Terraform Cloud API to create a new state version in the specified workspace.
  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 that defines the input schema and validation for the state version creation request, including required fields (workspace_id, serial, md5) and optional fields (state, lineage, json_state, etc.). 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 the workspace_id routing field. Provides input validation for additional state version attributes.
  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 function as an MCP tool in the FastMCP server, using write_tool_config which enables it only if not in read-only mode.
  mcp.tool(**write_tool_config)(state_versions.create_state_version)