terraform-cloud-mcp

Instructions

Implementation Reference

• terraform_cloud_mcp/tools/plans.py:96-130 (handler)

  The async handler function that implements the core logic of the get_plan_logs tool. It validates the plan_id, fetches plan details to extract the log-read-url, and retrieves the raw logs.

  @handle_api_errors
  async def get_plan_logs(plan_id: str) -> APIResponse:
      """Retrieve logs from a plan.
  
      Gets the raw log output from a Terraform Cloud plan operation,
      providing detailed information about the execution plan.
  
      API endpoint: Uses the log-read-url from GET /plans/{plan_id}
  
      Args:
          plan_id: The ID of the plan to retrieve logs for (format: "plan-xxxxxxxx")
  
      Returns:
          The raw logs from the plan operation. The redirect to the log file
          is automatically followed.
  
      See:
          docs/tools/plan.md for reference documentation
      """
      # Validate parameters using existing model
      params = PlanRequest(plan_id=plan_id)
  
      # First get plan details to get the log URL
      plan_details = await api_request(f"plans/{params.plan_id}")
  
      # Extract log read URL
      log_read_url = (
          plan_details.get("data", {}).get("attributes", {}).get("log-read-url")
      )
      if not log_read_url:
          return {"error": "No log URL available for this plan"}
  
      # Use the enhanced api_request to fetch logs from the external URL
      return await api_request(log_read_url, external_url=True, accept_text=True)

• terraform_cloud_mcp/models/plans.py:111-128 (schema)

  Pydantic-based input schema model (PlanRequest) used for validating the plan_id parameter in the get_plan_logs handler.

  class PlanRequest(APIRequest):
      """Request model for retrieving a plan.
  
      Used to validate the plan ID parameter for API requests.
  
      Reference: https://developer.hashicorp.com/terraform/cloud-docs/api-docs/plans#show-a-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",
          pattern=r"^plan-[a-zA-Z0-9]{16}$",  # Standard plan ID pattern
      )

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

  Tool registration in the MCP server using FastMCP's mcp.tool() decorator, linking to the handler in plans module.

  mcp.tool()(plans.get_plan_logs)