shopdb-flask/.claude/archived/MCP-SETUP-GUIDE.md

# MCP Servers Setup Guide

Complete guide to set up Gortex, MySQL, Browser, and GitHub MCP servers for ShopDB.

## Quick Summary

**What you need to do:**
1. Install npm packages
2. Set environment variable for GitHub
3. Restart Claude Code to load MCP servers

---

## Step 1: Install MCP Server Packages

Run these commands:

```bash
# MySQL MCP server (with write support)
npm install -g @benborla29/mcp-server-mysql

# Browser automation MCP server
npm install -g @agent-infra/mcp-server-browser
```

---

## Step 2: Fix GitHub MCP Authentication

The GitHub MCP error "Authorization header is badly formatted" means your GitHub token isn't set.

### Create GitHub Personal Access Token

1. Go to: https://github.com/settings/tokens/new
2. Name: `Claude Code MCP`
3. Select scopes:
   - `repo` (Full control of private repositories)
   - `read:org` (Read org and team membership)
4. Click "Generate token"
5. **Copy the token** (starts with `ghp_...`)

### Set Environment Variable

**Option A: Set for current session** (temporary)
```bash
export GITHUB_PERSONAL_ACCESS_TOKEN="ghp_YOUR_TOKEN_HERE"
```

**Option B: Set permanently** (recommended)
Add to your shell profile (`~/.bashrc` or `~/.bash_profile`):
```bash
echo 'export GITHUB_PERSONAL_ACCESS_TOKEN="ghp_YOUR_TOKEN_HERE"' >> ~/.bashrc
source ~/.bashrc
```

**Option C: Windows Environment Variables** (GUI)
1. Search "Environment Variables" in Windows
2. Click "Environment Variables..."
3. Under "User variables", click "New"
4. Variable name: `GITHUB_PERSONAL_ACCESS_TOKEN`
5. Variable value: `ghp_YOUR_TOKEN_HERE`
6. Click OK, restart Claude Code

---

## Step 3: MCP Configuration

The configuration file is already created at:
`.claude/mcp-servers.json`

It contains:
- **Gortex** - Code intelligence (already running)
- **MySQL** - Database queries
- **Browser** - Frontend testing

### Current Configuration:

```json
{
  "mcpServers": {
    "gortex": {
      "command": "C:\\Users\\270015376\\Documents\\gortex.exe",
      "args": ["mcp"],
      "cwd": "C:\\Users\\270015376\\Documents\\github\\flask-shopdb"
    },
    "mysql": {
      "command": "npx",
      "args": [
        "-y",
        "@benborla29/mcp-server-mysql",
        "mysql://shopdb:shopdb-dev-password@127.0.0.1:3306/shopdb_flask"
      ]
    },
    "browser": {
      "command": "npx",
      "args": [
        "-y",
        "@agent-infra/mcp-server-browser"
      ]
    }
  }
}
```

---

## Step 4: Verify Setup

After installing packages and setting GitHub token:

1. **Restart Claude Code completely** (close and reopen)

2. **Check MCP servers are loaded:**
   - You should see available tools from each server
   - No authentication errors in console

3. **Test each server:**

**Gortex test:**
```
ToolSearch("gortex explore")
```

**MySQL test:**
```
# Once MCP is loaded, you can query:
SELECT COUNT(*) FROM notifications WHERE alertfleet = true;
```

**Browser test:**
```
# Once MCP is loaded:
Navigate to http://localhost:5000/shopdb
```

**GitHub test:**
```
# Once MCP is loaded:
List my repositories
```

---

## Step 5: Using the MCP Servers

### Gortex (Code Intelligence)
**Use for:** Finding code, understanding relationships, editing symbols

**Examples:**
- "Use Gortex to explore fleet alert architecture"
- "Show me what calls get_fleet_alerts"
- "Edit the _alert_targets_endpoint function"

### MySQL (Database)
**Use for:** Querying data, verifying schema, testing SQL

**Examples:**
- "Query all active fleet alerts from database"
- "Show me the notifications table schema"
- "How many operator reports exist?"

### Browser (Frontend Testing)
**Use for:** Testing Vue app, screenshots, UI verification

**Examples:**
- "Navigate to /shopdb/notifications and screenshot"
- "Test the fleet alert form"
- "Verify the notification list loads"

### GitHub (Collaboration)
**Use for:** PRs, issues, CI status

**Examples:**
- "Create PR for fleet alert work"
- "Check CI status on wj branch"
- "List open issues"

---

## Troubleshooting

### GitHub still shows auth error
- Verify token is correct (starts with `ghp_`)
- Check token has `repo` and `read:org` scopes
- Restart Claude Code after setting environment variable
- Try setting token in Windows Environment Variables GUI

### MySQL connection fails
- Verify Docker containers are running: `docker ps`
- Check MySQL is accessible: `mysql -h 127.0.0.1 -u shopdb -pshopdb-dev-password shopdb_flask`
- Verify port 3306 is not blocked

### Browser MCP doesn't work
- Install Chrome/Chromium if not present
- Check browser package installed: `npm list -g @agent-infra/mcp-server-browser`

### Gortex MCP not connecting
- Check daemon is running: `/c/Users/270015376/Documents/gortex.exe status`
- Verify path in mcp-servers.json is correct
- Try starting daemon manually: `/c/Users/270015376/Documents/gortex.exe daemon start`

### MCP servers not loading at all
- Check `.claude/mcp-servers.json` file exists in project
- Verify JSON syntax is valid
- Restart Claude Code completely
- Check Claude Code console for errors

---

## What Each Server Gives You

| Server | Tools | Token Savings |
|--------|-------|---------------|
| **Gortex** | 48 tools (explore, edit_symbol, find_files, etc.) | 30-50K per session |
| **MySQL** | Query, schema inspection, data verification | 5-10K per session |
| **Browser** | Navigate, click, screenshot, test | Catch bugs early |
| **GitHub** | PR, issues, CI status | 5-10K per session |

**Total expected savings: 50-70K tokens per session** (vs current ~120K usage)

---

## Next Steps

1. Run the npm install commands above
2. Create GitHub token and set environment variable
3. Restart Claude Code
4. Try the test commands to verify each server works

Once all four are connected, you'll have complete code + data + frontend + collaboration coverage!