terraform-cloud-mcp

Instructions

Implementation Reference

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

  The main handler function for the 'list_projects' tool. It validates input using ProjectListRequest model, builds query params, and makes a GET request to the Terraform Cloud API endpoint /organizations/{organization}/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/models/projects.py:32-67 (schema)

  Pydantic model defining the input schema and validation for the list_projects tool parameters, including organization, pagination, filters, and sort options.

  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)"
      )

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

  Registration of the list_projects tool using the MCP decorator mcp.tool() on the projects.list_projects function.

  mcp.tool()(projects.list_projects)