terraform-cloud-mcp

Instructions

Implementation Reference

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

  Main handler function implementing the list_runs_in_workspace tool. Validates inputs using Pydantic model, constructs query parameters, and makes GET request to Terraform Cloud API endpoint /workspaces/{workspace_id}/runs.
  @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 the input schema and validation rules for the list_runs_in_workspace tool parameters, including workspace_id, pagination, filters, and 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)

  Tool registration in the MCP server using the FastMCP mcp.tool() decorator, making list_runs_in_workspace available as an MCP tool.
  mcp.tool()(runs.list_runs_in_workspace)