terraform-cloud-mcp

Instructions

Implementation Reference

• terraform_cloud_mcp/tools/plans.py:44-67 (handler)

  The handler function that executes the tool logic: validates the plan_id using PlanJsonOutputRequest model and fetches the JSON plan output from the Terraform Cloud API endpoint /plans/{plan_id}/json-output.

  @handle_api_errors
  async def get_plan_json_output(plan_id: str) -> APIResponse:
      """Retrieve the JSON execution plan.
  
      Gets the JSON representation of a plan's execution details, providing a
      machine-readable format of the planned resource changes.
  
      API endpoint: GET /plans/{plan_id}/json-output
  
      Args:
          plan_id: The ID of the plan to retrieve JSON output for (format: "plan-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 = PlanJsonOutputRequest(plan_id=plan_id)
  
      # Make API request
      return await api_request(f"plans/{params.plan_id}/json-output")

• terraform_cloud_mcp/models/plans.py:130-146 (schema)

  Pydantic-based input schema model (PlanJsonOutputRequest) for validating the plan_id parameter with regex pattern matching Terraform Cloud plan ID format.

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

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

  Tool registration in the MCP server using FastMCP's mcp.tool() decorator, binding the handler function.

  mcp.tool()(plans.get_plan_json_output)