terraform-cloud-mcp

Instructions

Implementation Reference

• terraform_cloud_mcp/tools/runs.py:103-168 (handler)

  The handler function that executes the tool logic: creates a validated request model, builds query parameters, and makes the API request to list runs in the specified workspace.

  @handle_api_errors
  async def list_runs_in_workspace(
      workspace_id: str,
      page_number: int = 1,
      page_size: int = 20,
      filter_operation: Optional[str] = None,
      filter_status: Optional[str] = None,
      filter_source: Optional[str] = None,
      filter_status_group: Optional[str] = None,
      filter_timeframe: Optional[str] = None,
      filter_agent_pool_names: Optional[str] = None,
      search_user: Optional[str] = None,
      search_commit: Optional[str] = None,
      search_basic: Optional[str] = None,
  ) -> APIResponse:
      """List runs in a workspace with filtering and pagination
  
      Retrieves run history for a specific workspace with options to filter by status,
      operation type, source, and other criteria. Useful for auditing changes, troubleshooting,
      or monitoring deployment history.
  
      API endpoint: GET /workspaces/{workspace_id}/runs
  
      Args:
          workspace_id: The workspace ID to list runs for (format: "ws-xxxxxxxx")
          page_number: Page number to fetch (default: 1)
          page_size: Number of results per page (default: 20)
          filter_operation: Filter by operation type
          filter_status: Filter by status
          filter_source: Filter by source
          filter_status_group: Filter by status group
          filter_timeframe: Filter by timeframe
          filter_agent_pool_names: Filter by agent pool names
          search_user: Search by VCS username
          search_commit: Search by commit SHA
          search_basic: Search across run ID, message, commit SHA, and username
  
      Returns:
          List of runs with metadata, status info, and pagination details
  
      See:
          docs/tools/run.md for reference documentation
      """
      # Create request using Pydantic model for validation
      request = RunListInWorkspaceRequest(
          workspace_id=workspace_id,
          page_number=page_number,
          page_size=page_size,
          filter_operation=filter_operation,
          filter_status=filter_status,
          filter_source=filter_source,
          filter_status_group=filter_status_group,
          filter_timeframe=filter_timeframe,
          filter_agent_pool_names=filter_agent_pool_names,
          search_user=search_user,
          search_commit=search_commit,
          search_basic=search_basic,
      )
  
      # Use the unified query params utility function
      params = query_params(request)
  
      # Make API request
      return await api_request(
          f"workspaces/{workspace_id}/runs", method="GET", params=params
      )

• terraform_cloud_mcp/models/runs.py:147-201 (schema)

  Pydantic model defining and validating the input parameters for the list_runs_in_workspace tool, including workspace_id and various filter/search options.

  class RunListInWorkspaceRequest(APIRequest):
      """Request parameters for listing runs in a workspace.
  
      Used with the GET /workspaces/{workspace_id}/runs endpoint to retrieve
      and filter run data for a specific workspace.
  
      Reference: https://developer.hashicorp.com/terraform/cloud-docs/api-docs/run#list-runs-in-a-workspace
  
      See:
          docs/models/run.md for reference
      """
  
      workspace_id: str = Field(
          ...,
          description="The workspace ID to list runs for",
          pattern=r"^ws-[a-zA-Z0-9]{16}$",  # Standardized workspace ID pattern
      )
      page_number: Optional[int] = Field(1, ge=1, description="Page number to fetch")
      page_size: Optional[int] = Field(
          20, ge=1, le=100, description="Number of results per page"
      )
      filter_operation: Optional[str] = Field(
          None,
          description="Filter runs by operation type, comma-separated",
          max_length=100,
      )
      filter_status: Optional[str] = Field(
          None, description="Filter runs by status, comma-separated", max_length=100
      )
      filter_source: Optional[str] = Field(
          None, description="Filter runs by source, comma-separated", max_length=100
      )
      filter_status_group: Optional[str] = Field(
          None, description="Filter runs by status group", max_length=50
      )
      filter_timeframe: Optional[str] = Field(
          None, description="Filter runs by timeframe", max_length=50
      )
      filter_agent_pool_names: Optional[str] = Field(
          None,
          description="Filter runs by agent pool names, comma-separated",
          max_length=100,
      )
      search_user: Optional[str] = Field(
          None, description="Search for runs by VCS username", max_length=100
      )
      search_commit: Optional[str] = Field(
          None, description="Search for runs by commit SHA", max_length=40
      )
      search_basic: Optional[str] = Field(
          None,
          description="Basic search across run ID, message, commit SHA, and username",
          max_length=100,
      )

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

  Registers the list_runs_in_workspace function as an MCP tool in the FastMCP server.

  mcp.tool()(runs.list_runs_in_workspace)