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)

```bash
# 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

```bash
# 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

```bash
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

```bash
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:

```yaml
# 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.