Gradle MCP Server

Instructions

Implementation Reference

• src/gradle_mcp/server.py:232-254 (handler)

  The primary handler function for the 'list_projects' MCP tool. It is registered via the @mcp.tool() decorator, fetches projects using GradleWrapper, and returns a list of ProjectInfo objects.

  @mcp.tool()
  async def list_projects(ctx: Context) -> list[ProjectInfo]:
      """List all Gradle projects in the workspace.
  
      Returns:
          List of Gradle projects.
      """
      try:
          await ctx.info("Listing all Gradle projects")
          gradle = _get_gradle_wrapper(ctx)
          projects = gradle.list_projects()
          await ctx.info(f"Found {len(projects)} projects: {', '.join(p.name for p in projects)}")
          return [
              ProjectInfo(
                  name=p.name,
                  path=p.path,
                  description=p.description,
              )
              for p in projects
          ]
      except Exception as e:
          raise ValueError(f"Failed to list projects: {str(e)}") from e

• src/gradle_mcp/server.py:144-150 (schema)

  Pydantic BaseModel defining the output schema for the list_projects tool, specifying fields for project name, path, and optional description.

  class ProjectInfo(BaseModel):
      """Information about a Gradle project."""
  
      name: str
      path: str
      description: str | None = None

• src/gradle_mcp/gradle.py:726-780 (helper)

  Core helper method in GradleWrapper class that executes 'gradlew projects -q', parses the output, and constructs GradleProject objects used by the tool handler.

  def list_projects(self) -> list[GradleProject]:
      """List all Gradle projects in the workspace.
  
      Returns:
          List of GradleProject objects.
  
      Raises:
          subprocess.CalledProcessError: If Gradle command fails.
      """
      try:
          result = subprocess.run(
              [str(self.wrapper_script), "projects", "-q"],
              cwd=str(self.project_root),
              capture_output=True,
              text=True,
              check=True,
              env=self._build_execution_environment(),
          )
  
          projects = []
          root_added = False
  
          for line in result.stdout.split("\n"):
              line = line.strip()
  
              # Add root project (only once)
              if "Root project" in line and not root_added:
                  projects.append(
                      GradleProject(
                          name=":", path=str(self.project_root), description="Root project"
                      )
                  )
                  root_added = True
                  continue
  
              # Look for subproject lines like "+--- Project ':app'" or "Project ':app'"
              # But skip if it's the root project line we already handled
              if "Project '" in line and "Root project" not in line:
                  # Extract project name from various formats
                  match = re.search(r"Project '([^']+)'", line)
                  if match:
                      project_name = match.group(1)
                      # Skip root project if it appears again
                      if project_name != ":":
                          projects.append(
                              GradleProject(
                                  name=project_name,
                                  path=str(self.project_root),
                              )
                          )
  
          return projects
      except subprocess.CalledProcessError as e:
          raise RuntimeError(f"Failed to list projects: {e.stderr}") from e

• src/gradle_mcp/gradle.py:40-47 (helper)

  Dataclass defining the internal structure for Gradle projects, mirrored by the ProjectInfo schema in server.py.

  @dataclass
  class GradleProject:
      """Represents a Gradle project."""
  
      name: str
      path: str
      description: str | None = None