MCP Build Service

A Model Context Protocol (MCP) server that provides access to git repositories for build and test operations. This allows AI assistants to run builds, execute tests, and inspect git repositories on your behalf.

What does it do?

This service provides AI assistants with tools to:

• List available git repositories
• Execute git commands (status, log, checkout, pull, fetch, diff, show, branch)
• Run make targets (build, test, clean, etc.)
• List directory contents
• Read files from repositories
• Query installed build tools and versions

The service runs in a directory containing git repositories and exposes them through the MCP protocol.

Use case

The typical workflow is:

1. You develop code in your workspace and push to a git branch
2. AI assistant uses this service to checkout your branch in a build environment
3. AI assistant runs builds and tests on that branch
4. AI assistant reports results back to you
5. You make fixes based on feedback and repeat

This separates your development environment from the build/test environment that the AI uses.

Installation

git clone <this-repo-url>
cd mcp-build
pip install -e .

Setup

Create or designate a directory containing your git repositories:

/path/to/build-area/
 project-one/    # git repository
 project-two/    # git repository
 project-three/  # git repository

Usage

Local mode (stdio)

Start the service in the directory containing your repositories:

cd /path/to/build-area
mcp-build

Configure Claude Desktop to use it. Add to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "build": {
      "command": "mcp-build",
      "cwd": "/path/to/build-area"
    }
  }
}

Remote mode (HTTP)

Start with HTTP transport:

cd /path/to/build-area
mcp-build --transport http --host 0.0.0.0 --port 3344

The service generates a session key on startup. Configure Claude Desktop with:

{
  "mcpServers": {
    "build": {
      "url": "http://your-server:3344/sse?key=SESSION_KEY"
    }
  }
}

Command-line options

mcp-build --help                  # Show all options
mcp-build                         # stdio mode (default)
mcp-build --transport http        # HTTP mode, auto-generate session key
mcp-build --transport http --session-key YOUR_KEY
mcp-build --transport http --host 0.0.0.0 --port 8080

Available tools

The service exposes these MCP tools:

• list - List available repositories
• git - Execute git commands (limited to: status, log, checkout, pull, branch, diff, fetch, show)
• make - Run make with specified arguments (executes whatever is in the Makefile)
• ls - List files and directories
• env - Show installed tools and versions
• read_file - Read file contents (with optional line range for large files)

Security considerations

Git operations: The service restricts git commands to a whitelist (status, log, checkout, pull, branch, diff, fetch, show). Dangerous operations like git push --force or git reset --hard are blocked.

Command validation: The service blocks path traversal patterns (../) and some command injection patterns (pipes, redirects, command substitution).

Make targets: The service runs whatever make targets you specify. These execute the commands defined in the repository's Makefile, which could be anything. The service does not sandbox or restrict what Makefiles can do.

Authentication (HTTP mode): Requires a session key passed as a Bearer token or query parameter. Keys can be auto-generated or provided.

Recommendation: Run this service in an environment appropriate for build operations (e.g., a dedicated build VM, container, or CI environment). It validates some inputs but does not provide comprehensive sandboxing.

Example usage with AI assistant

Once configured, you can ask your AI assistant:

• "List the available repositories"
• "Checkout the feature-branch in my-project and run make test"
• "What's the build output from the latest commit on main?"
• "Show me the diff between main and feature-branch"

The AI will use the service automatically through MCP tool calls.

Troubleshooting

No repositories found

• Verify you started mcp-build in the parent directory of your git repos
• Check each directory has a .git subdirectory

Repository not found

• Repository names must match directory names exactly
• Use the list tool to see available names

Build failures

• Use the env tool to check installed build tools
• Verify the Makefile exists and has the target you're trying to run

Connection issues (HTTP mode)

• Check the session key matches what the service printed at startup
• Verify firewall allows the port
• Test with curl: curl -H "Authorization: Bearer KEY" http://host:port/api/repos

HTTP API

In addition to the MCP protocol, the service provides HTTP endpoints:

Quick operations (REST):

• GET /api/repos - List repositories
• GET /api/repos/{repo}/env - Environment info
• POST /api/repos/{repo}/ls - List files
• POST /api/repos/{repo}/read_file - Read file contents
• POST /api/repos/{repo}/git/quick - Quick git operations (status, branch, log)

Long operations (streaming SSE):

• POST /stream/repos/{repo}/make - Stream build output
• POST /stream/repos/{repo}/git - Stream git operations (pull, fetch, diff, show, checkout)

All endpoints require authentication via session key.

Development

Run tests:

pip install -e ".[dev]"
pytest tests/

Project structure:

mcp-build/
 src/
    server.py       # Main server
    validators.py   # Input validation
 tests/              # Tests
 README.md          # This file (user docs)
 MCP-BUILD.md       # Agent usage guide

License

MIT License