<!-- Fork of https://github.com/fr0ster/mcp-abap-adt — original project by fr0ster -->

# macOS Installation Guide

Complete guide for installing MCP ABAP ADT Server on macOS using Homebrew.

## 📋 Prerequisites

- macOS 10.15 (Catalina) or later
- Terminal access
- Administrator privileges

## 🍺 Step 1: Install Homebrew

If you don't have Homebrew installed:

```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```

Verify installation:

```bash
brew --version
```

## 🔧 Step 2: Install Node.js

### Option 1: Using nvm (Recommended)

nvm (Node Version Manager) allows you to install and switch between multiple Node.js versions.

1. **Install nvm:**

```bash
# Install nvm via Homebrew
brew install nvm

# Create nvm directory
mkdir ~/.nvm

# Add to your shell profile (~/.zshrc or ~/.bash_profile)
echo 'export NVM_DIR="$HOME/.nvm"' >> ~/.zshrc
echo '[ -s "/opt/homebrew/opt/nvm/nvm.sh" ] && \. "/opt/homebrew/opt/nvm/nvm.sh"' >> ~/.zshrc
echo '[ -s "/opt/homebrew/opt/nvm/etc/bash_completion.d/nvm" ] && \. "/opt/homebrew/opt/nvm/etc/bash_completion.d/nvm"' >> ~/.zshrc

# Reload shell
source ~/.zshrc
```

2. **Install Node.js LTS:**

```bash
# Install latest LTS version
nvm install --lts

# Use the installed version
nvm use --lts

# Set as default
nvm alias default lts/*

# Verify installation
node -v
npm -v
```

### Option 2: Using Homebrew (Direct)

```bash
# Install Node.js LTS directly
brew install node

# Verify installation
node -v
npm -v
```

## 📦 Step 3: Install Git

```bash
# Install Git (if not already installed)
brew install git

# Verify
git --version
```

## 🚀 Step 4: Install MCP ABAP ADT Server

You have two installation options:

### Option A: Install from Pre-built Package (Recommended)

Install from a pre-built `.tgz` package file:

**Global Installation (Recommended):**

```bash
# Download or obtain the package file
# Then install globally
npm install -g ./fr0ster-mcp-abap-adt-1.1.0.tgz

# Verify installation
mcp-abap-adt --help
```

**Available commands after installation:**
- `mcp-abap-adt` - HTTP transport (default)
- `mcp-abap-adt --transport=stdio` - stdio transport (for MCP clients)
- `mcp-abap-adt --transport=http` - HTTP server transport
- `mcp-abap-adt --transport=sse` - SSE server transport

**Usage examples:**
```bash
# HTTP server on default port (3000)
mcp-abap-adt --transport=http

# HTTP server on custom port
mcp-abap-adt --transport=http --port 8080

# SSE server accessible from network
mcp-abap-adt --transport=sse --host 0.0.0.0 --port 3000

# Use custom .env file
mcp-abap-adt --transport=http --env /path/to/custom/.env --port 8080
```

**Local Installation (Project-specific):**

```bash
# Navigate to your project
cd /path/to/your/project

# Install package locally
npm install /path/to/fr0ster-mcp-abap-adt-1.1.0.tgz

# Use via npx
npx mcp-abap-adt --transport=http --port 3000
```

**Troubleshooting:**

If command not found after global installation:
```bash
# Check npm global bin directory
npm config get prefix

# Add to PATH (add to ~/.zshrc or ~/.bash_profile)
export PATH="$(npm config get prefix)/bin:$PATH"
source ~/.zshrc  # or source ~/.bash_profile
```

### Option B: Install from Source (For Development)

Clone and build from source code:

```bash
# Clone repository with submodules
git clone --recurse-submodules https://github.com/fr0ster/mcp-abap-adt.git
cd mcp-abap-adt

# If you already cloned without submodules, initialize them:
# git submodule update --init --recursive

# Install dependencies
npm install

# Build project
npm run build

# Verify installation
npm test
```

## ⚙️ Step 5: Configure SAP Connection

Create `.env` file in project root:

```bash
# Copy template
cp .env.template .env

# Edit with your favorite editor
nano .env
# or
vim .env
# or
code .env  # if you have VS Code
```

Example `.env` content:

```env
SAP_URL=https://your-sap-system.com:8000
SAP_CLIENT=100
SAP_LANGUAGE=en
SAP_AUTH_TYPE=basic
SAP_USERNAME=your_username
SAP_PASSWORD=your_password
TLS_REJECT_UNAUTHORIZED=0
SAP_TIMEOUT_DEFAULT=45000
```

## 🔌 Step 6: Connect to AI Tools

### Server Modes

MCP ABAP ADT Server supports two transport protocols:

1. **http** (default) - HTTP StreamableHTTP transport, works without .env file
2. **stdio** - Standard input/output, used by Cline/Cursor (requires .env file)
2. **SSE/HTTP** - Server-Sent Events over HTTP, for web interfaces

### Cline (VS Code Extension)

Uses **stdio** mode (must be explicitly specified).

**⚠️ IMPORTANT:** After global installation (`npm install -g @fr0ster/mcp-abap-adt`), use the `mcp-abap-adt` command with `--transport=stdio` and `--env` arguments.

1. Install Cline extension in VS Code
2. Open Cline settings (JSON): `Cmd+Shift+P` → "Preferences: Open User Settings (JSON)"
3. Add MCP server configuration:

**For globally installed package (recommended):**

```json
{
  "mcpServers": {
    "mcp-abap-adt": {
      "command": "mcp-abap-adt",
      "args": [
        "--transport=stdio",
        "--env=/path/to/your/e19.env"
      ]
    }
  }
}
```

**Important notes:**
- `--transport=stdio` is **required** (default is HTTP mode)
- `--env` argument is **required** if `.env` file is not in the current working directory
- If `.env` file is in the current directory, you can omit `--env` argument:

```json
{
  "mcpServers": {
    "mcp-abap-adt": {
      "command": "mcp-abap-adt",
      "args": ["--transport=stdio"]
    }
  }
}
```

**Alternative: Using node with full path (if global command not in PATH):**

```json
{
  "mcpServers": {
    "mcp-abap-adt": {
      "command": "node",
      "args": [
        "/usr/local/lib/node_modules/@fr0ster/mcp-abap-adt/bin/mcp-abap-adt.js",
        "--transport=stdio",
        "--env=/path/to/your/e19.env"
      ]
    }
  }
}
```

### Cursor

Uses **stdio** mode (must be explicitly specified).

**⚠️ IMPORTANT:** After global installation, use the `mcp-abap-adt` command with `--transport=stdio` and `--env` arguments.

Add to Cursor settings (`~/.cursor/config.json`):

```json
{
  "mcpServers": {
    "mcp-abap-adt": {
      "command": "mcp-abap-adt",
      "args": [
        "--transport=stdio",
        "--env=/path/to/your/e19.env"
      ]
    }
  }
}
```

**Note:** If `.env` file is in the current directory, you can omit `--env` argument.

### HTTP Mode (Streamable HTTP)

**⚠️ IMPORTANT:** HTTP mode is the **default** mode. No `.env` file is required for HTTP mode (connection can be configured via HTTP headers).

**Starting HTTP Server:**

```bash
# Start server in HTTP mode (default, no arguments needed)
mcp-abap-adt

# Or explicitly specify HTTP mode
mcp-abap-adt --transport=streamable-http

# Or with custom port
mcp-abap-adt --transport=streamable-http --http-port=8080
```

**HTTP Server Options:**
- `--transport=streamable-http` or `--transport=http` - Use HTTP transport (default)
- `--http-port PORT` - Port number (default: 3000)
- `--http-host HOST` - Host address (default: 0.0.0.0)

**Example with custom port:**
```bash
mcp-abap-adt --transport=streamable-http --http-port=8080
```

Server will be available at: `http://localhost:8080/mcp/stream/http`

**Configuration for HTTP clients:**

```json
{
  "local-mcp-http": {
    "disabled": false,
    "timeout": 60,
    "type": "streamableHttp",
    "url": "http://localhost:3000/mcp/stream/http",
    "headers": {
      "x-sap-url": "https://your-sap-system.com:8000",
      "x-sap-auth-type": "basic",
      "x-sap-login": "your_username",
      "x-sap-password": "your_password",
      "x-sap-client": "100"
    }
  }
}
```

**⚠️ NOTE:** For HTTP mode, you can configure SAP connection via HTTP headers (as shown above) OR use `.env` file:

```bash
# Using .env file with HTTP mode
mcp-abap-adt --transport=streamable-http --env=/path/to/your/e19.env
```

### SSE Mode (Server-Sent Events)

**⚠️ IMPORTANT:** SSE mode requires `.env` file or HTTP headers for SAP connection configuration.

**Starting SSE Server:**

```bash
# Start server in SSE mode (requires .env file)
mcp-abap-adt --transport=sse --env=/path/to/your/e19.env

# Or with custom port
mcp-abap-adt --transport=sse --sse-port=3001 --env=/path/to/your/e19.env
```

**SSE Server Options:**
- `--transport=sse` - Use SSE transport
- `--sse-port PORT` - Port number (default: 3001)
- `--sse-host HOST` - Host address (default: 0.0.0.0)
- `--sse-allowed-origins LIST` - Comma-separated allowed origins
- `--sse-enable-dns-protection` - Enable DNS rebinding protection
- `--env=PATH` - Path to `.env` file (required for SSE mode)

**Example with custom port and host:**
```bash
mcp-abap-adt --transport=sse --sse-port=4100 --sse-host=127.0.0.1 --env=/path/to/your/e19.env
```

Server will be available at: `http://127.0.0.1:4100/sse`

**Configuration for SSE clients:**

```json
{
  "local-mcp-sse": {
    "disabled": false,
    "timeout": 60,
    "type": "sse",
    "url": "http://localhost:3001/sse"
  }
}
```

**⚠️ NOTE:** SSE mode requires `.env` file to be specified. The server will not start without it.

## ✅ Step 7: Test Installation

```bash
# Run test suite
npm test

# Test specific connection
node tests/test-connection.js
```

## 🐛 Troubleshooting

### Homebrew installation fails

If you get permission errors:

```bash
sudo chown -R $(whoami) /usr/local/Cellar /usr/local/Homebrew
```

### Node.js version issues

Check and switch Node.js versions:

```bash
# Install nvm (Node Version Manager)
brew install nvm

# Install specific Node.js version
nvm install 18
nvm use 18
```

### SSL/TLS certificate errors

Set in `.env`:

```env
TLS_REJECT_UNAUTHORIZED=0
```

Or install certificates:

```bash
# Update certificates
brew install ca-certificates
```

### Permission denied errors

Fix npm permissions:

```bash
sudo chown -R $(whoami) ~/.npm
sudo chown -R $(whoami) /usr/local/lib/node_modules
```

### Command not found after installation

Add to PATH in `~/.zshrc` or `~/.bash_profile`:

```bash
export PATH="/usr/local/bin:$PATH"
export PATH="$HOME/.npm-global/bin:$PATH"
```

Then reload:

```bash
source ~/.zshrc  # for zsh
# or
source ~/.bash_profile  # for bash
```

## 📚 Next Steps

- [Configure SAP Connection](../../user-guide/CLIENT_CONFIGURATION.md)
- [Review CLI Options](../../user-guide/CLI_OPTIONS.md)

## 💡 Tips for macOS

### Use iTerm2

Better terminal experience:

```bash
brew install --cask iterm2
```

### Use Oh My Zsh

Enhanced shell:

```bash
sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"
```

### Install VS Code via Homebrew

```bash
brew install --cask visual-studio-code
```

### Use Rosetta 2 (Apple Silicon)

If you have M1/M2/M3 Mac and encounter compatibility issues:

```bash
softwareupdate --install-rosetta
```

### Check Architecture

```bash
uname -m
# arm64 = Apple Silicon
# x86_64 = Intel
```
- [Available Tools](../../user-guide/AVAILABLE_TOOLS.md)