terraform-cloud-mcp

Instructions

Implementation Reference

• terraform_cloud_mcp/tools/runs.py:298-329 (handler)

  The main handler function that executes the discard_run tool by POSTing to the Terraform Cloud API /runs/{run_id}/actions/discard endpoint with optional comment payload.

  @handle_api_errors
  async def discard_run(run_id: str, comment: str = "") -> APIResponse:
      """Discard a run that is paused waiting for confirmation
  
      Cancels a run without applying its changes, typically used when the plan
      shows undesired changes or after reviewing and rejecting a plan. This action
      removes the run from the queue and unlocks the workspace for new runs.
  
      API endpoint: POST /runs/{run_id}/actions/discard
  
      Args:
          run_id: The ID of the run to discard (format: "run-xxxxxxxx")
          comment: An optional explanation for why the run was discarded
  
      Returns:
          Run status update with discarded state information, timestamp of the
          discard action, and user information
  
      See:
          docs/tools/run.md for reference documentation
      """
      request = RunActionRequest(run_id=run_id, comment=comment)
  
      # Create payload if comment is provided
      payload = {}
      if request.comment:
          payload = {"comment": request.comment}
  
      # Make API request
      return await api_request(
          f"runs/{run_id}/actions/discard", method="POST", data=payload
      )

• terraform_cloud_mcp/models/runs.py:376-404 (schema)

  Pydantic model defining the input schema (run_id and optional comment) used by the discard_run handler for validation.

  class RunActionRequest(APIRequest):
      """Base request model for run actions like apply, discard, cancel, etc.
  
      This model provides common fields used in run action requests such as
      applying, discarding, or canceling runs. It includes the run ID and
      an optional comment field that can be included with the action.
  
      Reference: https://developer.hashicorp.com/terraform/cloud-docs/api-docs/run#apply-a-run
  
      Note:
          This model is used for multiple run action endpoints that share the
          same basic structure but perform different operations on the run.
  
      See:
          docs/models/run.md for reference
      """
  
      run_id: str = Field(
          ...,
          # No alias needed as field name matches API field name
          description="The ID of the run to perform an action on",
          pattern=r"^run-[a-zA-Z0-9]{16}$",
      )
      comment: Optional[str] = Field(
          None,
          # No alias needed as field name matches API field name
          description="An optional comment about the run",
      )

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

  MCP tool registration for discard_run using FastMCP's mcp.tool decorator with write permissions configuration.

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