terraform-cloud-mcp

Instructions

Implementation Reference

• terraform_cloud_mcp/tools/assessment_results.py:40-71 (handler)

  The main handler function for the 'get_assessment_json_output' tool. It validates the assessment_result_id using Pydantic models and performs an API request to the Terraform Cloud endpoint for JSON output, following redirects.

  @handle_api_errors
  async def get_assessment_json_output(assessment_result_id: str) -> APIResponse:
      """Retrieve the JSON execution plan from an assessment result.
  
      Gets the JSON representation of the plan execution details from an assessment,
      providing a machine-readable format of the planned resource changes.
  
      API endpoint: GET /api/v2/assessment-results/{assessment_result_id}/json-output
  
      Args:
          assessment_result_id: The ID of the assessment result to retrieve JSON output for (format: "asmtres-xxxxxxxx")
  
      Returns:
          The complete JSON formatted plan with resource changes, metadata,
          and planned actions. The redirect is automatically followed.
  
      Note:
          This endpoint requires admin level access to the workspace and cannot be accessed
          with organization tokens.
  
      See:
          docs/tools/assessment_results.md for reference documentation
      """
      # Validate parameters
      params = AssessmentOutputRequest(assessment_result_id=assessment_result_id)
  
      # Make API request with text acceptance since it may be a large JSON file
      return await api_request(
          f"assessment-results/{params.assessment_result_id}/json-output",
          accept_text=True,
      )

• terraform_cloud_mcp/models/assessment_results.py:39-71 (schema)

  Pydantic input schema models used for validating the assessment_result_id parameter in the tool handler. AssessmentOutputRequest is instantiated for validation.

  class AssessmentResultRequest(APIRequest):
      """Request model for retrieving assessment result details.
  
      Used to validate the assessment result ID parameter for API requests.
  
      Reference: https://developer.hashicorp.com/terraform/cloud-docs/api-docs/assessment-results#show-assessment-result
  
      See:
          docs/models/assessment_result.md for reference
      """
  
      assessment_result_id: str = Field(
          ...,
          # No alias needed as field name matches API parameter
          description="The ID of the assessment result to retrieve",
          pattern=r"^asmtres-[a-zA-Z0-9]{8,}$",  # Standard assessment result ID pattern
      )
  
  
  class AssessmentOutputRequest(AssessmentResultRequest):
      """Request model for retrieving assessment result outputs.
  
      Extends the base AssessmentResultRequest for specialized outputs like
      JSON plan, schema, and log output.
  
      Reference: https://developer.hashicorp.com/terraform/cloud-docs/api-docs/assessment-results#retrieve-the-json-output-from-the-assessment-execution
  
      See:
          docs/models/assessment_result.md for reference
      """
  
      pass  # Uses the same validation as the parent class

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

  The registration of the 'get_assessment_json_output' tool using FastMCP's mcp.tool() decorator in the main server file.

  mcp.tool()(assessment_results.get_assessment_json_output)