docs/developer-guide/mcp-testing.md

MCP Testing Infrastructure

This document describes the Docker-based MCP testing infrastructure for KGraph-MCP.

Overview

The project includes Docker containers for running MCP (Model Context Protocol) servers locally to enable comprehensive E2E testing without relying on external services.

Available MCP Servers

1. Sentiment Analysis Server

• Port: 7860
• Endpoint: http://localhost:7860/gradio_api/mcp/sse
• Purpose: Analyzes sentiment of text input
• Input Format: {"data": ["text to analyze"]}
• Output Format: {"data": [{"label": "POSITIVE", "score": 0.95, "all_scores": {...}}]}

2. Text Summarization Server

• Port: 7861
• Endpoint: http://localhost:7861/gradio_api/mcp/sse
• Purpose: Summarizes long text content
• Input Format: {"data": ["text to summarize", "max_length", "min_length"]}
• Output Format: {"data": ["summarized text content"]}

Quick Start

Using Just Commands (Recommended)

# Start MCP test servers
just mcp-start

# Test endpoints are working
just mcp-test

# Run E2E tests with MCP servers
just test-e2e-mcp

# Stop MCP servers
just mcp-stop

Manual Docker Commands

# Start servers
docker-compose -f docker-compose.test.yml up --build -d

# Check server health
docker-compose -f docker-compose.test.yml ps

# View server logs
docker-compose -f docker-compose.test.yml logs

# Stop servers
docker-compose -f docker-compose.test.yml down

Testing Workflow

1. Start MCP Servers: The servers boot up in Docker containers
2. Health Checks: Automatic health checks ensure servers are ready
3. Run Tests: E2E tests can now call real MCP endpoints
4. Cleanup: Servers are stopped and containers removed

Configuration

Environment Variables

The servers use these environment variables:

• HF_TOKEN: Hugging Face API token (defaults to dummy_token_for_testing)

Port Mapping

• Sentiment Server: Host 7860 → Container 7860
• Summarizer Server: Host 7861 → Container 7860

Manual Testing

You can manually test the MCP endpoints once servers are running:

Test Sentiment Analysis

curl -X POST http://localhost:7860/gradio_api/mcp/sse \
  -H "Content-Type: application/json" \
  -d '{"data": ["This is amazing! I love it!"]}'

Test Text Summarization

curl -X POST http://localhost:7861/gradio_api/mcp/sse \
  -H "Content-Type: application/json" \
  -d '{"data": ["Artificial Intelligence has revolutionized many industries. Machine learning algorithms have achieved breakthroughs in computer vision and natural language processing.", "100", "30"]}'

Troubleshooting

Servers Won't Start

1. Check Docker is running: docker --version
2. Check ports aren't in use: lsof -i :7860,7861
3. View container logs: docker-compose -f docker-compose.test.yml logs

Health Checks Failing

1. Wait longer - containers need time to start Gradio servers
2. Check HF_TOKEN is set correctly
3. Verify network connectivity

Tests Still Failing

1. Ensure servers are healthy: just mcp-test
2. Check test configuration matches server endpoints
3. Verify firewall isn't blocking Docker networking

Development

Adding New MCP Servers

1. Create new directory: mcp_new_tool_gradio/
2. Add Dockerfile and requirements.txt
3. Update docker-compose.test.yml
4. Add tool configuration to data/initial_tools.json
5. Update tests to use new endpoint

Modifying Existing Servers

1. Edit the app code in mcp_*_tool_gradio/
2. Rebuild containers: just mcp-restart
3. Test changes: just mcp-test

CI/CD Integration

The MCP testing infrastructure can be integrated into CI/CD pipelines:

# GitHub Actions example
- name: Start MCP Test Servers
  run: just mcp-start

- name: Run E2E Tests
  run: pytest tests/test_e2e_mcp_execution.py -v

- name: Stop MCP Test Servers
  run: just mcp-stop
  if: always()

Files Structure

├── docker-compose.test.yml          # Docker Compose for test servers
├── mcp_sentiment_tool_gradio/       # Sentiment analysis server
│   ├── Dockerfile
│   ├── app.py
│   └── requirements.txt
├── mcp_summarizer_tool_gradio/      # Text summarization server
│   ├── Dockerfile
│   ├── app.py
│   └── requirements.txt
└── scripts/
    ├── start-test-mcp-servers.sh    # Start script
    ├── stop-test-mcp-servers.sh     # Stop script
    └── test-mcp-endpoints.sh        # Test script

This infrastructure enables reliable, fast, and reproducible testing of MCP functionality without external dependencies.