name: running_gradle_builds description: > Executes and orchestrates Gradle builds with background management, surgical task output capturing, and structured failure diagnostics; ALWAYS use instead of ./gradlew for core lifecycle tasks (build, assemble), dev servers, and troubleshooting. Do NOT use for running tests (use running_gradle_tests) or dependency graph auditing. license: Apache-2.0 metadata: author: https://github.com/rnett/gradle-mcp version: "3.4"

Authoritative Gradle Build Execution & Orchestration

Executes Gradle builds with managed background orchestration and surgical failure diagnostics.

Constitution

• ALWAYS use the gradle tool instead of ./gradlew via shell.
• ALWAYS provide absolute paths for projectRoot.
• NEVER use --rerun-tasks unless investigating project-wide cache-specific corruption; prioritize Gradle's native caching. Prefer --rerun for individual tasks to ensure they are executed even if up-to-date.
• ALWAYS prefer foreground execution (default) unless the task is persistent (e.g., servers) or extremely long-running (>2 minutes).
• ALWAYS use captureTaskOutput when you need the isolated output of a specific task (e.g., help, dependencies).
• ALWAYS check the build dashboard (query_build()) to manage active processes and historical results.
• STRONGLY PREFERRED: Use query_build for all diagnostics. It is more token-efficient than reading raw console logs and provides structured access to failures.
• NEVER leave background builds running; use stopBuildId to release resources when finished.

Surgical Inspection with query_build

The query_build tool is your primary window into build results. Use it to move from high-level summaries to deep-dive diagnostics.

1. Build Dashboard (No Arguments)

Call query_build() without arguments to see the Build Dashboard. This shows active background builds and recently completed builds with their BuildId, status, and failure counts.

• Example: query_build()

2. Build Summary

Provide a buildId to get a summary of that specific build, including failures, problems, and test results. This summary also contains a guide on how to inspect specific details.

• Example: query_build(buildId="ID")

3. Detailed Inspection

To get exhaustive information, ALWAYS use the appropriate kind combined with a specific query:

• Individual Tests: kind="TESTS", query="FullTestName" (REQUIRED for full output/stack trace).
  • Prefix Support: Both query (for tasks/tests) and taskPath support unique prefix matching. Providing a unique prefix (e.g., query="com.example.MyTest" or taskPath=":app:compile") will automatically select the item if it's unambiguous.
• Task Outputs: kind="TASKS", query=":path:to:task".
• Build Failures: kind="FAILURES", query="ID" (find IDs in the build summary).
• Problems/Errors: kind="PROBLEMS", query="ID" (find IDs in the build summary). |- Console Logs: kind="CONSOLE". Use query as a regex filter if needed. |- Full Export: Use outputFile="path/to/file.txt" to write the entire result (e.g., full console output, all tests) to a file, bypassing pagination limits and reducing token usage.

4. Progress Monitoring

Use wait_build with timeout, waitFor, or waitForTask to block until a condition is met in a background build.

• Example: wait_build(buildId="ID", timeout=60, waitFor="Started Application")
• Wait for completion: If timeout is set without a wait condition (waitFor/waitForTask), the tool waits for the build to finish.

5. Monitoring Test Progress

While a build is running, the progress notification (and the query_build summary) provides real-time counts of passed, failed, and skipped tests. This gives immediate feedback on the health of the test suite.

• Example: Call query_build(buildId="ID") repeatedly to see updated test counts: (5 passed, 1 failed).

Directives

• ALWAYS use foreground for authoritative builds: If you intend to wait for a result, ALWAYS use foreground execution. It provides superior progressive disclosure and simpler control flow than starting a background build only to immediately call wait_build(timeout=...).
• Background ONLY for persistent tasks: Use background: true ONLY for tasks that must remain active (e.g., bootRun, continuous builds) or when you explicitly intend to perform independent research while the build proceeds.
• Monitor with query_build and wait_build: Use query_build to check the status of background builds or to perform deep-dives into any historical build started by the server. Use wait_build for blocking waits.
• Provide absolute projectRoot: Provide projectRoot as an absolute file system path to all Gradle MCP tools. Relative paths are not supported.
• Manage resources via dashboard: Frequently call query_build() without arguments to view the build dashboard and ensure no orphaned background builds are consuming system resources.

Authoritative Task Path Syntax

Gradle utilizes two primary ways to identify tasks from the command line. Precision here prevents running redundant tasks in multi-project builds.

1. Task Selectors (Recursive Execution)

Providing a task name without a leading colon (e.g., test, build) acts as a selector. Gradle will execute that task in every project (root and all subprojects) that contains a task with that name.

• Example: gradle(commandLine=["test"]) -> Executes test in all projects.

2. Absolute Task Paths (Targeted Execution)

Providing a task path with a leading colon (e.g., :test, :app:test) targets a single specific project.

• Root Project Only: Use a single leading colon.
  • Example: gradle(commandLine=[":test"]) -> Executes test in the root project ONLY.
• Subproject Only: Use the subproject name(s) separated by colons.
  • Example: gradle(commandLine=[":app:test"]) -> Executes test in the 'app' subproject ONLY.

When to Use

• Core Lifecycle Execution: When you need to execute standard Gradle tasks like build, assemble, or clean with maximum reliability and clean, parseable output.
• Persistent Development Processes: When starting development servers (e.g., bootRun) or continuous builds where background management and real-time log monitoring are required.
• Surgical Build Troubleshooting: When a build has failed and you need to perform deep-dive analysis of task failures or console logs using the query_build diagnostic suite. For test failures, ALWAYS use kind="TESTS" with query="FullTestName".
• Task-Specific Information Retrieval: When you need to extract isolated output from a single task (like help or properties) without the noise of the full build log.

Workflows

Running a Foreground Build

1. Identify the task(s) to run (e.g., ["clean", "build"]).
2. Call gradle with the commandLine.
3. If the build fails, the tool will return a high-signal failure summary. Use query_build with the buildId for deeper diagnostics.

Orchestrating Background Jobs

1. Start the build with background: true to receive a BuildId.
2. Use wait_build(buildId=ID, timeout=..., waitFor=...) to block until a specific state or log pattern is reached.
3. Call query_build() (no arguments) to manage active jobs in the dashboard.
4. Stop the job using gradle(stopBuildId=ID) once its utility is complete.

Examples

Run build in all projects

{
  "commandLine": ["build"]
}
// Reasoning: Using a task selector to verify build health across the entire multi-project structure.

Run test only in a specific subproject

{
  "commandLine": [":app:test"]
}
// Reasoning: Using an absolute path to target a specific module, minimizing execution time and context usage.

Inspect Help Output for a Specific Task

{
  "commandLine": [":app:help", "--task", "test"],
  "captureTaskOutput": ":app:help"
}
// Reasoning: Using captureTaskOutput to retrieve clean, isolated documentation for the 'test' task without Gradle's general console noise.

Start a Dev Server and Wait for Readiness

// 1. Start the server in the background
{
  "commandLine": [":app:bootRun"],
  "background": true
}
// Response: { "buildId": "build_123" }

// 2. Wait for the 'Started Application' log pattern
{
  "buildId": "build_123",
  "timeout": 60,
  "waitFor": "Started Application"
}
// Reasoning: Using background orchestration to allow the server to remain active while waiting for a specific readiness signal.

Troubleshooting

• Build Not Found: If a BuildId is not recognized, it may have expired from the recent history cache. Check the dashboard (query_build()) for valid active and historical IDs.
• Task Output Not Captured: Ensure the path provided to captureTaskOutput matches exactly one of the tasks in the commandLine.
• Missing environment variables: Set invocationArguments: { envSource: "SHELL" } if Gradle cannot find expected env vars (e.g., JAVA_HOME).

Resources

• Background Monitoring
• Failure Analysis