Gradle MCP Server

Instructions

Implementation Reference

• src/gradle_mcp/server.py:98-127 (handler)

  The main execution handler for the list_project_tasks MCP tool, decorated with @mcp.tool() for automatic registration. It retrieves the GradleWrapper, normalizes the project argument, lists tasks, and maps them to TaskInfo objects.
  @mcp.tool() async def list_project_tasks(project: Optional[str] = None, ctx: Context = None) -> list[TaskInfo]: """List all tasks available in a Gradle project. Args: project: Project path (e.g., ':app' or 'lib:module'). Use None, empty string, or ':' for root project. ctx: MCP Context. Returns: List of available tasks in the project. """ try: await ctx.info(f"Listing tasks for project: {project or 'root'}") gradle = _get_gradle_wrapper(ctx) # Normalize root project: None, empty, or ":" all mean root project_arg = project if project and project != "" else ":" tasks = gradle.list_tasks(project_arg) await ctx.info(f"Found {len(tasks)} tasks for project {project_arg}") return [ TaskInfo( name=t.name, project=t.project, description=t.description, group=t.group, ) for t in tasks ] except Exception as e: raise ValueError(f"Failed to list tasks: {str(e)}")
• src/gradle_mcp/server.py:32-38 (schema)

  Pydantic model defining the output schema for list_project_tasks tool responses.
  class TaskInfo(BaseModel): """Information about a Gradle task.""" name: str project: str description: Optional[str] = None group: Optional[str] = None
• src/gradle_mcp/server.py:40-71 (helper)

  Helper function used by the tool handler to initialize and configure the GradleWrapper instance based on environment variables.
  def _get_gradle_wrapper(ctx: Optional[Context] = None) -> GradleWrapper: """Get a GradleWrapper instance, optionally using context to determine project root. Respects the following environment variables: - GRADLE_PROJECT_ROOT: Root directory of Gradle project (default: current directory) - GRADLE_WRAPPER: Path to Gradle wrapper script (optional, auto-detected if not set) Args: ctx: MCP Context (optional). Returns: GradleWrapper instance. Raises: FileNotFoundError: If Gradle wrapper cannot be found. """ project_root = os.getenv("GRADLE_PROJECT_ROOT") or os.getcwd() wrapper_path = os.getenv("GRADLE_WRAPPER") gradle = GradleWrapper(project_root) # If a custom wrapper path is specified, override the auto-detected one if wrapper_path: wrapper_path_obj = Path(wrapper_path) if not wrapper_path_obj.exists(): raise FileNotFoundError( f"Gradle wrapper not found at specified path: {wrapper_path}. " "Please verify GRADLE_WRAPPER environment variable." ) gradle.wrapper_script = wrapper_path_obj return gradle
• src/gradle_mcp/gradle.py:329-411 (helper)

  Core helper method in GradleWrapper class that executes 'gradle tasks --all' (or project:tasks), parses the output to extract task names, groups, and descriptions, and returns a list of GradleTask objects.
  def list_tasks(self, project: str = ":") -> list[GradleTask]: """List all available tasks for a specific Gradle project. Args: project: Project name (e.g., ':app'). Use ':' or empty string for root project. Returns: List of GradleTask objects. Raises: subprocess.CalledProcessError: If Gradle command fails. """ try: # Use tasks --all to get all tasks including inherited ones # For root project (: or empty), use just "tasks", for subprojects use "project:tasks" is_root = project == ":" or project == "" or project is None task_cmd = "tasks" if is_root else f"{project}:tasks" result = subprocess.run( [str(self.wrapper_script), task_cmd, "--all"], cwd=str(self.project_root), capture_output=True, text=True, check=True, ) tasks = [] in_task_section = False current_group = None for line in result.stdout.split("\n"): line_stripped = line.strip() # Skip empty lines if not line_stripped: continue # Look for task group headers (end with "tasks") if line_stripped.endswith(" tasks") and line_stripped[0].isupper(): in_task_section = True current_group = line_stripped.replace(" tasks", "").strip() continue # Skip separators and rules if line_stripped.startswith("-") or "Pattern:" in line_stripped: continue # Stop at help text if "To see all tasks" in line_stripped or line_stripped.startswith("BUILD"): break # Parse task lines when in a task section if in_task_section: # Task lines format: "taskName - description" task_match = re.match(r"^(\w+)\s+-\s+(.+)$", line_stripped) if task_match: task_name = task_match.group(1) description = task_match.group(2) tasks.append( GradleTask( name=task_name, project=project, description=description, group=current_group, ) ) # Also handle tasks without description elif re.match(r"^(\w+)$", line_stripped): task_name = line_stripped tasks.append( GradleTask( name=task_name, project=project, description="", group=current_group, ) ) return tasks except subprocess.CalledProcessError as e: raise RuntimeError( f"Failed to list tasks for project {project}: {e.stderr}" ) from e
• src/gradle_mcp/gradle.py:23-29 (schema)

  Dataclass defining the structure for individual Gradle tasks, used by the list_tasks helper and mapped to TaskInfo in the tool handler.
  @dataclass class GradleTask: """Represents a Gradle task.""" name: str project: str description: Optional[str] = None group: Optional[str] = None