terraform-cloud-mcp

Instructions

params: Workspace parameters to update (optional):
    - name: New name for the workspace (if renaming)
    - description: Human-readable description of the workspace
    - execution_mode: How Terraform runs are executed (remote, local, agent)
    - terraform_version: Version of Terraform to use
    - working_directory: Subdirectory to use when running Terraform
    - vcs_repo: Version control repository configuration (oauth-token-id, identifier)
    - auto_apply: Whether to automatically apply successful plans
    - file_triggers_enabled: Whether file changes trigger runs
    - trigger_prefixes: Directories that trigger runs when changed
    - trigger_patterns: Glob patterns that trigger runs when files match
    - allow_destroy_plan: Whether to allow destruction plans
    - auto_apply_run_trigger: Whether to auto-apply changes from run triggers

Implementation Reference

• terraform_cloud_mcp/tools/workspaces.py:71-137 (handler)

  The handler function that implements the tool logic: accepts organization, workspace_name, and optional WorkspaceParams; builds WorkspaceUpdateRequest; creates API payload excluding routing fields; logs and sends PATCH request to Terraform Cloud API; returns the updated workspace response.

  @handle_api_errors
  async def update_workspace(
      organization: str, workspace_name: str, params: Optional[WorkspaceParams] = None
  ) -> APIResponse:
      """Update an existing workspace.
  
      Modifies the settings of a Terraform Cloud workspace. This can be used to change
      attributes like execution mode, VCS repository settings, description, or any other
      workspace configuration options. Only specified attributes will be updated;
      unspecified attributes remain unchanged.
  
      API endpoint: PATCH /organizations/{organization}/workspaces/{workspace_name}
  
      Args:
          organization: The name of the organization that owns the workspace
          workspace_name: The name of the workspace to update
  
          params: Workspace parameters to update (optional):
              - name: New name for the workspace (if renaming)
              - description: Human-readable description of the workspace
              - execution_mode: How Terraform runs are executed (remote, local, agent)
              - terraform_version: Version of Terraform to use
              - working_directory: Subdirectory to use when running Terraform
              - vcs_repo: Version control repository configuration (oauth-token-id, identifier)
              - auto_apply: Whether to automatically apply successful plans
              - file_triggers_enabled: Whether file changes trigger runs
              - trigger_prefixes: Directories that trigger runs when changed
              - trigger_patterns: Glob patterns that trigger runs when files match
              - allow_destroy_plan: Whether to allow destruction plans
              - auto_apply_run_trigger: Whether to auto-apply changes from run triggers
  
      Returns:
          The updated workspace with all current settings and configuration
  
      See:
          docs/tools/workspace.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 = WorkspaceUpdateRequest(
          organization=organization, workspace_name=workspace_name, **param_dict
      )
  
      # Create API payload using utility function
      payload = create_api_payload(
          resource_type="workspaces",
          model=request,
          exclude_fields={"organization", "workspace_name"},
      )
  
      # Log payload for debugging
      logger = logging.getLogger(__name__)
      logger.debug(f"Update workspace payload: {payload}")
  
      # Make API request
      response = await api_request(
          f"organizations/{organization}/workspaces/{workspace_name}",
          method="PATCH",
          data=payload,
      )
  
      # Log response for debugging
      logger.debug(f"Update workspace response: {response}")
  
      return response

• terraform_cloud_mcp/models/workspaces.py:80-202 (schema)

  Pydantic base model defining all configurable parameters for workspace updates (name, description, execution_mode, vcs_repo, auto_apply, terraform_version, trigger_patterns, etc.). Inherited by WorkspaceParams (tool input) and WorkspaceUpdateRequest (internal payload).

  class BaseWorkspaceRequest(APIRequest):
      """Base class for workspace create and update requests with common fields.
  
      This includes common fields used in request payloads for workspace
      creation and update APIs, providing a foundation for more specific workspace models.
  
      Reference: https://developer.hashicorp.com/terraform/cloud-docs/api-docs/workspaces
  
      Note:
          This class inherits model_config from APIRequest -> BaseModelConfig and provides
          default values for most fields based on Terraform Cloud API defaults.
  
      See:
          docs/models/workspace.md for detailed field descriptions and usage examples
      """
  
      # Fields common to both create and update requests with API defaults from docs
      name: Optional[str] = Field(
          None,
          # No alias needed as field name matches API field name
          description="Name of the workspace",
      )
      description: Optional[str] = Field(
          None,
          # No alias needed as field name matches API field name
          description="Description of the workspace",
      )
      execution_mode: Optional[Union[str, ExecutionMode]] = Field(
          ExecutionMode.REMOTE,
          alias="execution-mode",
          description="How operations are executed",
      )
      agent_pool_id: Optional[str] = Field(
          None, alias="agent-pool-id", description="The ID of the agent pool"
      )
      assessments_enabled: Optional[bool] = Field(
          False,
          alias="assessments-enabled",
          description="Whether to perform health assessments",
      )
      auto_apply: Optional[bool] = Field(
          False,
          alias="auto-apply",
          description="Whether to automatically apply changes in runs triggered by VCS, UI, or CLI",
      )
      auto_apply_run_trigger: Optional[bool] = Field(
          False,
          alias="auto-apply-run-trigger",
          description="Whether to automatically apply changes initiated by run triggers",
      )
      auto_destroy_at: Optional[str] = Field(
          None,
          alias="auto-destroy-at",
          description="Timestamp when the next scheduled destroy run will occur",
      )
      auto_destroy_activity_duration: Optional[str] = Field(
          None,
          alias="auto-destroy-activity-duration",
          description="Value and units for automatically scheduled destroy runs based on workspace activity",
      )
      file_triggers_enabled: Optional[bool] = Field(
          True,
          alias="file-triggers-enabled",
          description="Whether to filter runs based on file paths",
      )
      working_directory: Optional[str] = Field(
          None,
          alias="working-directory",
          description="The directory to execute commands in",
      )
      speculative_enabled: Optional[bool] = Field(
          True,
          alias="speculative-enabled",
          description="Whether this workspace allows speculative plans",
      )
      terraform_version: Optional[str] = Field(
          "latest",
          alias="terraform-version",
          description="Specifies the version of Terraform to use for this workspace",
      )
      global_remote_state: Optional[bool] = Field(
          False,
          alias="global-remote-state",
          description="Whether to allow all workspaces to access this workspace's state",
      )
      vcs_repo: Optional[Union[VcsRepoConfig, None]] = Field(
          None,
          alias="vcs-repo",
          description="Settings for the workspace's VCS repository",
      )
      allow_destroy_plan: Optional[bool] = Field(
          True,
          alias="allow-destroy-plan",
          description="Whether to allow destruction plans",
      )
      queue_all_runs: Optional[bool] = Field(
          False,
          alias="queue-all-runs",
          description="Whether runs should be queued immediately",
      )
      source_name: Optional[str] = Field(
          None,
          alias="source-name",
          description="Indicates where the workspace settings originated",
      )
      source_url: Optional[str] = Field(
          None, alias="source-url", description="URL to origin source"
      )
      trigger_prefixes: Optional[List[str]] = Field(
          None, alias="trigger-prefixes", description="List of paths that trigger runs"
      )
      trigger_patterns: Optional[List[str]] = Field(
          None,
          alias="trigger-patterns",
          description="List of glob patterns that trigger runs",
      )
      setting_overwrites: Optional[Dict[str, bool]] = Field(
          None,
          alias="setting-overwrites",
          description="Specifies attributes that have organization-level defaults",
      )

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

  MCP tool registration calling mcp.tool on workspaces.update_workspace with write_tool_config (enabled unless read-only mode, non-readOnlyHint).

  mcp.tool(**write_tool_config)(workspaces.update_workspace)

• terraform_cloud_mcp/models/workspaces.py:233-260 (schema)

  Pydantic model used internally to construct the update request, adding required organization and workspace_name fields to BaseWorkspaceRequest.

  class WorkspaceUpdateRequest(BaseWorkspaceRequest):
      """Request model for updating a Terraform Cloud workspace.
  
      Validates and structures the request for updating workspaces. Extends BaseWorkspaceRequest
      with routing fields while keeping all configuration fields optional.
  
      Reference: https://developer.hashicorp.com/terraform/cloud-docs/api-docs/workspaces#update-a-workspace
  
      Note:
          This inherits all configuration fields from BaseWorkspaceRequest
          and adds required routing fields for the update operation.
  
      See:
          docs/models/workspace.md for reference
      """
  
      # Add fields which are required for updates but not part of the workspace attributes payload
      organization: str = Field(
          ...,
          # No alias needed as field name matches API field name
          description="The name of the organization that owns the workspace",
      )
      workspace_name: str = Field(
          ...,
          # No alias needed as field name matches API field name
          description="The name of the workspace to update",
      )

• terraform_cloud_mcp/models/workspaces.py:262-281 (schema)

  Pydantic model for optional params argument in tool signature, directly inheriting all fields from BaseWorkspaceRequest.

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