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

1. Build failures - Check Java version compatibility (requires Java 21+)
2. Native image issues - Ensure GraalVM is properly configured
3. 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

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request

License

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