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:

   npm install -g @modelcontextprotocol/inspector
   

   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:

npx -y chrome-devtools-mcp@latest --headless true --isolated false --channel stable

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:

   mcp-inspector npx -y chrome-devtools-mcp@latest --headless true --isolated false --channel stable
   

   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:

C:\Users\games3\.local\bin\uvx.exe markitdown-mcp

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:

   mcp-inspector C:\Users\games3\.local\bin\uvx.exe markitdown-mcp
   

   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:

  pip install uvx
  

  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:

$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:

   curl -H "Authorization: token 391c9ddbe113378bc87bb8184800ba954648fcf8" https://gitea.torbonium.com/api/v1/user/repos
   

   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:

$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:

$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:

$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:

   mcp-inspector npx -y @modelcontextprotocol/server-docker
   

   mcp-inspector npx -y @modelcontextprotocol/server-docker
   

Verify Docker Access Directly:

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:

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

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:

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

   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:

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:

npx -y @modelcontextprotocol/server-fetch

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:

   mcp-inspector npx -y @modelcontextprotocol/server-fetch
   

   mcp-inspector npx -y @modelcontextprotocol/server-fetch
   

3. Test fetching a URL through the inspector

Test Fetch Capability Directly:

curl https://api.github.com/users/github

# 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:

# 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:

# Install globally
npm install -g @modelcontextprotocol/inspector

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

# Install globally
npm install -g @modelcontextprotocol/inspector

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

Example Sessions:

# 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

# 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