Gradle MCP Server

Instructions

Implementation Reference

• src/gradle_mcp/server.py:190-234 (handler)

  MCP tool handler for the 'clean' tool. Delegates to GradleWrapper.clean() with logging and error handling.
  @mcp.tool() async def clean( project: Optional[str] = None, ctx: Context = None, ) -> TaskResult: """Clean build artifacts for a Gradle project. This is the only tool that should be used for cleaning tasks. Args: project: Project path (e.g., ':app'). Use None, empty string, or ':' for root project. Returns: TaskResult with success status and error message if failed. """ try: await ctx.info(f"Cleaning project: {project or 'root'}") gradle = _get_gradle_wrapper(ctx) # clean now handles progress reporting internally by parsing Gradle output result = await gradle.clean(project, ctx) # Log Gradle output if result.get("stdout"): await ctx.debug(f"Gradle stdout:\n{result['stdout']}") if result.get("stderr"): await ctx.debug(f"Gradle stderr:\n{result['stderr']}") if result["success"]: await ctx.info(f"Clean completed successfully for project {project or 'root'}") else: await ctx.error(f"Clean failed for project {project or 'root'}", extra={"error": result.get('error')}) return TaskResult( success=result["success"], error=result.get("error"), ) except Exception as e: return TaskResult( success=False, error=str(e), )
• src/gradle_mcp/gradle.py:519-609 (helper)

  Core implementation of the clean operation in the GradleWrapper class. Executes 'gradlew clean' (or project-specific) subprocess with real-time output parsing and progress reporting.
  async def clean(self, project: Optional[str] = None, ctx: Optional['Context'] = None) -> dict: """Run the clean task for a project. Args: project: Project path (e.g., ':app'). Use ':' or empty string or None for root project. ctx: FastMCP context for progress reporting and logging. Returns: Dictionary with 'success', 'error', 'stdout', and 'stderr' keys. - success (bool): True if clean completed successfully - error (str or None): Error message if clean failed, None otherwise - stdout (str): Standard output from Gradle - stderr (str): Standard error from Gradle Raises: subprocess.CalledProcessError: If Gradle command fails. """ # Root project if project is None, empty, or ":" is_root = project is None or project == "" or project == ":" project_arg = "" if is_root else f"{project}:" # Remove -q to get progress output cmd = [str(self.wrapper_script), f"{project_arg}clean", "--no-build-cache"] try: progress_pattern = re.compile(r'(\d+)%') process = subprocess.Popen( cmd, cwd=str(self.project_root), stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, ) stdout_lines = [] stderr_lines = [] # Read output line by line in real-time while True: # Check if process has finished if process.poll() is not None: # Read any remaining output remaining_out = process.stdout.read() remaining_err = process.stderr.read() if remaining_out: stdout_lines.append(remaining_out) if remaining_err: stderr_lines.append(remaining_err) break # Read available output out_line = process.stdout.readline() if out_line: stdout_lines.append(out_line) # Parse progress if ctx and '%' in out_line: match = progress_pattern.search(out_line) if match: progress = int(match.group(1)) await ctx.report_progress(progress=progress, total=100) err_line = process.stderr.readline() if err_line: stderr_lines.append(err_line) # Small async sleep to not block event loop await asyncio.sleep(0.01) stdout = ''.join(stdout_lines) stderr = ''.join(stderr_lines) if process.returncode == 0: return { "success": True, "error": None } else: # Extract comprehensive error message using helper method error_message = self._extract_error_message(stdout, stderr, "Clean failed") return { "success": False, "error": error_message } except Exception as e: return { "success": False, "error": str(e) }
• src/gradle_mcp/server.py:19-23 (schema)

  Pydantic model used as the return type/schema for the clean tool's output.
  class TaskResult(BaseModel): """Result of running a Gradle task.""" success: bool error: Optional[str] = None
• src/gradle_mcp/server.py:190-190 (registration)

  FastMCP decorator that registers the clean function as an MCP tool.
  @mcp.tool()