get_repository_files

Instructions

Args:
    project_id: GitLab project ID
    path: Directory path (optional)
    ref: Branch/tag reference (default: main)
    token: GitLab Personal Access Token (optional)
    ctx: MCP context (automatically injected)

Implementation Reference

• gitlab_clone_mcp_server/server.py:288-311 (handler)

  The get_repository_files tool handler function. It is decorated with @mcp.tool(), takes project_id, path, ref, token, and ctx parameters. It calls the GitLab API endpoint /projects/{project_id}/repository/tree?path={path}&ref={ref} to list repository files and directories, then formats them with icons (📁 for directories, 📄 for files), limited to 20 items.

  @mcp.tool()
  async def get_repository_files(project_id: int, path: str = "", ref: str = "main", token: str = None, ctx=None) -> str:
      """Get repository files and directories.
      
      Args:
          project_id: GitLab project ID
          path: Directory path (optional)
          ref: Branch/tag reference (default: main)
          token: GitLab Personal Access Token (optional)
          ctx: MCP context (automatically injected)
      """
      endpoint = f"/projects/{project_id}/repository/tree?path={path}&ref={ref}"
      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 files found."
      
      files = []
      for item in data[:20]:
          icon = "📁" if item['type'] == 'tree' else "📄"
          files.append(f"{icon} {item['name']}")
      return "\n".join(files)

• gitlab_clone_mcp_server/server.py:289-291 (schema)

  The input schema for get_repository_files is defined implicitly via the function signature parameters: project_id (int, required), path (str, optional, default ''), ref (str, optional, default 'main'), token (str, optional), and ctx (optional). The docstring documents the Args as: project_id (GitLab project ID), path (Directory path), ref (Branch/tag reference, default: main).

  async def get_repository_files(project_id: int, path: str = "", ref: str = "main", token: str = None, ctx=None) -> str:
      """Get repository files and directories.

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

  The tool is registered via the @mcp.tool() decorator on line 288, which uses FastMCP's tool registration mechanism to register the function as an MCP tool named 'get_repository_files'.

  @mcp.tool()

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

  The make_gitlab_request helper function used by get_repository_files to make HTTP requests to the GitLab API. It handles token resolution (parameter, context headers, or environment variable), constructs the URL using GITLAB_URL, and makes async HTTP requests via httpx.

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