terraform-cloud-mcp

Instructions

Implementation Reference

• terraform_cloud_mcp/tools/plans.py:70-93 (handler)

  The core handler function for the 'get_run_plan_json_output' tool. It validates the input run_id using a Pydantic model and fetches the JSON plan output via the Terraform Cloud API endpoint /runs/{run_id}/plan/json-output.

  @handle_api_errors
  async def get_run_plan_json_output(run_id: str) -> APIResponse:
      """Retrieve the JSON execution plan from a run.
  
      Gets the JSON representation of a run's current plan execution details,
      providing a machine-readable format of the planned resource changes.
  
      API endpoint: GET /runs/{run_id}/plan/json-output
  
      Args:
          run_id: The ID of the run to retrieve plan JSON output for (format: "run-xxxxxxxx")
  
      Returns:
          The complete JSON formatted plan with resource changes, metadata,
          and planned actions. The redirect is automatically followed.
  
      See:
          docs/tools/plan.md for reference documentation
      """
      # Validate parameters
      params = RunPlanJsonOutputRequest(run_id=run_id)
  
      # Make API request
      return await api_request(f"runs/{params.run_id}/plan/json-output")

• terraform_cloud_mcp/models/plans.py:149-166 (schema)

  Pydantic input validation model for the tool's run_id parameter, enforcing the standard Terraform Cloud run ID format (run-[a-zA-Z0-9]{16}).

  class RunPlanJsonOutputRequest(APIRequest):
      """Request model for retrieving a run's plan JSON output.
  
      Used to validate the run ID parameter for JSON output API requests.
  
      Reference: https://developer.hashicorp.com/terraform/cloud-docs/api-docs/plans#retrieve-the-json-execution-plan-from-a-run
  
      See:
          docs/models/plan.md for reference
      """
  
      run_id: str = Field(
          ...,
          # No alias needed as field name matches API parameter
          description="The ID of the run to retrieve plan JSON output for",
          pattern=r"^run-[a-zA-Z0-9]{16}$",  # Standard run ID pattern
      )

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

  Registers the get_run_plan_json_output handler as an MCP tool using FastMCP's mcp.tool() decorator.

  mcp.tool()(plans.get_run_plan_json_output)