Build-Scout MCP Server

A comprehensive Model Context Protocol (MCP) server that enables LLM clients to interact with various build systems including Gradle, Maven, NPM/Yarn, Cargo, Python, Makefile, and CMake.

Overview

Build-scout provides a standardized interface for build tool operations through the Model Context Protocol, allowing AI assistants to understand, analyze, and manipulate software projects across multiple build technologies.

Supported Build Systems

Gradle (Groovy and Kotlin DSL) - build.gradle, build.gradle.kts
Maven - pom.xml
NPM/Yarn - package.json
Cargo (Rust) - Cargo.toml
Python - requirements.txt, setup.py
Makefile - Makefile
CMake - CMakeLists.txt

Available Tools

Build System Discovery

find_build_system - Discovers build systems in project directories
build_system_file_paths - Returns paths to build system files

Gradle Operations

build_gradle_project - Executes Gradle builds with optional checks
gradle_tester - Runs Gradle build and test tasks

Dependency Management

dependencies_list - Lists all top-level dependencies with versions
update_dependency_version - Updates dependency versions in build files
latest_dependency_version - Fetches latest versions from repositories

Code Analysis

find_class_usage - Finds class usage across the codebase
jar_diff_reporter - Compares JAR files for differences

File Operations

get_file_info - Retrieves file metadata and information
get_resource_info - Gets resource information
replace_source_code_complete - Performs source code replacements

Source Management

download_current_latest_source - Downloads latest source versions

Building the Server

JAR Build (Recommended)

This will increment the version number and build the JAR:

./gradlew clean prebuild updateConfigJson

Native Image Build (Experimental)

Completed and tested all the tools, prompt and root to see the native image working. Still need to review more for edge cases but try it out.

./gradlew clean prebuild nativeCompile

To run the server locally and get out put for native image class discovery.

"scout-server": { "command": "java", "args": [ "-agentlib:native-image-agent=config-output-dir=/Users/davidparry/code/github/mcp-servers/build-scout/tmp/META-INF/native-image", "-Dorg.gradle.native=false", "-Djava.awt.headless=true", "-jar /Users/davidparry/code/github/mcp-servers/build-scout/build/libs/scout-1.0.105.jar" ], "env": { "BUILD_SCOUT_LOGGING": "DEBUG" } }

After running the server, you can generate the native image configuration files will append to the files already in the `src/main/resources/META-INF/native-image` directory.:

$GRAALVM_HOME/bin/native-image-configure generate --input-dir=tmp/META-INF/native-image --output-dir=src/main/resources/META-INF/native-image

Installation & Configuration

Claude Desktop

Add to your claude_desktop_config.json:

If you built the JAR:

{ "mcpServers": { "scout-server": { "command": "java", "args": ["-jar", "/path/to/scout-1.0.{VERSION}.jar"] } } }

If you built the Native Image:

{ "mcpServers": { "scout-server": { "command": "scout", "args": [], "env": { "BUILD_SCOUT_LOGGING": "ERROR" } } } }

GitHub Copilot

Add to your ~/.config/github-copilot/intellij/mcp.json:

{ "servers": { "scout-server": { "command": "java", "args": ["-jar", "/path/to/scout-1.0.{VERSION}.jar"] } } }

Custom MCP Client

The server can be integrated with any MCP-compatible client by configuring the appropriate JSON configuration file.

Usage Examples

Discovering Build Systems

{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "find_build_system", "arguments": { "project_root": "/path/to/your/project" } } }

Building a Gradle Project

{ "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "build_gradle_project", "arguments": { "project_root": "/path/to/gradle/project", "check": true } } }

Listing Dependencies

{ "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "dependencies_list", "arguments": { "path": "/path/to/build.gradle" } } }

Updating Dependency Version

{ "jsonrpc": "2.0", "id": 4, "method": "tools/call", "params": { "name": "update_dependency_version", "arguments": { "groupId": "org.springframework.boot", "artifactId": "spring-boot-starter-web", "version": "3.2.0", "path": "/path/to/build.gradle" } } }

Architecture

Core Components

Main.java - Entry point and server initialization
RequestController - Routes JSON-RPC requests to appropriate handlers
SchemaInitializer - Registers tools and handlers using annotations
IOHandler - Manages input/output communication
BuildSystem - Core interface for build system operations

Key Features

Annotation-based tool registration using @Schema annotations
Virtual thread processing for concurrent request handling
Gradle Tooling API integration for direct Gradle operations
Native image support with GraalVM configuration
Automatic version management and JAR updates

Development

Requirements

Java 21+
Gradle 8.14+

Project Structure

src/
├── main/
│   ├── java/
│   │   └── com/davidparry/scout/
│   │       ├── Main.java
│   │       ├── Router.java
│   │       ├── tools/           # MCP tools implementation
│   │       ├── common/          # Build system implementations
│   │       ├── spec/            # MCP protocol specifications
│   └── resources/
│       └── META-INF/native-image/  # GraalVM configuration
└── test/
    └── java/                    # Unit tests

Testing

Run the test suite:

./gradlew test

Version Management

The build system automatically:

Increments patch version numbers
Updates JAR references in MCP client configurations
Generates version metadata for runtime access

Troubleshooting

Common Issues

Build failures - Check Java version compatibility (requires Java 21+)
Native image issues - Ensure GraalVM is properly configured
Tool registration - Static classes not registered correctly; for the native image.

Logging

The server includes comprehensive logging at different levels. Check the console output for detailed information about tool execution and errors.

Contributing

Fork the repository
Create a feature branch
Add tests for new functionality
Ensure all tests pass
Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Build-Scout