terraform-cloud-mcp

Instructions

Implementation Reference

• terraform_cloud_mcp/tools/runs.py:172-240 (handler)

  The main execution handler for the 'list_runs_in_organization' tool. It validates inputs using the Pydantic model, builds query parameters, and performs the API request to list runs across all workspaces in the specified organization.
  async def list_runs_in_organization( organization: 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, filter_workspace_names: Optional[str] = None, search_user: Optional[str] = None, search_commit: Optional[str] = None, search_basic: Optional[str] = None, ) -> APIResponse: """List runs across all workspaces in an organization Retrieves run history across all workspaces in an organization with powerful filtering. Useful for organization-wide auditing, monitoring deployments across teams, or finding specific runs by commit or author. API endpoint: GET /organizations/{organization}/runs Args: organization: The organization name 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 filter_workspace_names: Filter by workspace names search_user: Search by VCS username search_commit: Search by commit SHA search_basic: Basic search across run attributes Returns: List of runs across workspaces with metadata and pagination details See: docs/tools/run.md for reference documentation """ # Create request using Pydantic model for validation request = RunListInOrganizationRequest( organization=organization, 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, filter_workspace_names=filter_workspace_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"organizations/{organization}/runs", method="GET", params=params )
• terraform_cloud_mcp/models/runs.py:203-264 (schema)

  Pydantic model (RunListInOrganizationRequest) that defines and validates all input parameters for the list_runs_in_organization tool, including organization name, pagination, and various filtering options.
  class RunListInOrganizationRequest(APIRequest): """Request parameters for listing runs in an organization. These parameters map to the query parameters in the runs API. The endpoint returns a paginated list of runs across all workspaces in an organization, with options for filtering by workspace name, status, and other criteria. Reference: https://developer.hashicorp.com/terraform/cloud-docs/api-docs/run#list-runs-in-an-organization See: docs/models/run.md for reference """ organization: str = Field( ..., description="The organization name", min_length=3, pattern=r"^[a-z0-9][-a-z0-9_]*[a-z0-9]$", ) 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, ) filter_workspace_names: Optional[str] = Field( None, description="Filter runs by workspace names, comma-separated", max_length=250, ) 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:66-66 (registration)

  The MCP tool registration decorator that exposes the list_runs_in_organization handler as an MCP tool.
  mcp.tool()(runs.list_runs_in_organization)