flyer-crawler.projectium.com/plans/mcp-server-testing-guide.md

# MCP Server Testing Guide

This guide provides step-by-step instructions for manually testing each of the configured MCP servers.

## Overview

MCP (Model Context Protocol) servers are standalone processes that expose tools and resources to AI assistants. Each server runs independently and communicates via stdio.

## Testing Prerequisites

1. **MCP Inspector Tool** - Install the official MCP testing tool:
   ```bash
   npm install -g @modelcontextprotocol/inspector
   ```
   ```powershell
   npm install -g @modelcontextprotocol/inspector
   ```

2. **Alternative: Manual stdio testing** - Use the MCP CLI for direct interaction

---

## 1. Chrome DevTools MCP Server

**Purpose**: Browser automation and Chrome DevTools integration

### Test Command:
```bash
npx -y chrome-devtools-mcp@latest --headless true --isolated false --channel stable
```
```powershell
npx -y chrome-devtools-mcp@latest --headless true --isolated false --channel stable
```

### Expected Capabilities:
- Browser launch and control
- DOM inspection
- Network monitoring
- JavaScript execution in browser context

### Manual Test Steps:
1. Run the command above
2. The server should start and output MCP protocol messages
3. Use MCP Inspector to connect:
   ```bash
   mcp-inspector npx -y chrome-devtools-mcp@latest --headless true --isolated false --channel stable
   ```
   ```powershell
   mcp-inspector npx -y chrome-devtools-mcp@latest --headless true --isolated false --channel stable
   ```

### Success Indicators:
- Server starts without errors
- Lists available tools (e.g., `navigate`, `click`, `screenshot`)
- Can execute browser actions

---

## 2. Markitdown MCP Server

**Purpose**: Convert various file formats to markdown

### Test Command:
```bash
C:\Users\games3\.local\bin\uvx.exe markitdown-mcp
```
```powershell
C:\Users\games3\.local\bin\uvx.exe markitdown-mcp
```

### Expected Capabilities:
- Convert PDF to markdown
- Convert DOCX to markdown
- Convert HTML to markdown
- Convert images (OCR) to markdown

### Manual Test Steps:
1. Ensure `uvx` is installed (Python tool)
2. Run the command above
3. Test with MCP Inspector:
   ```bash
   mcp-inspector C:\Users\games3\.local\bin\uvx.exe markitdown-mcp
   ```
   ```powershell
   mcp-inspector C:\Users\games3\.local\bin\uvx.exe markitdown-mcp
   ```

### Success Indicators:
- Server initializes successfully
- Lists conversion tools
- Can convert a test file

### Troubleshooting:
- If `uvx` is not found, install it:
  ```bash
  pip install uvx
  ```
  ```powershell
  pip install uvx
  ```
- Verify Python is in PATH

---

## 3. Gitea MCP Servers

You have three Gitea server configurations. All use the same executable but connect to different instances.

### A. Gitea Torbonium

**Host**: https://gitea.torbonium.com

#### Test Command:
```powershell
$env:GITEA_HOST="https://gitea.torbonium.com"
$env:GITEA_ACCESS_TOKEN="391c9ddbe113378bc87bb8184800ba954648fcf8"
d:\gitea-mcp\gitea-mcp.exe run -t stdio
```

#### Expected Capabilities:
- List repositories
- Create/update issues
- Manage pull requests
- Read/write repository files
- Manage branches

#### Manual Test Steps:
1. Set environment variables
2. Run gitea-mcp.exe
3. Use MCP Inspector or test direct API access:
   ```bash
   curl -H "Authorization: token 391c9ddbe113378bc87bb8184800ba954648fcf8" https://gitea.torbonium.com/api/v1/user/repos
   ```
   ```powershell
   Invoke-RestMethod -Uri "https://gitea.torbonium.com/api/v1/user/repos" -Headers @{Authorization="token 391c9ddbe113378bc87bb8184800ba954648fcf8"}
   ```

### B. Gitea LAN (Torbolan)

**Host**: https://gitea.torbolan.com
**Status**: ⚠️ Token needs replacement

#### Test Command:
```powershell
$env:GITEA_HOST="https://gitea.torbolan.com"
$env:GITEA_ACCESS_TOKEN="REPLACE_WITH_NEW_TOKEN"  # ⚠️ UPDATE THIS
d:\gitea-mcp\gitea-mcp.exe run -t stdio
```

#### Before Testing:
1. Generate a new access token:
   - Log into https://gitea.torbolan.com
   - Go to Settings → Applications → Generate New Token
   - Copy the token and update the configuration

### C. Gitea Projectium

**Host**: https://gitea.projectium.com

#### Test Command:
```powershell
$env:GITEA_HOST="https://gitea.projectium.com"
$env:GITEA_ACCESS_TOKEN="c72bc0f14f623fec233d3c94b3a16397fe3649ef"
d:\gitea-mcp\gitea-mcp.exe run -t stdio
```

### Success Indicators for All Gitea Servers:
- Server connects to Gitea instance
- Lists available repositories
- Can read repository metadata
- Authentication succeeds

### Troubleshooting:
- **401 Unauthorized**: Token is invalid or expired
- **Connection refused**: Check if Gitea instance is accessible
- **SSL errors**: Verify HTTPS certificate validity

---

## 4. Podman/Docker MCP Server

**Purpose**: Container management and Docker operations

### Test Command:
```powershell
$env:DOCKER_HOST="npipe:////./pipe/docker_engine"
npx -y @modelcontextprotocol/server-docker
```

### Expected Capabilities:
- List containers
- Start/stop containers
- View container logs
- Execute commands in containers
- Manage images

### Manual Test Steps:
1. Ensure Docker Desktop or Podman is running
2. Verify named pipe exists: `npipe:////./pipe/docker_engine`
3. Run the server command
4. Test with MCP Inspector:
   ```bash
   mcp-inspector npx -y @modelcontextprotocol/server-docker
   ```
   ```powershell
   mcp-inspector npx -y @modelcontextprotocol/server-docker
   ```

### Verify Docker Access Directly:
```powershell
docker ps
docker images
```

### Success Indicators:
- Server connects to Docker daemon
- Can list containers and images
- Can execute container operations

### Troubleshooting:
- **Cannot connect to Docker daemon**: Ensure Docker Desktop is running
- **Named pipe error**: Check DOCKER_HOST configuration
- **Permission denied**: Run as administrator

---

## 5. Filesystem MCP Server

**Purpose**: Access and manipulate files in specified directory

### Test Command:
```bash
npx -y @modelcontextprotocol/server-filesystem "D:\gitea\flyer-crawler.projectium.com\flyer-crawler.projectium.com"
```
```powershell
npx -y @modelcontextprotocol/server-filesystem "D:\gitea\flyer-crawler.projectium.com\flyer-crawler.projectium.com"
```

### Expected Capabilities:
- List directory contents
- Read files
- Write files
- Search files
- Get file metadata

### Manual Test Steps:
1. Run the command above
2. Use MCP Inspector:
   ```bash
   mcp-inspector npx -y @modelcontextprotocol/server-filesystem "D:\gitea\flyer-crawler.projectium.com\flyer-crawler.projectium.com"
   ```
   ```powershell
   mcp-inspector npx -y @modelcontextprotocol/server-filesystem "D:\gitea\flyer-crawler.projectium.com\flyer-crawler.projectium.com"
   ```
3. Test listing directory contents

### Verify Directory Access:
```powershell
Test-Path "D:\gitea\flyer-crawler.projectium.com\flyer-crawler.projectium.com"
Get-ChildItem "D:\gitea\flyer-crawler.projectium.com\flyer-crawler.projectium.com" | Select-Object -First 5
```

### Success Indicators:
- Server starts successfully
- Can list directory contents
- Can read file contents
- Write operations work (if permissions allow)

### Security Note:
This server has access to your entire project directory. Ensure it's only used in trusted contexts.

---

## 6. Fetch MCP Server

**Purpose**: Make HTTP requests to external APIs and websites

### Test Command:
```bash
npx -y @modelcontextprotocol/server-fetch
```
```powershell
npx -y @modelcontextprotocol/server-fetch
```

### Expected Capabilities:
- HTTP GET requests
- HTTP POST requests
- Handle JSON/text responses
- Custom headers
- Follow redirects

### Manual Test Steps:
1. Run the server command
2. Use MCP Inspector:
   ```bash
   mcp-inspector npx -y @modelcontextprotocol/server-fetch
   ```
   ```powershell
   mcp-inspector npx -y @modelcontextprotocol/server-fetch
   ```
3. Test fetching a URL through the inspector

### Test Fetch Capability Directly:
```bash
curl https://api.github.com/users/github
```
```powershell
# Test if curl/web requests work
curl https://api.github.com/users/github
# Or use Invoke-RestMethod
Invoke-RestMethod -Uri "https://api.github.com/users/github"
```

### Success Indicators:
- Server initializes
- Can fetch URLs
- Returns proper HTTP responses
- Handles errors gracefully

---

## Comprehensive Testing Script

Here's a PowerShell script to test all servers:

```powershell
# test-mcp-servers.ps1

Write-Host "=== MCP Server Testing Suite ===" -ForegroundColor Cyan

# Test 1: Chrome DevTools
Write-Host "`n[1/8] Testing Chrome DevTools..." -ForegroundColor Yellow
$chromeProc = Start-Process -FilePath "npx" -ArgumentList "-y","chrome-devtools-mcp@latest","--headless","true" -PassThru -NoNewWindow
Start-Sleep -Seconds 3
if (!$chromeProc.HasExited) {
    Write-Host "✓ Chrome DevTools server started" -ForegroundColor Green
    $chromeProc.Kill()
} else {
    Write-Host "✗ Chrome DevTools failed" -ForegroundColor Red
}

# Test 2: Markitdown
Write-Host "`n[2/8] Testing Markitdown..." -ForegroundColor Yellow
if (Test-Path "C:\Users\games3\.local\bin\uvx.exe") {
    Write-Host "✓ Markitdown executable found" -ForegroundColor Green
} else {
    Write-Host "✗ Markitdown executable not found" -ForegroundColor Red
}

# Test 3-5: Gitea Servers
Write-Host "`n[3/8] Testing Gitea Torbonium..." -ForegroundColor Yellow
try {
    $response = Invoke-RestMethod -Uri "https://gitea.torbonium.com/api/v1/user" -Headers @{Authorization="token 391c9ddbe113378bc87bb8184800ba954648fcf8"}
    Write-Host "✓ Gitea Torbonium authenticated as: $($response.login)" -ForegroundColor Green
} catch {
    Write-Host "✗ Gitea Torbonium failed: $($_.Exception.Message)" -ForegroundColor Red
}

Write-Host "`n[4/8] Testing Gitea LAN..." -ForegroundColor Yellow
Write-Host "⚠ Token needs replacement" -ForegroundColor Yellow

Write-Host "`n[5/8] Testing Gitea Projectium..." -ForegroundColor Yellow
try {
    $response = Invoke-RestMethod -Uri "https://gitea.projectium.com/api/v1/user" -Headers @{Authorization="token c72bc0f14f623fec233d3c94b3a16397fe3649ef"}
    Write-Host "✓ Gitea Projectium authenticated as: $($response.login)" -ForegroundColor Green
} catch {
    Write-Host "✗ Gitea Projectium failed: $($_.Exception.Message)" -ForegroundColor Red
}

# Test 6: Podman/Docker
Write-Host "`n[6/8] Testing Docker..." -ForegroundColor Yellow
try {
    docker ps > $null 2>&1
    if ($LASTEXITCODE -eq 0) {
        Write-Host "✓ Docker daemon accessible" -ForegroundColor Green
    } else {
        Write-Host "✗ Docker daemon not accessible" -ForegroundColor Red
    }
} catch {
    Write-Host "✗ Docker not available" -ForegroundColor Red
}

# Test 7: Filesystem
Write-Host "`n[7/8] Testing Filesystem..." -ForegroundColor Yellow
if (Test-Path "D:\gitea\flyer-crawler.projectium.com\flyer-crawler.projectium.com") {
    Write-Host "✓ Project directory accessible" -ForegroundColor Green
} else {
    Write-Host "✗ Project directory not found" -ForegroundColor Red
}

# Test 8: Fetch
Write-Host "`n[8/8] Testing Fetch..." -ForegroundColor Yellow
try {
    $response = Invoke-RestMethod -Uri "https://api.github.com/zen"
    Write-Host "✓ Fetch capability working" -ForegroundColor Green
} catch {
    Write-Host "✗ Fetch failed" -ForegroundColor Red
}

Write-Host "`n=== Testing Complete ===" -ForegroundColor Cyan
```

---

## Using MCP Inspector for Interactive Testing

The MCP Inspector provides a visual interface for testing servers:

```bash
# Install globally
npm install -g @modelcontextprotocol/inspector

# Test any server
mcp-inspector <command> <args>
```
```powershell
# Install globally
npm install -g @modelcontextprotocol/inspector

# Test any server
mcp-inspector <command> <args>
```

### Example Sessions:

```bash
# Test fetch server
mcp-inspector npx -y @modelcontextprotocol/server-fetch

# Test filesystem server
mcp-inspector npx -y @modelcontextprotocol/server-filesystem "D:\gitea\flyer-crawler.projectium.com\flyer-crawler.projectium.com"

# Test Docker server
mcp-inspector npx -y @modelcontextprotocol/server-docker
```
```powershell
# Test fetch server
mcp-inspector npx -y @modelcontextprotocol/server-fetch

# Test filesystem server
mcp-inspector npx -y @modelcontextprotocol/server-filesystem "D:\gitea\flyer-crawler.projectium.com\flyer-crawler.projectium.com"

# Test Docker server
mcp-inspector npx -y @modelcontextprotocol/server-docker
```

---

## Common Issues and Solutions

### Issue: "Cannot find module" or "Command not found"
**Solution**: Ensure Node.js and npm are installed and in PATH

### Issue: MCP server starts but doesn't respond
**Solution**: Check server logs, verify stdio communication, ensure no JSON parsing errors

### Issue: Authentication failures with Gitea
**Solution**: 
1. Verify tokens haven't expired
2. Check token permissions in Gitea settings
3. Ensure network access to Gitea instances

### Issue: Docker server cannot connect
**Solution**:
1. Start Docker Desktop
2. Verify DOCKER_HOST environment variable
3. Check Windows named pipe permissions

---

## Next Steps

After testing:
1. Document which servers are working
2. Fix any configuration issues
3. Update tokens as needed
4. Consider security implications of exposed servers
5. Set up monitoring for server health

---

## Security Recommendations

1. **Token Security**: Keep Gitea tokens secure, rotate regularly
2. **Filesystem Access**: Limit filesystem server scope to necessary directories
3. **Network Access**: Consider firewall rules for external MCP servers
4. **Audit Logging**: Enable logging for all MCP server operations
5. **Token Permissions**: Use minimal required permissions for Gitea tokens