Bazel MCP Server

# Alternative if build scripts are unavailable
go build -o bazel-mcp .

# Point an IDE MCP client at the absolute path of the binary, e.g.
#   /home/you/src/bazel-mcp/bazel-mcp
#   C:\src\bazel-mcp\bazel-mcp.exe

{
  "mcpServers": {
    "bazel-mcp": {
      "command": "C:\\src\\bazel-mcp\\bazel-mcp.exe",
      "args": [],
      "env": {}
    }
  }
}

<!-- Snapshot of utils/mcp/README.md as of guide publish. Not auto-updated. No private-repo links. -->
# Bazel MCP Server

> This server is the **private Bazel/workspace stdio MCP**. The public agent trail outpost on Waryway is **Waypost** (`pkg/waypost`, apex `/waypost/` + `/mcp/`) — different product; do not conflate.

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server written in Go that gives AI assistants first-class access to:

- **Bazel Central Registry** — look up module versions, check compatibility with Bazel 9.0.1
- **Local Bazel** — run `bazel build`, `bazel test`, `bazel mod`, `bazel query`, etc. from the workspace root
- **Gazelle** — generate or verify Bazel BUILD files via `bazel run //:gazelle`

> **Bazel version constraint:** This server enforces Bazel **9.0.1** with **bzlmod** (`MODULE.bazel`).  
> All WORKSPACE-era flags (`--noenable_bzlmod`, `--enable_workspace`) are rejected.  
> For dependency management, only `bazel mod` is accepted.

---

## Tools

| Tool | Description |
|---|---|
| `registry_lookup` | Fetch all versions of a module from registry.bazel.build |
| `registry_check_version` | Verify a specific `module@version` exists and is not yanked |
| `bazel_run` | Run any Bazel command locally (`build`, `test`, `mod`, `query`, …) |
| `gazelle_run` | Run Gazelle in `update`, `diff`, or `fix` mode |

### `registry_lookup`
```json
{
  "module": "rules_go"
}
```
Returns a sorted list of all versions, yanked status, the latest stable version, and the correct `bazel_dep(...)` snippet.

### `registry_check_version`
```json
{
  "module": "rules_go",
  "version": "0.50.0"
}
```
Confirms the version is published and not yanked. Returns upgrade advice if yanked.

### `bazel_run`
```json
{
  "args": "build //apps/retronium/...",
  "workspace_root": "/optional/absolute/path"
}
```
- `args` — everything after `bazel` (required)
- `workspace_root` — optional; auto-detected by walking up from the binary to find `.bazelversion`

Examples:
```
build //...
test //server/auth/...
mod deps
mod graph
query 'deps(//apps/retronium)'
```

### `gazelle_run`
```json
{
  "mode": "update",
  "extra_args": "",
  "workspace_root": ""
}
```
- `mode` — `update` (default), `diff`, `fix`
- `extra_args` — optional flags forwarded to Gazelle, e.g. `-go_prefix (local monorepo module path)`
- `workspace_root` — optional

---

## Building

### Windows
```bat
cd utils\mcp
build.bat
```

### macOS / Linux / Git Bash
```bash
cd utils/mcp
chmod +x build.sh
./build.sh
```

Both produce a `bazel-mcp` (or `bazel-mcp.exe`) binary in the same directory.

---

## Setup

The MCP server communicates over **stdio** (stdin/stdout). Every tool connects to it by spawning the binary as a subprocess.

### JetBrains AI Assistant (GoLand / IntelliJ / Rider / …)

1. Open **Settings → Tools → AI Assistant → Model Context Protocol (MCP)**.
2. Click **+** → **As process**.
3. Fill in:

| Field | Value |
|---|---|
| Name | `Bazel MCP` |
| Command | Full path to `bazel-mcp.exe` (Windows) or `bazel-mcp` (macOS/Linux) |
| Working directory | *(leave blank — server auto-detects workspace root)* |

Or use the JSON config file at:

- **Windows:** `%APPDATA%\JetBrains\<product>\mcp.json`
- **macOS:** `~/Library/Application Support/JetBrains/<product>/mcp.json`
- **Linux:** `~/.config/JetBrains/<product>/mcp.json`

```json
{
  "servers": {
    "bazel-mcp": {
      "command": "C:\\Users\\kawie\\waryway\\stack\\utils\\mcp\\bazel-mcp.exe",
      "args": [],
      "env": {}
    }
  }
}
```

> Replace the path with your actual binary path. On macOS/Linux omit `.exe`.

---

### Cursor

Create or edit **`.cursor/mcp.json`** in the repo root:

```json
{
  "mcpServers": {
    "bazel-mcp": {
      "command": "C:\\Users\\kawie\\waryway\\stack\\utils\\mcp\\bazel-mcp.exe",
      "args": [],
      "env": {}
    }
  }
}
```

macOS/Linux:
```json
{
  "mcpServers": {
    "bazel-mcp": {
      "command": "/absolute/path/to/utils/mcp/bazel-mcp",
      "args": [],
      "env": {}
    }
  }
}
```

Restart Cursor. The four Bazel tools appear in the MCP tools panel.

---

### Claude Desktop

Edit `claude_desktop_config.json`:

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

```json
{
  "mcpServers": {
    "bazel-mcp": {
      "command": "C:\\Users\\kawie\\waryway\\stack\\utils\\mcp\\bazel-mcp.exe",
      "args": []
    }
  }
}
```

Restart Claude Desktop.

---

### VS Code (GitHub Copilot / Continue / MCP extension)

Create **`.vscode/mcp.json`** in the repo root:

```json
{
  "servers": {
    "bazel-mcp": {
      "type": "stdio",
      "command": "C:\\Users\\kawie\\waryway\\stack\\utils\\mcp\\bazel-mcp.exe",
      "args": []
    }
  }
}
```

macOS/Linux:
```json
{
  "servers": {
    "bazel-mcp": {
      "type": "stdio",
      "command": "${workspaceFolder}/utils/mcp/bazel-mcp",
      "args": []
    }
  }
}
```

> VS Code supports `${workspaceFolder}` in the command path.

---

## Example Prompts

Once connected, you can ask your AI assistant:

- *"Look up the latest version of `rules_go` in the Bazel registry"*
- *"Check if `gazelle@0.40.0` is valid for Bazel 9"*
- *"Run `bazel build //apps/retronium/...` and show me the output"*
- *"Run Gazelle in diff mode to see if any BUILD files need updating"*
- *"Update all BUILD files with Gazelle"*
- *"Show the `bazel mod graph` for this workspace"*

---

## Module structure

```
utils/mcp/
├── main.go       — MCP server entry point, tool registration
├── registry.go   — registry_lookup, registry_check_version tools
├── bazel.go      — bazel_run tool + workspace root detection
├── gazelle.go    — gazelle_run tool
├── go.mod        — standalone Go module ((local module path; not a public URL))
├── go.sum        — dependency checksums
├── build.sh      — build script (macOS/Linux/Git Bash)
├── build.bat     — build script (Windows cmd)
└── README.md     — this file
```