MCP Build Service

A Model Context Protocol (MCP) server that provides secure access to software project repositories for build operations. This service allows AI assistants to execute builds, run tests, and manage git operations across multiple repositories in a controlled manner.

Features

• Automatic Repository Discovery: Discovers git repositories in the configured directory
• Safe Command Execution: Validated commands to prevent accidental harmful operations
• Git Operations: Limited to safe operations (status, log, checkout, pull, branch, diff, fetch, show)
• Build Management: Execute make targets, run tests, and manage build artifacts
• Environment Inspection: Query installed tools, versions, and environment variables
• Multi-Repository Support: Work with multiple repositories from a single service

Available Commands

list

List all available repositories discovered in the service directory.

Example:

{
  "tool": "list"
}

make

Run make command with specified arguments in a repository.

Parameters:

• args (optional): Arguments to pass to make (e.g., "clean", "all", "test")
• repo (required): Repository name

Examples:

{
  "tool": "make",
  "args": "clean all",
  "repo": "my-project"
}

{
  "tool": "make",
  "args": "test",
  "repo": "my-project"
}

git

Run git commands (limited to safe operations).

Allowed operations: status, log, checkout, pull, branch, diff, fetch, show

Parameters:

• args (required): Git command and arguments
• repo (required): Repository name

Examples:

{
  "tool": "git",
  "args": "status",
  "repo": "my-project"
}

{
  "tool": "git",
  "args": "checkout feature-branch",
  "repo": "my-project"
}

{
  "tool": "git",
  "args": "log --oneline -10",
  "repo": "my-project"
}

ls

List files and directories in a repository.

Parameters:

• args (optional): Arguments to pass to ls (e.g., "-la", "-lh build/")
• repo (required): Repository name

Examples:

{
  "tool": "ls",
  "args": "-la",
  "repo": "my-project"
}

{
  "tool": "ls",
  "args": "-lh build/",
  "repo": "my-project"
}

env

Show environment information including installed tools and versions.

Parameters:

• repo (required): Repository name

Example:

{
  "tool": "env",
  "repo": "my-project"
}

Installation

Prerequisites

• Python 3.10 or higher
• pip
• Build tools (make, gcc, etc.) installed on your system
• Git repositories you want to work with

Setup Steps

1. Clone the repository:

   git clone <this-repo-url>
   cd mcp-build
   

2. Install the service:

   pip install -e .
   # Or for development:
   pip install -e ".[dev]"
   

3. Organize your repositories: Place your git repositories in a directory where the service can discover them. For example:

   /home/user/projects/
   ├── project-a/     (git repo)
   ├── project-b/     (git repo)
   └── project-c/     (git repo)
   

Configuration

MCP Client Configuration

Add the server to your MCP client configuration (e.g., Claude Desktop):

{
  "mcpServers": {
    "mcp-build": {
      "command": "python",
      "args": ["-m", "server"]
    }
  }
}

Note: The service runs in the current working directory and automatically discovers all git repositories (directories containing .git) in that directory.

Command-Line Options:

# View all available options
mcp-build --help

# Start with default stdio transport
mcp-build

# Start with HTTP transport (auto-generates session key)
mcp-build --transport http

# Start with HTTP transport and custom session key
mcp-build --transport http --session-key YOUR_SECRET_KEY

# Start with HTTP transport on custom host and port
mcp-build --transport http --host 127.0.0.1 --port 8080

Available Arguments:

• --transport {stdio,http}: Transport mode (default: stdio)
• --host HOST: Host address for HTTP transport (default: 0.0.0.0)
• --port PORT: Port for HTTP transport (default: 3344)
• --session-key KEY: Session key for HTTP authentication
• --generate-key: Auto-generate a random session key for HTTP transport

HTTP Transport

The service supports HTTP transport using Server-Sent Events (SSE) for remote access. This is useful for:

• Remote access to build environments
• Running the service in containers or remote servers
• Integration with web-based MCP clients

Authentication:

HTTP transport requires a session key for authentication. You can either:

1. Provide your own key using --session-key YOUR_KEY
2. Let the server auto-generate a secure random key (displayed on startup)

Starting with HTTP transport:

# Start with auto-generated session key
cd /path/to/repos
mcp-build --transport http

# Or provide your own session key
cd /path/to/repos
mcp-build --transport http --session-key $(python3 -c "import secrets; print(secrets.token_urlsafe(32))")

The service will start an HTTP server with an SSE endpoint at:

http://0.0.0.0:3344/sse

MCP Client Configuration for HTTP:

Include the session key in the URL as a query parameter:

{
  "mcpServers": {
    "mcp-build-http": {
      "url": "http://localhost:3344/sse?key=YOUR_SESSION_KEY_HERE"
    }
  }
}

Or use the Authorization header (if your MCP client supports it):

{
  "mcpServers": {
    "mcp-build-http": {
      "url": "http://localhost:3344/sse",
      "headers": {
        "Authorization": "Bearer YOUR_SESSION_KEY_HERE"
      }
    }
  }
}

Testing the Connection:

# Test with curl (replace YOUR_KEY with your session key)
curl -H "Authorization: Bearer YOUR_KEY" http://localhost:3344/sse

# Or using query parameter
curl "http://localhost:3344/sse?key=YOUR_KEY"

Security Notes:

• Session keys provide authentication to prevent unauthorized access
• Use TLS/SSL in production by deploying behind a reverse proxy (nginx, caddy)
• Use firewall rules to restrict access to trusted networks
• Consider VPN or SSH tunneling for remote access
• Keep your session key secret and rotate it regularly

Hybrid API Architecture

In addition to the MCP protocol over SSE, the service provides a Hybrid REST/Streaming API for more flexible access patterns:

API Design

• REST API for quick, synchronous operations (< 1 second)
• Streaming SSE API for long-running operations with real-time output
• MCP Protocol for backwards compatibility with MCP clients

Quick Operations (REST API)

These endpoints return immediately with complete results:

GET /api/repos

List all discovered repositories.

Example:

curl -H "Authorization: Bearer YOUR_KEY" \
  http://localhost:3344/api/repos

Response:

{
  "repos": [
    {
      "name": "test-repo",
      "path": "/path/to/test-repo",
      "description": "Repository at test-repo",
      "is_default": false
    }
  ]
}

Note: The is_default field is deprecated and always false since repository parameter is now required for all operations.

GET /api/repos/{repo}/env

Get environment information for a repository.

Example:

curl -H "Authorization: Bearer YOUR_KEY" \
  http://localhost:3344/api/repos/test-repo/env

Response:

{
  "success": true,
  "data": "=== STDOUT ===\ngcc version 11.4.0\n..."
}

POST /api/repos/{repo}/ls

List directory contents (fast file listing).

Request Body:

{
  "args": "-la"
}

Example:

curl -X POST \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"args": "-la"}' \
  http://localhost:3344/api/repos/test-repo/ls

Response:

{
  "success": true,
  "data": "=== STDOUT ===\ntotal 24\ndrwxr-xr-x 3 user user 4096...\n"
}

POST /api/repos/{repo}/git/quick

Quick git operations (status, branch, log only).

Request Body:

{
  "operation": "status",
  "args": ""
}

Example:

curl -X POST \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"operation": "status", "args": ""}' \
  http://localhost:3344/api/repos/test-repo/git/quick

Response:

{
  "success": true,
  "data": "=== STDOUT ===\nOn branch main\nnothing to commit, working tree clean\n"
}

Long Operations (Streaming SSE API)

These endpoints stream output line-by-line as the command executes:

POST /stream/repos/{repo}/make

Stream make command output in real-time.

Request Body:

{
  "args": "clean all"
}

Example:

curl -X POST \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"args": "test"}' \
  -N \
  http://localhost:3344/stream/repos/test-repo/make

Streaming Response:

data: {"type": "stdout", "line": "Starting tests..."}

data: {"type": "stdout", "line": "Running test 1..."}

data: {"type": "stdout", "line": "Running test 2..."}

data: {"type": "stdout", "line": "All tests passed!"}

data: {"type": "complete", "exit_code": 0}

POST /stream/repos/{repo}/git

Stream git operations with potentially large output (pull, fetch, diff, show, checkout).

Request Body:

{
  "operation": "pull",
  "args": "origin main"
}

Example:

curl -X POST \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"operation": "diff", "args": "HEAD~1"}' \
  -N \
  http://localhost:3344/stream/repos/test-repo/git

Streaming Response:

data: {"type": "stdout", "line": "diff --git a/file.txt b/file.txt"}

data: {"type": "stdout", "line": "+Added line"}

data: {"type": "complete", "exit_code": 0}

Event Types in Streaming Responses

Type	Description	Fields
stdout	Standard output line	type, line
stderr	Standard error line	type, line
complete	Command completed	type, exit_code
error	Error occurred	type, message

When to Use Each API

Use REST API for:

• Repository discovery (/api/repos)
• Quick status checks (/api/repos/{repo}/git/quick)
• Environment queries (/api/repos/{repo}/env)
• Fast file listings (/api/repos/{repo}/ls)

Use Streaming API for:

• Long builds (/stream/repos/{repo}/make)
• Large git diffs (/stream/repos/{repo}/git)
• Operations where progress visibility is important

Use MCP Protocol for:

• Integration with MCP-compatible clients (Claude Desktop, etc.)
• Unified tool interface across different MCP services

Example Configuration for Different Setups

Single Project:

{
  "mcpServers": {
    "mcp-build": {
      "command": "python",
      "args": ["-m", "server"],
      "cwd": "/home/user/my-project/.."
    }
  }
}

Multiple Projects Directory:

{
  "mcpServers": {
    "mcp-build": {
      "command": "python",
      "args": ["-m", "server"],
      "cwd": "/home/user/workspace"
    }
  }
}

Security

This service implements security measures to protect your build environment:

Authentication (HTTP Transport)

• Session Key Authentication: HTTP transport requires a session key (Bearer token or query parameter)
• Auto-generated Keys: Secure random keys are generated if not provided
• Constant-time Comparison: Uses secrets.compare_digest() to prevent timing attacks

Command Validation

• Path Traversal Protection: Blocks ../ patterns and absolute paths
• Command Injection Protection: Blocks pipes, redirects, and command substitution
• Git Command Whitelist: Only allows safe git operations (status, log, checkout, pull, branch, diff, fetch, show)
• Argument Validation: Validates all command arguments before execution

Best Practices

• Keep your session key secret and rotate it regularly
• Use TLS/SSL in production (deploy behind a reverse proxy)
• Restrict network access with firewall rules
• Use stdio transport for local, trusted environments
• Use HTTP transport only when remote access is required

Important: These security measures provide protection for typical use cases, but do not expose this service to completely untrusted users or networks without additional security controls.

Development

Project Structure

mcp-build/
├── src/
│   ├── __init__.py
│   ├── server.py              # Main MCP server
│   ├── validators.py          # Argument validation
│   ├── env_info.sh            # Environment info script
│   └── helpers/               # Helper modules
├── tests/
│   ├── __init__.py
│   └── test_validators.py    # Validator tests
├── requirements.txt
├── pyproject.toml
└── README.md

Running Tests

pytest tests/

Code Formatting

black src/

Type Checking

mypy src/

Usage Examples

Building a Project

# List available repos
await mcp.call_tool("list", {})

# Check current git status
await mcp.call_tool("git", {"args": "status", "repo": "my-project"})

# Pull latest changes
await mcp.call_tool("git", {"args": "pull origin main", "repo": "my-project"})

# Clean and build
await mcp.call_tool("make", {"args": "clean all", "repo": "my-project"})

# Run tests
await mcp.call_tool("make", {"args": "test", "repo": "my-project"})

# Check build artifacts
await mcp.call_tool("ls", {"args": "-lh build/", "repo": "my-project"})

Working with Multiple Repositories

# List all discovered repositories
await mcp.call_tool("list", {})

# Check status of specific repo
await mcp.call_tool("git", {"args": "status", "repo": "project-a"})

# Build a specific repo
await mcp.call_tool("make", {"args": "all", "repo": "project-b"})

# Get environment info from specific repo
await mcp.call_tool("env", {"repo": "project-c"})

Troubleshooting

No repositories found

Check that:

1. The service is running in the correct directory (current working directory)
2. Each repository has a .git directory
3. The service has read permissions for the directory

# Verify repositories are git repos
ls -la /path/to/repos/*/.git

# Check current working directory
pwd

Repository not found error

The specified repository name must match the directory name exactly. Use the list command to see available repositories:

{
  "tool": "list"
}

Permission issues

Ensure the service has appropriate permissions to execute commands in your repository directories:

chmod -R u+rwx /path/to/repos/my-project

Build tools not found

The env command shows installed build tools. If tools are missing, install them on your system:

# Ubuntu/Debian
sudo apt-get install build-essential cmake

# macOS
xcode-select --install
brew install cmake

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

License

MIT License - see LICENSE file for details

Support

For issues and questions:

• Open an issue on GitHub
• Check existing documentation
• Review the MCP protocol specification

Roadmap

• [x] Automatic repository discovery
• [x] Multi-repository support
• [ ] Build caching and artifact management
• [ ] Integration with CI/CD systems
• [ ] Enhanced security controls
• [ ] Build history and logs
• [ ] Performance metrics and monitoring
• [ ] Support for additional build systems (npm, gradle, cargo, etc.)