list_projects

Instructions

Args:
    owned: If True, only show owned projects. If False, show all accessible projects.
    per_page: Number of projects per page (max 100)
    token: GitLab Personal Access Token (optional)
    ctx: MCP context (automatically injected)

Implementation Reference

• gitlab_clone_mcp_server/server.py:95-119 (handler)

  The actual handler function for the 'list_projects' tool. It calls the GitLab API /projects endpoint with optional owned filter, formats project names, paths, and IDs into a bulleted list.

  @mcp.tool()
  async def list_projects(owned: bool = False, per_page: int = 20, token: str = None, ctx=None) -> str:
      """List GitLab projects.
      
      Args:
          owned: If True, only show owned projects. If False, show all accessible projects.
          per_page: Number of projects per page (max 100)
          token: GitLab Personal Access Token (optional)
          ctx: MCP context (automatically injected)
      """
      per_page = min(per_page, 100)
      endpoint = f"/projects?membership=true&per_page={per_page}" + ("&owned=true" if owned else "")
      data = await make_gitlab_request(endpoint, ctx=ctx, token=token)
      
      if isinstance(data, dict) and "error" in data:
          return f"Error: {data['error']}"
      
      if not data:
          return "No projects found."
      
      projects = []
      for project in data:
          projects.append(f"• {project['name']} ({project['path_with_namespace']}) - ID: {project['id']}")
      
      return "\n".join(projects)

• gitlab_clone_mcp_server/server.py:95-95 (registration)

  The @mcp.tool() decorator registers list_projects as an MCP tool named 'list_projects'.

  @mcp.tool()

• gitlab_clone_mcp_server/server.py:11-52 (helper)

  Helper function used by list_projects (and all other tools) to make authenticated requests to the GitLab API. Handles token resolution from parameters, context headers, or environment variables, and builds the API URL.

  async def make_gitlab_request(endpoint: str, method: str = "GET", data: dict = None, ctx=None, token: str = None) -> dict[str, Any] | None:
      """Make a request to GitLab API with proper error handling."""
      # Priority: 1. Explicit token parameter, 2. Context headers, 3. Environment variable
      
      # If no explicit token provided, try to get from context
      if not token and ctx and hasattr(ctx, 'request_context') and ctx.request_context:
          # Try to get from request headers
          if hasattr(ctx.request_context, 'headers'):
              token = ctx.request_context.headers.get('GITLAB_TOKEN')
      
      # Fallback to environment variable
      if not token:
          token = os.getenv("GITLAB_TOKEN")
      
      if not token:
          return {"error": "GitLab token not provided. Please provide a token parameter, GITLAB_TOKEN in the request headers, or set the environment variable."}
      
      # Get GitLab URL (from context or environment)
      gitlab_url = os.getenv("GITLAB_URL", "https://gitlab.com")
      
      headers = {
          "PRIVATE-TOKEN": token,
          "Content-Type": "application/json"
      }
      
      url = f"{gitlab_url}/api/v4{endpoint}"
      
      async with httpx.AsyncClient() as client:
          try:
              if method == "GET":
                  response = await client.get(url, headers=headers, timeout=30.0)
              elif method == "POST":
                  response = await client.post(url, headers=headers, json=data, timeout=30.0)
              elif method == "PUT":
                  response = await client.put(url, headers=headers, json=data, timeout=30.0)
              elif method == "DELETE":
                  response = await client.delete(url, headers=headers, timeout=30.0)
              
              response.raise_for_status()
              return response.json() if response.content else {"success": True}
          except Exception as e:
              return {"error": str(e)}