terraform-cloud-mcp

Instructions

Implementation Reference

• terraform_cloud_mcp/tools/projects.py:90-154 (handler)

  The handler function that executes the 'update_project' tool. It constructs the API payload using Pydantic models and sends a PATCH request to update the project in Terraform Cloud.

  async def update_project(
      project_id: str, params: Optional[ProjectParams] = None
  ) -> APIResponse:
      """Update an existing project.
  
      Modifies the settings of a Terraform Cloud project. This can be used to change
      attributes like name, description, auto-destroy duration, or tags. Only specified
      attributes will be updated; unspecified attributes remain unchanged.
  
      API endpoint: PATCH /projects/{project_id}
  
      Args:
          project_id: The ID of the project to update (format: "prj-xxxxxxxx")
          params: Project parameters to update (optional):
              - name: New name for the project
              - description: Human-readable description of the project
              - auto_destroy_activity_duration: How long each workspace should wait before
                auto-destroying (e.g., '14d', '24h')
              - tag_bindings: List of tag key-value pairs to bind to the project
  
      Returns:
          The updated project with all current settings and configuration
  
      See:
          docs/tools/project.md for reference documentation
      """
      # Extract parameters from the params object if provided
      param_dict = params.model_dump(exclude_none=True) if params else {}
  
      # Create request using Pydantic model
      request = ProjectUpdateRequest(project_id=project_id, **param_dict)
  
      # Create base API payload using utility function
      payload = create_api_payload(
          resource_type="projects",
          model=request,
          exclude_fields={"project_id"},
      )
  
      # Handle tag bindings if present
      if request.tag_bindings:
          tag_bindings_data = []
          for tag in request.tag_bindings:
              tag_bindings_data.append(
                  {
                      "type": "tag-bindings",
                      "attributes": {"key": tag.key, "value": tag.value},
                  }
              )
  
          if "relationships" not in payload["data"]:
              payload["data"]["relationships"] = {}
  
          payload["data"]["relationships"]["tag-bindings"] = {"data": tag_bindings_data}
  
      # Remove tag-bindings from attributes if present since we've moved them to relationships
      if "tag-bindings" in payload["data"]["attributes"]:
          del payload["data"]["attributes"]["tag-bindings"]
  
      # Log payload for debugging
      logger = logging.getLogger(__name__)
      logger.debug(f"Update project payload: {payload}")
  
      # Make API request
      return await api_request(f"projects/{project_id}", method="PATCH", data=payload)

• terraform_cloud_mcp/models/projects.py:159-178 (schema)

  Pydantic model used as input parameter 'params' for the update_project tool, defining optional fields like name, description, auto_destroy_activity_duration, and tag_bindings.

  class ProjectParams(BaseProjectRequest):
      """Parameters for project operations without routing fields.
  
      This model provides all optional parameters for creating or updating projects,
      reusing field definitions from BaseProjectRequest. It separates configuration
      parameters from routing information like organization and project ID.
  
      Reference: https://developer.hashicorp.com/terraform/cloud-docs/api-docs/projects
  
      Note:
          When updating a project, use this model to specify only the attributes
          you want to change. Unspecified attributes retain their current values.
          All fields are inherited from BaseProjectRequest.
  
      See:
          docs/models/project.md for reference
      """
  
      # Inherits model_config and all fields from BaseProjectRequest

• terraform_cloud_mcp/models/projects.py:136-158 (schema)

  Internal Pydantic model used within the handler to structure the update request payload, extending BaseProjectRequest with project_id.

  class ProjectUpdateRequest(BaseProjectRequest):
      """Request model for updating a Terraform Cloud project.
  
      Validates and structures the request for updating projects. Extends BaseProjectRequest
      with routing fields while keeping all configuration fields optional.
  
      Reference: https://developer.hashicorp.com/terraform/cloud-docs/api-docs/projects#update-a-project
  
      Note:
          This inherits all configuration fields from BaseProjectRequest
          and adds required routing field for the update operation.
  
      See:
          docs/models/project.md for reference
      """
  
      # Add project_id which is required for updates but not part of the project attributes payload
      project_id: str = Field(
          ...,
          description="The ID of the project to update",
      )

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

  Registers the update_project handler as an MCP tool with write permissions configuration.

  mcp.tool(**write_tool_config)(projects.update_project)