Peekaboo/docs/mcp-testing.md

summary	read_when
Review MCP Server Testing Guide guidance	planning work related to mcp server testing guide debugging or extending features described here

MCP Server Testing Guide

This guide explains how to test the Peekaboo MCP (Model Context Protocol) server during development using various tools and approaches.

Overview

The Peekaboo MCP server ships with the CLI (peekaboo mcp) and provides AI assistants with direct access to macOS automation capabilities through a standardized protocol. Testing this server effectively requires tools that can simulate MCP client interactions and allow rapid iteration during development.

Testing Approaches

1. MCP Inspector (Official Tool)

The official MCP Inspector provides a web-based interface for testing MCP servers:

# Test the installed CLI
npx @modelcontextprotocol/inspector peekaboo mcp

# Test a local build
pnpm run build:cli
PEEKABOO_BIN="$(swift build --show-bin-path --package-path Apps/CLI)/peekaboo"
npx @modelcontextprotocol/inspector "$PEEKABOO_BIN" mcp

# Test with specific AI provider
PEEKABOO_AI_PROVIDERS="ollama/llama3.3" npx @modelcontextprotocol/inspector peekaboo mcp

Features:

• Visual interface showing available tools, resources, and prompts
• Interactive tool calling with parameter inputs
• Real-time response visualization
• Session history tracking

2. Reloaderoo (Development Proxy)

Reloaderoo is a powerful MCP development tool that provides both CLI testing and hot-reload capabilities. Due to npm package issues, it should be built from source.

Installation

# Clone and build from source
git clone https://github.com/cameroncooke/reloaderoo.git
cd reloaderoo
npm install
npm run build

CLI Mode (Direct Testing)

# Build the CLI once and set the binary path
pnpm run build:cli
export PEEKABOO_BIN="$(swift build --show-bin-path --package-path Apps/CLI)/peekaboo"

# List available tools
node reloaderoo/dist/bin/reloaderoo.js inspect list-tools -- "$PEEKABOO_BIN" mcp

# Call a specific tool
node reloaderoo/dist/bin/reloaderoo.js inspect call-tool image --params '{"format": "data", "app_target": "Safari"}' -- "$PEEKABOO_BIN" mcp
node reloaderoo/dist/bin/reloaderoo.js inspect call-tool image --params '{"format": "data", "app_target": "Safari:1", "scale": "native"}' -- "$PEEKABOO_BIN" mcp
node reloaderoo/dist/bin/reloaderoo.js inspect call-tool see --params '{"app_target": "PID:1234:2"}' -- "$PEEKABOO_BIN" mcp

# Get server information
node reloaderoo/dist/bin/reloaderoo.js inspect server-info -- "$PEEKABOO_BIN" mcp

# List resources
node reloaderoo/dist/bin/reloaderoo.js inspect list-resources -- "$PEEKABOO_BIN" mcp

# List prompts
node reloaderoo/dist/bin/reloaderoo.js inspect list-prompts -- "$PEEKABOO_BIN" mcp

# Test with AI provider
PEEKABOO_AI_PROVIDERS="anthropic/claude-opus-4-8" node reloaderoo/dist/bin/reloaderoo.js inspect call-tool analyze --params '{"image_path": "/tmp/screenshot.png", "question": "What is shown in this image?"}' -- "$PEEKABOO_BIN" mcp

Proxy Mode (Hot-Reload Development)

# Start Reloaderoo as a proxy (for manual testing)
node reloaderoo/dist/bin/reloaderoo.js proxy -- "$PEEKABOO_BIN" mcp

# Configure in Claude Code for hot-reload development with local build
claude mcp add peekaboo-local node $PWD/reloaderoo/dist/bin/reloaderoo.js proxy -- "$PEEKABOO_BIN" mcp

# The proxy adds a 'restart_server' tool that can be called from within Claude Code:
# "Please restart the MCP server" - This will reload your local changes without losing session context

Benefits:

• Test MCP servers without full client setup
• Hot-reload servers during development without losing AI session context
• Direct command-line access for CI/CD integration
• Transparent protocol forwarding with debug logging
• Built-in restart_server tool for seamless reloading

3. Direct Claude Code Integration

For production-like testing, integrate directly with Claude Code:

# Add the MCP server to Claude Code (local scope)
claude mcp add peekaboo peekaboo mcp

# Add with environment variables
claude mcp add peekaboo peekaboo mcp \
  -e PEEKABOO_AI_PROVIDERS="anthropic/claude-opus-4-8"

# List configured servers
claude mcp list

# Remove server
claude mcp remove peekaboo

4. Manual Testing with curl

For low-level protocol testing, you can interact with the MCP server directly:

# Start the server in stdio mode
peekaboo mcp

# Send JSON-RPC requests via stdin
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | peekaboo mcp

Development Workflow

Recommended Testing Cycle

1. Initial Development:

   • Use MCP Inspector for interactive testing
   • Verify tool schemas and responses
   • Test error handling with invalid inputs

2. Integration Testing:

   • Configure in Claude Code for real-world usage
   • Test tool interactions in actual AI conversations
   • Verify resource access and permissions

3. Continuous Development with Reloaderoo:

   • Start with Reloaderoo proxy in Claude Code
   • Make changes to the Swift CLI/Core code
   • Run pnpm run build:cli to compile changes
   • In Claude Code, ask: "Please restart the MCP server"
   • The proxy reloads with your new code while maintaining session context
   • Continue testing without losing conversation history

Hot-Reload Example Workflow

# Terminal 1: Set up Reloaderoo with local server
cd ~/Projects/Peekaboo
PEEKABOO_BIN="$(swift build --show-bin-path --package-path Apps/CLI)/peekaboo"
claude mcp add peekaboo-local node $PWD/reloaderoo/dist/bin/reloaderoo.js proxy -- "$PEEKABOO_BIN" mcp

# Terminal 2: Watch for changes and rebuild
pnpm run build:cli  # Rebuild after changes (or use your local watcher)

# In Claude Code:
# 1. Test current functionality: "Take a screenshot of Safari"
# 2. Make changes in Apps/CLI or Core/PeekabooCore
# 3. Run: pnpm run build:cli
# 4. Tell Claude: "Please restart the MCP server"
# 5. Test new functionality without losing context

Environment Configuration

# Set AI provider for agent tools
export PEEKABOO_AI_PROVIDERS="anthropic/claude-opus-4-8"

# Enable debug logging
export DEBUG="peekaboo:*"

# Configure credentials
./scripts/peekaboo-wait.sh config set-credential ANTHROPIC_API_KEY sk-ant-...

Common Testing Scenarios

1. Tool Discovery

Test that all tools are properly exposed:

• List all available tools
• Verify tool descriptions are clear
• Check parameter schemas are complete

2. Screenshot Capabilities

// Expected tool: captureScreen
{
  "app": "Safari",
  "savePath": "/tmp/screenshot.png",
  "format": "png"
}

3. UI Automation

// Expected tool: click
{
  "elementDescription": "Submit button"
}

// Expected tool: type
{
  "text": "Hello, World!"
}

4. Agent Integration

// Expected tool: runAgent
{
  "task": "Take a screenshot of the current window",
  "provider": "anthropic/claude-opus-4-8"
}

Troubleshooting

Server Won't Start

• Check Node.js version (requires 18+)
• Verify all dependencies are installed
• Ensure no port conflicts for SSE/HTTP modes

Tools Not Available

• Verify Peekaboo CLI is built and accessible
• Check PATH includes Peekaboo binary location
• Ensure proper permissions for screen recording and accessibility

Connection Issues

• For stdio mode: Ensure proper JSON-RPC formatting
• For SSE mode: Check firewall settings
• For HTTP mode: Verify CORS configuration

Best Practices

1. Version Testing:

   • Always test with specific versions (@beta, @latest)
   • Document which version was tested
   • Test upgrade paths between versions

2. Error Handling:

   • Test with invalid parameters
   • Verify graceful degradation
   • Check timeout handling

3. Performance Testing:

   • Monitor response times for tools
   • Test with rapid sequential calls
   • Verify memory usage over time

4. Security Testing:

   • Validate input sanitization
   • Test path traversal prevention
   • Verify credential handling

Future Improvements

1. Automated Testing Suite:

   • Create comprehensive test cases
   • Implement CI/CD integration
   • Add performance benchmarks

2. Mock MCP Client:

   • Build lightweight testing client
   • Support scripted test scenarios
   • Enable regression testing

3. Debug Mode Enhancements:

   • Add detailed protocol logging
   • Implement request/response recording
   • Create replay functionality

Recent test snapshot (Nov 2025)

• Hot-reload via Reloaderoo works against a local Server build when proxied through Claude Code.
• image tool captures frontmost window with correct metadata; list returns apps/windows/status.
• analyze requires PEEKABOO_AI_PROVIDERS at server start; no per-call provider override yet.
• Confirmed tool inventory: image, analyze, list, see, click, type, scroll, hotkey, swipe, run, sleep, clean, agent, app, window, menu, permissions, move, drag, dialog, space, dock.

Conclusion

Testing MCP servers effectively requires a combination of tools and approaches. While the MCP Inspector provides excellent interactive testing, tools like Reloaderoo (once installation issues are resolved) will enable more efficient development workflows with hot-reload capabilities. Direct integration with Claude Code remains the gold standard for production testing.