Installation Guide & CLI Commands

Introduction

CostAffective-MCP runs as a local native Go binary. It maps your codebase's AST symbols, function call-graphs, and references into a local SQLite database. It interfaces with your IDE or CLI coding agent using standard Input/Output (stdio) streams.

1. Linux Installation (Variants)

Variant A: Automated Installer Script (amd64 & arm64)

The recommended way to install on modern Linux distributions. It automatically checks for Go and C compiler dependencies, builds from source, and registers with your AI clients:

curl -fsSL https://raw.githubusercontent.com/okyashgajjar/costaffective-mcp/main/install.sh | bash

Variant B: Debian / Ubuntu Manual Build

Install system build dependencies and compile the binary manually:

# Install Go compiler and gcc (required for CGO Tree-sitter bindings)
sudo apt update && sudo apt install -y golang-go gcc git

# Build and verify
git clone https://github.com/okyashgajjar/costaffective-mcp.git
cd costaffective-mcp
CGO_ENABLED=1 go build -o ~/.local/bin/costaffective ./cmd/costaffective
chmod +x ~/.local/bin/costaffective
costaffective --version

Variant C: Alpine Linux Build

Alpine requires specific compilation environment setups to accommodate musl libc and native build tooling:

# Install build dependencies
apk add --no-cache go build-base git

# Clone and compile
git clone https://github.com/okyashgajjar/costaffective-mcp.git
cd costaffective-mcp
CGO_ENABLED=1 go build -o ~/.local/bin/costaffective ./cmd/costaffective

Variant D: RHEL / Fedora / CentOS Build

For Red Hat family distributions, configure using dnf:

sudo dnf install -y golang gcc git
git clone https://github.com/okyashgajjar/costaffective-mcp.git
cd costaffective-mcp
CGO_ENABLED=1 go build -o ~/.local/bin/costaffective ./cmd/costaffective

2. macOS Installation (Variants)

Variant A: Automated Shell Script (Intel & Apple Silicon)

Run the automated script inside your macOS Terminal to set up paths and config targets:

curl -fsSL https://raw.githubusercontent.com/okyashgajjar/costaffective-mcp/main/install.sh | bash

Variant B: Apple Silicon (M1 / M2 / M3 / M4 arm64) Manual Build

Ensure you have Xcode Command Line Tools installed (xcode-select --install). Build natively targeting ARM64 architecture:

# Build targeting local ARM64 arch
git clone https://github.com/okyashgajjar/costaffective-mcp.git
cd costaffective-mcp
CGO_ENABLED=1 GOOS=darwin GOARCH=arm64 go build -o ~/.local/bin/costaffective ./cmd/costaffective
chmod +x ~/.local/bin/costaffective

Variant C: macOS Intel (amd64) Manual Build

Compile natively targeting Intel x86_64 architecture:

git clone https://github.com/okyashgajjar/costaffective-mcp.git
cd costaffective-mcp
CGO_ENABLED=1 GOOS=darwin GOARCH=amd64 go build -o ~/.local/bin/costaffective ./cmd/costaffective
chmod +x ~/.local/bin/costaffective

3. Windows Installation (Variants)

Variant A: Windows Subsystem for Linux (WSL) - Recommended

For the best performance and CGO compiling environment, install Ubuntu under WSL and run the quick installer script:

# In PowerShell (run as Administrator to set up WSL):
wsl --install

# Once inside WSL (Ubuntu), run the shell installer:
curl -fsSL https://raw.githubusercontent.com/okyashgajjar/costaffective-mcp/main/install.sh | bash

Variant B: Native PowerShell Build (Requires Go + gcc)

To run natively on Windows without WSL, you must have Go 1.25+ and a gcc compiler (such as MinGW-w64) installed and configured in your environment PATH:

# In PowerShell:
git clone https://github.com/okyashgajjar/costaffective-mcp.git
cd costaffective-mcp
$env:CGO_ENABLED=1
go build -o costaffective.exe ./cmd/costaffective/
Move-Item costaffective.exe C:\Users\$env:USERNAME\.local\bin\

4. CLI Utility Commands

Once the binary is built, use these utility flags to manage and repair client configurations:

# Run interactive auto-installer (detects and configures clients)
costaffective install

# Configure all detected clients automatically without prompts
costaffective install --all

# Configure a specific editor target
costaffective install --target cursor
costaffective install --target claude-code

# Rebuild the binary from source before configuring clients
costaffective install --build

# Run idempotent repair mode (fixes broken paths/configs)
costaffective install --repair

5. Diagnostics with Doctor Command

Verify that the installation is intact and all IDE configurations are running with correct absolute binary paths:

costaffective doctor

Diagnostics Output Structure:

CostAffective Doctor

PASS Binary Found
       ~/.local/bin/costaffective
PASS Binary Permissions
PASS Binary Version
       costaffective version 1.0.0
PASS Binary in PATH
       /home/user/.local/bin/costaffective
PASS Cursor Config
       ~/.cursor/mcp.json
PASS OpenCode Config
       ~/.config/opencode/opencode.jsonc
PASS Antigravity / Gemini Config
       ~/.gemini/antigravity/mcp_config.json
PASS MCP Startup
       Server responds to JSON-RPC initialize
PASS Repository
       /home/user/project
PASS Index Directory
       /home/user/project/.mycli-fts

Results: 10 PASS, 0 WARN, 0 FAIL
Status: READY