# MCP Executor Server

A secure, Docker-based code execution server that provides HTTP API endpoints for running Python code in isolated containers. Perfect for integration with automation tools like n8n, web applications, or any HTTP client.

## 🚀 Features

- **🔒 Secure Execution** - Code runs in isolated Docker containers
- **⚡ Fast Performance** - Optimized for quick code execution
- **📡 Real-time Streaming** - Server-Sent Events (SSE) for live output
- **🌐 HTTP API** - RESTful endpoints for easy integration
- **📊 Health Monitoring** - Built-in health check endpoint
- **🐍 Python Support** - Execute Python code with full library access
- **🔧 Docker Integration** - Uses `my-llm-sandbox` container for execution

## 📋 Prerequisites

- **Docker Desktop** - Must be running and in Linux containers mode
- **Node.js** - Version 18+ recommended
- **Docker Image** - `my-llm-sandbox` image must be available locally

## 🛠️ Installation & Setup

### 1. Clone and Navigate
```bash
cd src
```

### 2. Install Dependencies
```bash
npm install
```

### 3. Start the Server

**Development Mode (Recommended):**
```bash
npm run dev
```

**Production Mode:**
```bash
npm run build
npm start
```

The server will start on `http://localhost:3000`

## 📡 API Endpoints

### 1. Execute Code
**POST** `/execute`

Execute Python code in a secure Docker container.

**Request Body:**
```json
{
  "code": "print('Hello, World!')",
  "language": "python",
  "timeout": 30,
  "libraries": []
}
```

**Response:**
```json
{
  "content": [
    {
      "type": "text",
      "text": "Hello, World!\n"
    }
  ],
  "exitCode": 0
}
```

### 2. Real-time Streaming
**GET** `/sse`

Connect to Server-Sent Events for real-time output streaming.

**Usage:**
- Open in browser: `http://localhost:3000/sse`
- Or use curl: `curl http://localhost:3000/sse`

**Output Format:**
```
data: {"type":"stdout","data":"Hello, World!\n"}
data: {"type":"stderr","data":"Error message\n"}
```

### 3. Health Check
**GET** `/health`

Check if the server is running properly.

**Response:**
```json
{
  "status": "ok",
  "message": "MCP Executor server is healthy",
  "timestamp": "2025-07-10T18:12:11.711Z"
}
```

## 🧪 Testing

### Using Postman

1. **Test Health Check:**
   - Method: `GET`
   - URL: `http://localhost:3000/health`

2. **Test Code Execution:**
   - Method: `POST`
   - URL: `http://localhost:3000/execute`
   - Headers: `Content-Type: application/json`
   - Body:
   ```json
   {
     "code": "print('Hello from Postman!')",
     "language": "python"
   }
   ```

3. **Test SSE Streaming:**
   - Method: `GET`
   - URL: `http://localhost:3000/sse`
   - Keep connection open while testing `/execute`

### Using curl

```bash
# Health check
curl http://localhost:3000/health

# Execute code
curl -X POST http://localhost:3000/execute \
  -H "Content-Type: application/json" \
  -d '{"code": "print(\"Hello from curl!\")", "language": "python"}'

# SSE streaming
curl http://localhost:3000/sse
```

## 🔧 n8n Integration

### Basic Setup

1. **Add HTTP Request Node**
2. **Configure:**
   - Method: `POST`
   - URL: `http://localhost:3000/execute`
   - Headers: `Content-Type: application/json`
   - Body (JSON):
   ```json
   {
     "code": "print('Hello from n8n!')",
     "language": "python"
   }
   ```

### Advanced Examples

**Dynamic Code Execution:**
```json
{
  "code": "{{ $json.code }}",
  "language": "python"
}
```

**Data Processing:**
```json
{
  "code": "import json; data = {{ $json.data }}; print('Processed:', len(data))",
  "language": "python"
}
```

**File Operations:**
```json
{
  "code": "with open('output.txt', 'w') as f: f.write('{{ $json.content }}'); print('File written')",
  "language": "python"
}
```

## 📁 Project Structure

```
src/
├── index.ts          # Main Express server
├── server.ts         # Docker execution logic
├── utils/
│   └── sse.ts       # Server-Sent Events handling
├── types/            # TypeScript type definitions
├── tools/            # Tool definitions
├── docs/             # Documentation
├── package.json      # Dependencies and scripts
├── tsconfig.json     # TypeScript configuration
├── Dockerfile        # Docker configuration
└── README.md         # This file
```

## 🔍 Troubleshooting

### Common Issues

1. **Docker not running:**
   - Ensure Docker Desktop is running
   - Check that it's in Linux containers mode

2. **Container not found:**
   - Verify `my-llm-sandbox` image exists: `docker images`
   - Rebuild if needed: `docker build -t my-llm-sandbox .`

3. **Permission denied:**
   - Ensure Docker has proper permissions
   - Check Docker socket access

4. **Slow responses:**
   - First request may take 2-3 seconds (container startup)
   - Subsequent requests should be fast (1-2 seconds)

### Debug Mode

Enable detailed logging by checking the server console output for:
- `[STDOUT]` - Docker container output
- `[STDERR]` - Docker container errors
- `Executing code in Docker container...` - Request processing

## 🚀 Deployment

### Docker Deployment

1. **Build the image:**
   ```bash
   docker build -t mcp-executor .
   ```

2. **Run the container:**
   ```bash
   docker run -p 3000:3000 -v /var/run/docker.sock:/var/run/docker.sock mcp-executor
   ```

### Environment Variables

- `PORT` - Server port (default: 3000)
- `NODE_ENV` - Environment (development/production)

## 📝 Examples

### Simple Python Code
```json
{
  "code": "print('Hello, World!')",
  "language": "python"
}
```

### Mathematical Operations
```json
{
  "code": "import math; print(f'Pi: {math.pi}'); print(f'2^10: {2**10}')",
  "language": "python"
}
```

### Data Processing
```json
{
  "code": "data = [1, 2, 3, 4, 5]; print(f'Sum: {sum(data)}'); print(f'Average: {sum(data)/len(data)}')",
  "language": "python"
}
```

### File Operations
```json
{
  "code": "with open('test.txt', 'w') as f: f.write('Hello from Docker!'); print('File created')",
  "language": "python"
}
```

## 🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

## 📄 License

This project is licensed under the ISC License.

## 🆘 Support

For issues and questions:
1. Check the troubleshooting section
2. Review the console logs
3. Test with simple code examples
4. Verify Docker setup

---

**Happy coding! 🎉**