terraform-cloud-mcp

Instructions

Implementation Reference

• terraform_cloud_mcp/tools/projects.py:157-211 (handler)

  The main handler function `list_projects` that executes the tool logic: validates inputs using ProjectListRequest, constructs query parameters, and makes a GET request to the Terraform Cloud API endpoint `/organizations/{organization}/projects` to retrieve a paginated list of projects.
  @handle_api_errors async def list_projects( organization: str, page_number: int = 1, page_size: int = 20, q: Optional[str] = None, filter_names: Optional[str] = None, filter_permissions_update: Optional[bool] = None, filter_permissions_create_workspace: Optional[bool] = None, sort: Optional[str] = None, ) -> APIResponse: """List projects in an organization. Retrieves a paginated list of all projects in a Terraform Cloud organization. Results can be filtered using a search string or permissions filters to find specific projects. API endpoint: GET /organizations/{organization}/projects Args: organization: The name of the organization to list projects from page_number: The page number to return (default: 1) page_size: The number of items per page (default: 20, max: 100) q: Optional search query to filter projects by name filter_names: Filter projects by name (comma-separated list) filter_permissions_update: Filter projects that the user can update filter_permissions_create_workspace: Filter projects that the user can create workspaces in sort: Sort projects by name ('name' or '-name' for descending) Returns: Paginated list of projects with their configuration settings and metadata See: docs/tools/project.md for reference documentation """ # Create request using Pydantic model for validation request = ProjectListRequest( organization=organization, page_number=page_number, page_size=page_size, q=q, filter_names=filter_names, filter_permissions_update=filter_permissions_update, filter_permissions_create_workspace=filter_permissions_create_workspace, sort=sort, ) # Use the unified query params utility function params = query_params(request) # Make API request return await api_request( f"organizations/{organization}/projects", method="GET", params=params )
• terraform_cloud_mcp/server.py:96-96 (registration)

  The registration of the `list_projects` tool in the MCP server using the `mcp.tool()` decorator, referencing the handler from the projects module.
  mcp.tool()(projects.list_projects)
• terraform_cloud_mcp/models/projects.py:32-67 (schema)

  Pydantic model `ProjectListRequest` providing input schema validation for the list_projects tool parameters including organization, pagination, search query, filters, and sorting.
  class ProjectListRequest(APIRequest): """Request parameters for listing projects in an organization. Defines the parameters for the project listing API including pagination and search filtering options. Reference: https://developer.hashicorp.com/terraform/cloud-docs/api-docs/projects#list-projects See: docs/models/project.md for reference """ organization: str = Field( ..., description="The name of the organization to list projects from", 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" ) q: Optional[str] = Field(None, description="Search query for name") filter_names: Optional[str] = Field( None, description="Filter projects by name (comma-separated)" ) filter_permissions_update: Optional[bool] = Field( None, description="Filter projects by update permission" ) filter_permissions_create_workspace: Optional[bool] = Field( None, description="Filter projects by create workspace permission" ) sort: Optional[str] = Field( None, description="Sort projects by name ('name' or '-name' for descending)" )