Gradle MCP Server

Instructions

Implementation Reference

• src/gradle_mcp/server.py:256-313 (handler)

  Main handler function for 'list_project_tasks' MCP tool. Decorated with @mcp.tool() for registration and execution. Calls GradleWrapper.list_tasks to fetch and parse tasks, converts to Pydantic models, and handles context logging.
  @mcp.tool() async def list_project_tasks( project: str | None = None, include_descriptions: bool = False, group: str | None = None, ctx: Context | None = None, ) -> list[GroupedTasksInfo]: """List all tasks available in a Gradle project. Returns a nested structure grouped by task group. This is more compact than a flat list and avoids repeating project/group information for each task. Args: project: Project path (e.g., ':app' or 'lib:module'). Use None, empty string, or ':' for root project. include_descriptions: If True, include task descriptions in the response. If False, return only task names for a more compact response. group: Optional group name to filter tasks (e.g., 'Build', 'Verification'). Case-insensitive. If not provided, all groups are returned. Returns: List of grouped tasks. Each group contains a group name and list of tasks. If include_descriptions is True, tasks include name and description. If include_descriptions is False, tasks are just name strings. """ try: if ctx: 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 ":" grouped_tasks = gradle.list_tasks(project_arg, include_descriptions, group) if ctx: total_tasks = sum(len(g.tasks) for g in grouped_tasks) group_info = f" (filtered by group '{group}')" if group else "" await ctx.info( f"Found {total_tasks} tasks in {len(grouped_tasks)} groups for project {project_arg}{group_info}" ) # Convert to response model result = [] for group in grouped_tasks: if include_descriptions: # Tasks are TaskWithDescription objects tasks = [ TaskWithDescriptionInfo(name=t.name, description=t.description) for t in group.tasks ] else: # Tasks are already strings tasks = group.tasks result.append(GroupedTasksInfo(group=group.group, tasks=tasks)) return result except Exception as e: raise ValueError(f"Failed to list tasks: {str(e)}") from e
• src/gradle_mcp/server.py:161-177 (schema)

  Pydantic BaseModel classes defining the input parameters schema (via function signature) and output schema (list[GroupedTasksInfo]) for the list_project_tasks tool.
  class TaskWithDescriptionInfo(BaseModel): """Task with its description.""" name: str description: str class GroupedTasksInfo(BaseModel): """Tasks grouped by their group name. When include_descriptions is True, tasks contains TaskWithDescriptionInfo objects. When include_descriptions is False, tasks contains task name strings. """ group: str tasks: list[TaskWithDescriptionInfo] | list[str]
• src/gradle_mcp/server.py:179-229 (helper)

  Utility function to create and configure a GradleWrapper instance, respecting environment variables and logging configuration details.
  def _get_gradle_wrapper(ctx: Context | None = 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) - GRADLE_OPTS: JVM options for the Gradle client (logged for visibility) - JAVA_OPTS: General Java options (logged for visibility) Args: ctx: MCP Context (optional). Returns: GradleWrapper instance. Raises: FileNotFoundError: If Gradle wrapper cannot be found. """ import logging logger = logging.getLogger(__name__) project_root = os.getenv("GRADLE_PROJECT_ROOT") or os.getcwd() wrapper_path = os.getenv("GRADLE_WRAPPER") # Log environment variables for debugging visibility gradle_opts = os.getenv("GRADLE_OPTS") java_opts = os.getenv("JAVA_OPTS") if gradle_opts: logger.debug(f"GRADLE_OPTS is set: {gradle_opts}") if java_opts: logger.debug(f"JAVA_OPTS is set: {java_opts}") if wrapper_path: logger.debug(f"GRADLE_WRAPPER is set: {wrapper_path}") logger.debug(f"Using project root: {project_root}") 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:781-884 (helper)

  Core helper method in GradleWrapper class that executes 'gradle tasks --all', parses the output to group tasks by category, filters by group if specified, and returns structured data used by the MCP tool handler.
  def list_tasks( self, project: str = ":", include_descriptions: bool = True, group: str | None = None, ) -> list[GroupedTasks]: """List all available tasks for a specific Gradle project. Returns a nested structure grouped by task group. When include_descriptions is True, each task includes its description. When False, only task names are returned for a more compact response. Args: project: Project name (e.g., ':app'). Use ':' or empty string for root project. include_descriptions: If True, include task descriptions. If False, return only task names for a more compact response. group: Optional group name to filter tasks. If provided, only tasks from this group will be returned. Case-insensitive matching. Returns: List of GroupedTasks objects, each containing a group name and its tasks. Tasks are either TaskWithDescription objects (if include_descriptions=True) or plain task name strings (if include_descriptions=False). 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, env=self._build_execution_environment(), ) # Use dict to group tasks by group name, preserving order groups: dict[str, list[TaskWithDescription] | list[str]] = {} in_task_section = False current_group: str | None = 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() if current_group not in groups: groups[current_group] = [] 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 and current_group is not None: # 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) if include_descriptions: groups[current_group].append( TaskWithDescription(name=task_name, description=description) ) else: groups[current_group].append(task_name) # Also handle tasks without description elif re.match(r"^(\w+)$", line_stripped): task_name = line_stripped if include_descriptions: groups[current_group].append( TaskWithDescription(name=task_name, description="") ) else: groups[current_group].append(task_name) # Convert to list of GroupedTasks, optionally filtering by group name result = [] for group_name, task_list in groups.items(): # Filter by group if specified (case-insensitive) if group is not None and group_name.lower() != group.lower(): continue result.append(GroupedTasks(group=group_name, tasks=task_list)) return result except subprocess.CalledProcessError as e: raise RuntimeError(f"Failed to list tasks for project {project}: {e.stderr}") from e