From 2fbf19f825dcc62bae89952fa40e17b7c8f24885 Mon Sep 17 00:00:00 2001
From: Anson Biggs <anson@ansonbiggs.com>
Date: Mon, 13 Oct 2025 19:04:25 -0400
Subject: [PATCH] docs: add MCP server setup guide

Added guide for configuring Playwright and GitLab MCP servers to enable:
- Browser automation for testing the live site
- GitLab pipeline monitoring and artifact access
- Real-time debugging capabilities
---
 Anson-Projects/badfriends/MCP_SETUP.md | 197 +++++++++++++++++++++++++
 1 file changed, 197 insertions(+)
 create mode 100644 Anson-Projects/badfriends/MCP_SETUP.md

diff --git a/Anson-Projects/badfriends/MCP_SETUP.md b/Anson-Projects/badfriends/MCP_SETUP.md
new file mode 100644
index 000000000..ee5687f6e
--- /dev/null
+++ b/Anson-Projects/badfriends/MCP_SETUP.md
@@ -0,0 +1,197 @@
+# MCP Server Setup for BadFriends Debugging
+
+## Useful MCP Servers
+
+### 1. Playwright - Browser Automation
+
+**What it does:**
+- Opens real browser windows
+- Executes JavaScript and sees console errors
+- Interacts with the live site (click, type, navigate)
+- Takes screenshots
+- Perfect for debugging web apps
+
+**Installation:**
+```bash
+npm install -g @modelcontextprotocol/server-playwright
+```
+
+**Configuration:**
+Add to your Claude Code MCP settings:
+```json
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-playwright"]
+    }
+  }
+}
+```
+
+**Usage:**
+Once configured, I can:
+- Navigate to https://badfriends.ansonbiggs.com
+- Test the OAuth flow end-to-end
+- See console errors in real-time
+- Debug JavaScript issues
+- Take screenshots of problems
+
+### 2. GitLab - Pipeline & Repository Access
+
+**What it does:**
+- Monitor pipeline status
+- Get pipeline artifacts
+- Read repository files
+- Create/update merge requests
+- Check CI/CD job logs
+
+**Installation:**
+```bash
+npm install -g @modelcontextprotocol/server-gitlab
+```
+
+**Configuration:**
+You'll need a GitLab Personal Access Token first:
+
+1. Go to: https://gitlab.com/-/user_settings/personal_access_tokens
+2. Create token with scopes: `api`, `read_api`, `read_repository`
+3. Copy the token
+
+Then add to MCP settings:
+```json
+{
+  "mcpServers": {
+    "gitlab": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-gitlab"],
+      "env": {
+        "GITLAB_PERSONAL_TOKEN": "glpat-your-token-here",
+        "GITLAB_API_URL": "https://gitlab.com/api/v4"
+      }
+    }
+  }
+}
+```
+
+**Usage:**
+Once configured, I can:
+- Check if pipeline #2097450460 has finished
+- Download artifacts automatically
+- Read CI/CD logs to debug build failures
+- Monitor deployment status
+- Create merge requests
+
+## Complete Configuration Example
+
+Your full MCP settings would look like:
+
+```json
+{
+  "mcpServers": {
+    "playwright": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-playwright"]
+    },
+    "gitlab": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-gitlab"],
+      "env": {
+        "GITLAB_PERSONAL_TOKEN": "glpat-xxxxxxxxxxxxx",
+        "GITLAB_API_URL": "https://gitlab.com/api/v4"
+      }
+    }
+  }
+}
+```
+
+## Where to Add Configuration
+
+### For Claude Desktop:
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+- **Linux**: `~/.config/Claude/claude_desktop_config.json`
+
+### For Claude Code (CLI):
+Configuration location varies by installation method. Check:
+- `~/.config/claude-code/`
+- Or the documentation at your Claude Code install location
+
+## Verifying Setup
+
+After adding the configuration and restarting Claude Code/Desktop, I'll have access to new tools:
+
+**Playwright tools:**
+- `playwright_navigate`
+- `playwright_click`
+- `playwright_screenshot`
+- `playwright_evaluate`
+
+**GitLab tools:**
+- `gitlab_get_pipeline`
+- `gitlab_list_pipelines`
+- `gitlab_get_job`
+- `gitlab_get_artifact`
+
+## Benefits for This Project
+
+With both configured, I could:
+
+1. **Watch deployments in real-time:**
+   - Monitor GitLab pipeline progress
+   - Get artifacts when ready
+   - Check deployment logs
+
+2. **Test the live site immediately:**
+   - Open in browser as soon as deployed
+   - Test full OAuth flow
+   - See exact error messages
+   - Debug issues interactively
+
+3. **End-to-end validation:**
+   - Push code → Monitor pipeline → Test in browser → Verify it works
+
+This would make debugging much faster than the current cycle of:
+- Push → Wait → Ask you to test → Get error messages → Debug → Repeat
+
+## Quick Start
+
+1. Install both MCP servers:
+   ```bash
+   npm install -g @modelcontextprotocol/server-playwright
+   npm install -g @modelcontextprotocol/server-gitlab
+   ```
+
+2. Create GitLab token: https://gitlab.com/-/user_settings/personal_access_tokens
+
+3. Add configuration to your Claude MCP settings file
+
+4. Restart Claude Code/Desktop
+
+5. Test by asking me to "Check the latest GitLab pipeline" or "Open the site in a browser"
+
+## Security Notes
+
+- GitLab token should have minimal required scopes
+- Don't commit tokens to git
+- Use environment variables or secure storage
+- Tokens can be revoked anytime at GitLab
+
+## Alternative: Puppeteer Instead of Playwright
+
+If you prefer Puppeteer over Playwright:
+
+```bash
+npm install -g @modelcontextprotocol/server-puppeteer
+```
+
+```json
+{
+  "puppeteer": {
+    "command": "npx",
+    "args": ["-y", "@modelcontextprotocol/server-puppeteer"]
+  }
+}
+```
+
+Both work similarly, choose whichever you prefer.
-- 
2.51.2