# Installation Guide

This guide helps you install and configure the Siemens Graph Studio MCP Server for use with VS Code and GitHub Copilot.

## Quick Install (Recommended)

### Option 1: Using pipx (Best for CLI tools)

```bash
# Install pipx if you don't have it
brew install pipx    # macOS
# or: pip install pipx

# Install the MCP server
pipx install siemens-graph-studio-mcp-server
```

### Option 2: Using uv (Fast Python package manager)

```bash
# Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install globally with uv
uv tool install siemens-graph-studio-mcp-server
```

### Option 3: Using pip

```bash
# Ensure you're using Python 3.10+
python3 --version

# Install (use --user to avoid permission issues)
pip install --user siemens-graph-studio-mcp-server
```

## Verify Installation

After installing, verify the command is available:

```bash
# Check the command exists
which siemens-graph-studio-mcp

# Or run directly
siemens-graph-studio-mcp --help
```

**If the command is not found**, see [Troubleshooting: Command Not Found](#command-not-found-after-installation).

## VS Code Setup

### Step 1: Create MCP Configuration

Create `.vscode/mcp.json` in your project root:

```json
{
  "servers": {
    "graph-studio": {
      "type": "stdio",
      "command": "siemens-graph-studio-mcp",
      "env": {
        "ANZO_SERVER": "your-server.example.com",
        "ANZO_PORT": "8443",
        "ANZO_USERNAME": "your-username",
        "ANZO_PASSWORD": "your-password",
        "GRAPHMART_URI": "http://example.com/Graphmart/your-id"
      }
    }
  }
}
```

> **Tip:** If the command is not in PATH, use the full path:
> ```json
> "command": "/Users/yourname/.local/bin/siemens-graph-studio-mcp"
> ```

### Step 2: Enable MCP in VS Code

1. Open VS Code Settings (`Cmd+,` on macOS, `Ctrl+,` on Windows/Linux)
2. Search for "MCP"
3. Enable **"GitHub Copilot Chat: MCP"**

### Step 3: Reload VS Code

1. Open Command Palette (`Cmd+Shift+P` / `Ctrl+Shift+P`)
2. Run **"Developer: Reload Window"**

### Step 4: Verify MCP Connection

1. Open Copilot Chat (`Cmd+Shift+I` / `Ctrl+Shift+I`)
2. Click the **tools icon** (wrench) in the chat panel
3. You should see Graph Studio tools listed

---

## Troubleshooting

### Command Not Found After Installation

**Symptom:** `siemens-graph-studio-mcp: command not found`

**Cause:** The installation directory isn't in your PATH.

**Solutions:**

#### macOS/Linux

```bash
# Find where pip installed the command
python3 -m site --user-base

# The command is in that directory + /bin
# Example: /Users/yourname/.local/bin/siemens-graph-studio-mcp

# Add to PATH in your shell config (~/.zshrc or ~/.bashrc):
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
```

#### Windows

```powershell
# Find Python Scripts directory
python -c "import site; print(site.USER_SITE.replace('site-packages', 'Scripts'))"

# Add that directory to your PATH environment variable
```

#### Use Full Path in VS Code (Quick Fix)

If you don't want to modify PATH, use the full command path in `mcp.json`:

```bash
# Find the full path
python3 -c "import shutil; print(shutil.which('siemens-graph-studio-mcp') or 'Not found')"

# Or for pip-installed scripts
pip show -f siemens-graph-studio-mcp-server | grep siemens-graph-studio-mcp
```

Then use the full path in your `mcp.json`:

```json
{
  "servers": {
    "graph-studio": {
      "command": "/full/path/to/siemens-graph-studio-mcp",
      ...
    }
  }
}
```

---

### MCP Tools Not Appearing in VS Code

**Symptom:** No Graph Studio tools visible in Copilot Chat

**Solutions:**

1. **Check MCP output panel:**
   - View → Output → Select "MCP" from dropdown
   - Look for error messages

2. **Ensure MCP is enabled:**
   - Settings → Search "chat.mcp.enabled" → Enable it

3. **Verify command runs manually:**
   ```bash
   # This should print JSON-RPC initialization
   echo '{"jsonrpc":"2.0","method":"initialize","id":1,"params":{}}' | siemens-graph-studio-mcp
   ```

4. **Check environment variables:**
   - All required env vars must be in `mcp.json`
   - Verify credentials are correct

5. **Reload VS Code:**
   - `Cmd+Shift+P` → "Developer: Reload Window"

---

### Python Version Issues

**Symptom:** `requires Python >= 3.10` or similar errors

**Solution:**

```bash
# Check your Python version
python3 --version

# If below 3.10, install a newer Python:
# macOS:
brew install python@3.12

# Then install with that specific Python
/opt/homebrew/bin/python3.12 -m pip install siemens-graph-studio-mcp-server
```

---

### Dependency Conflicts

**Symptom:** `ERROR: pip's dependency resolver...` or version conflicts

**Solution:** Install in an isolated environment:

```bash
# Option 1: Use pipx (recommended for CLI tools)
pipx install siemens-graph-studio-mcp-server

# Option 2: Use a dedicated virtual environment
python3 -m venv ~/mcp-env
~/mcp-env/bin/pip install siemens-graph-studio-mcp-server

# Then use the full path in mcp.json:
# "command": "/Users/yourname/mcp-env/bin/siemens-graph-studio-mcp"
```

---

### Connection Errors to Graph Studio

**Symptom:** "Connection refused" or authentication errors

**Solutions:**

1. **Test credentials manually:**
   ```bash
   export ANZO_SERVER="your-server.example.com"
   export ANZO_PORT="8443"
   export ANZO_USERNAME="your-username"
   export ANZO_PASSWORD="your-password"
   export GRAPHMART_URI="http://example.com/Graphmart/your-id"
   
   siemens-graph-studio-mcp
   ```

2. **Verify network access:**
   ```bash
   curl -k https://your-server.example.com:8443/health
   ```

3. **Check VPN:** Ensure you're connected to required VPN

---

### SSL/Certificate Errors

**Symptom:** SSL verification failed

**Solution:** If your Graph Studio uses self-signed certificates:

```json
{
  "servers": {
    "graph-studio": {
      "command": "siemens-graph-studio-mcp",
      "env": {
        "ANZO_SSL_VERIFY": "false",
        ...
      }
    }
  }
}
```

---

## Getting Help

If you're still having issues:

1. Run the verification script: `siemens-graph-studio-mcp --verify`
2. Check the [GitHub Issues](https://github.com/siemens/graph-studio-mcp-server/issues)
3. Collect diagnostic info:
   ```bash
   python3 --version
   pip show siemens-graph-studio-mcp-server
   which siemens-graph-studio-mcp
   ```
