terraform-cloud-mcp

Instructions

Implementation Reference

• terraform_cloud_mcp/tools/runs.py:23-100 (handler)

  The main handler function for the 'create_run' tool. It creates a new Terraform run in the specified workspace using the Terraform Cloud API, handling parameters, payload construction, relationships, and variables.

  @handle_api_errors
  async def create_run(
      workspace_id: str,
      params: Optional[RunParams] = None,
  ) -> APIResponse:
      """Create a run in a workspace
  
      Creates a new Terraform run to trigger infrastructure changes through Terraform Cloud,
      representing a single execution of plan and apply operations. The run queues in the
      workspace and executes based on the workspace's execution mode and settings. Use this
      to deploy new infrastructure, apply configuration changes, or destroy resources.
  
      API endpoint: POST /runs
  
      Args:
          workspace_id: The workspace ID to execute the run in (format: "ws-xxxxxxxx")
          params: Optional run configuration with:
              - message: Description of the run's purpose
              - is_destroy: Whether to destroy all resources managed by the workspace
              - auto_apply: Whether to auto-apply after a successful plan
              - refresh: Whether to refresh Terraform state before planning
              - refresh_only: Only refresh the state without planning changes
              - plan_only: Create a speculative plan without applying
              - allow_empty_apply: Allow applying when there are no changes
              - target_addrs: List of resource addresses to specifically target
              - replace_addrs: List of resource addresses to force replacement
              - variables: Run-specific variables that override workspace variables
              - terraform_version: Specific Terraform version to use for this run
              - save_plan: Save the plan for later execution
              - debugging_mode: Enable extended debug logging
  
      Returns:
          The created run details with ID, status, configuration information,
          workspace relationship, and links to associated resources
  
      See:
          docs/tools/run.md for reference documentation
      """
      # Convert optional params to dictionary
      param_dict = params.model_dump(exclude_none=True) if params else {}
  
      # Create validated request object
      request = RunCreateRequest(workspace_id=workspace_id, **param_dict)
  
      # Extract variables for special handling
      variables = request.variables
  
      # Create API payload using utility function
      payload = create_api_payload(
          resource_type="runs",
          model=request,
          exclude_fields={"workspace_id", "variables"},  # Fields handled separately
      )
  
      # Add workspace relationship
      add_relationship(
          payload=payload,
          relation_name="workspace",
          resource_type="workspaces",
          resource_id=workspace_id,
      )
  
      # Add optional configuration version relationship
      if request.configuration_version_id:
          add_relationship(
              payload=payload,
              relation_name="configuration-version",
              resource_type="configuration-versions",
              resource_id=request.configuration_version_id,
          )
  
      # Transform variables to key-value format required by API
      if variables:
          payload["data"]["attributes"]["variables"] = [
              {"key": var.key, "value": var.value} for var in variables
          ]
  
      return await api_request("runs", method="POST", data=payload)

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

  Registration of the 'create_run' tool using FastMCP's mcp.tool decorator, with write permissions configuration.

  mcp.tool(**write_tool_config)(runs.create_run)

• terraform_cloud_mcp/models/runs.py:406-423 (schema)

  Pydantic model defining the input parameters (schema) for the create_run tool, including fields like message, is_destroy, auto_apply, variables, etc., inherited from BaseRunRequest.

  class RunParams(BaseRunRequest):
      """Parameters for run operations without routing fields.
  
      This model provides all optional parameters that can be used when creating runs,
      reusing the field definitions from BaseRunRequest.
  
      Reference: https://developer.hashicorp.com/terraform/cloud-docs/api-docs/run#create-a-run
  
      Note:
          All fields are inherited from BaseRunRequest.
  
      See:
          docs/models/run.md for reference
      """
  
      # Inherits model_config and all fields from BaseRunRequest

• terraform_cloud_mcp/models/runs.py:340-374 (schema)

  Internal Pydantic model used by the create_run handler for API request validation, extending RunParams with workspace_id and configuration_version_id.

  class RunCreateRequest(BaseRunRequest):
      """Request model for creating a Terraform Cloud run.
  
      Validates and structures the request according to the Terraform Cloud API
      requirements for creating runs. The model inherits common run attributes from
      BaseRunRequest and adds workspace_id as a required parameter.
  
      Reference: https://developer.hashicorp.com/terraform/cloud-docs/api-docs/run#create-a-run
  
      Note:
          This inherits all configuration fields from BaseRunRequest
          and adds workspace_id as a required parameter.
          This model is typically used internally by the create_run tool function,
          which accepts parameters directly and constructs the request object.
  
      See:
          docs/models/run.md for reference
      """
  
      # Required fields
      workspace_id: str = Field(
          ...,
          # No alias needed as field name matches API field name
          description="The workspace ID to execute the run in (required)",
          pattern=r"^ws-[a-zA-Z0-9]{16}$",  # Standardized workspace ID pattern
      )
  
      # Optional fields specific to run creation
      configuration_version_id: Optional[str] = Field(
          None,
          alias="configuration-version-id",
          description="The configuration version ID to use",
          pattern=r"^cv-[a-zA-Z0-9]{16}$",
      )