This commit is contained in:
489
plans/mcp-server-testing-guide.md
Normal file
489
plans/mcp-server-testing-guide.md
Normal file
@@ -0,0 +1,489 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user