[![MseeP.ai Security Assessment Badge](https://mseep.net/pr/anansitrading-poe-proxy-mcp-badge.png)](https://mseep.ai/app/anansitrading-poe-proxy-mcp)

# Enhanced POE MCP Server for Warp.dev

A production-ready Model Context Protocol (MCP) server that integrates POE (Poe.com API) with Warp.dev terminal, enabling AI-powered terminal assistance with context-aware tooling, automated workflows, and real-time streaming capabilities.

## 🚀 Features

### Core Capabilities
- **Multi-Model Support**: Access GPT-4o, Claude 3 Opus/Sonnet, Gemini Pro, Perplexity, and O3 models
- **Warp Terminal Integration**: Deep integration with Warp's context extraction and action execution
- **OpenAI SDK Compatibility**: Drop-in replacement for OpenAI API with POE backend
- **Production-Ready**: Rate limiting, health checks, metrics, and graceful shutdown

### Advanced Features
- **Context-Aware Queries**: Automatically extracts terminal output, selections, CWD, git state
- **Real-Time Streaming**: Server-Sent Events (SSE) with delta content streaming
- **Command Execution**: Safe execution of terminal commands with validation
- **File Operations**: Create and modify files directly from model responses
- **Session Management**: Maintain conversation context across multiple queries
- **Rate Limiting**: Exponential backoff with 500 RPM limit and request queuing
- **Health Monitoring**: Built-in health checks and Prometheus-style metrics

## 📋 Prerequisites

- **Operating System**: Linux (tested on Ubuntu, Zorin OS), macOS, or WSL2 on Windows
- **Python**: Version 3.8 or higher
- **Warp Terminal**: [Download from warp.dev](https://warp.dev/)
- **POE API Key**: Get yours from [poe.com/api_key](https://poe.com/api_key)

## 🔧 Installation

### Step 1: Clone and Setup

```bash
# Clone the repository
git clone https://github.com/Anansitrading/enhanced-poe-mcp.git
cd enhanced-poe-mcp

# Quick installation with script
chmod +x install.sh
./install.sh

# Or manual setup
python3 -m venv venv
source venv/bin/activate  # On Linux/macOS
pip install -e .
```

### Step 2: Configure Environment

Create a `.env` file with your credentials:

```bash
# Required
POE_API_KEY=your_poe_api_key_here

# Optional (with defaults)
OPENAI_API_KEY=your_openai_key  # For OpenAI SDK compatibility
DEBUG_MODE=false
USE_CLAUDE_COMPATIBLE=true
MAX_FILE_SIZE_MB=10
SESSION_EXPIRY_MINUTES=60
RATE_LIMIT_RPM=500
MAX_RETRIES=3
STREAM_BUFFER_SIZE=64
METRICS_ENABLED=true
HEALTH_CHECK_INTERVAL=30
```

### Step 3: Configure in Warp Terminal

#### Option A: Local Installation (Can cause stability issues)

1. **Open Warp MCP Settings**:
   - Navigate to: **Settings → AI → Manage MCP servers**
   - Or press `Ctrl+P` (Linux/Windows) or `Cmd+P` (macOS) and search for "Open MCP Servers"

2. **Add the POE MCP Server**:
   Click the **+ Add** button and paste this configuration:

   ```json
   {
     "enhanced-poe-mcp": {
       "command": "python3",
       "args": ["/home/david/Projects/Kijko/MVP/MVP_Kijko/enhanced-poe-mcp/poe_server_phase2.py"],
       "env": {
         "POE_API_KEY": "your_poe_api_key_here",
         "PYTHONUNBUFFERED": "1",
         "DEBUG_MODE": "false",
         "RATE_LIMIT_RPM": "500"
       }
     }
   }
   ```

   **Important**: Replace `/home/david/Projects/Kijko/MVP/MVP_Kijko/enhanced-poe-mcp` with your actual installation path.

3. **Save and Start**:
   - Click **Save** to add the configuration
   - Click **Start** next to your server entry
   - The server status should show as "Running"

#### Option B: Remote Hosting (Recommended for Stability)

**Warp supports remote MCP servers!** Host your MCP server remotely to avoid local stability issues.

1. **Deploy to Railway.app** (Best free option):
   ```bash
   # Prepare for deployment
   cd enhanced-poe-mcp
   echo "web: python poe_server_phase2.py" > Procfile
   git add .
   git commit -m "Add Procfile for Railway"
   git push origin main
   ```

2. **Configure Railway**:
   - Sign up at [railway.app](https://railway.app)
   - Create new project → Deploy from GitHub
   - Add environment variables in Railway dashboard:
     - `POE_API_KEY`
     - `PORT=8000`
     - Any other config variables

3. **Configure Warp for Remote MCP**:
   ```json
   {
     "enhanced-poe-mcp": {
       "url": "https://your-app.up.railway.app/mcp/stream"
     }
   }
   ```

**Alternative Hosting Options**:
- **Render.com**: Good free tier, easy deployment
- **Google Cloud Run**: Generous free tier, requires Docker
- **Fly.io**: Global deployment, more complex setup
- **Vercel**: ❌ NOT COMPATIBLE - Cannot handle persistent connections, SSE streaming, or long-running tasks

## 🎮 Usage in Warp Terminal

### Specifying POE Models

POE is a marketplace with hundreds of LLMs. You must specify which model to use:

```bash
# Using Claude 3.5 Sonnet
@poe --model claude-3-5-sonnet "Explain quantum computing"

# Using GPT-4o
@poe --model gpt-4o "Write a Python function"

# Using Gemini Pro
@poe --model google-gemini-pro "Analyze this data"
```

**Popular Model Identifiers**:
| Model | Bot Identifier |
|-------|---------------|
| Claude 3.5 Sonnet | `claude-3-5-sonnet` |
| Claude 3 Opus | `claude-3-opus-20240229` |
| GPT-4 Turbo | `gpt-4-turbo` |
| GPT-4o | `gpt-4o` |
| Gemini Pro | `google-gemini-pro` |
| Llama 3 (70B) | `llama-3-70b` |
| Mistral Large | `mistral-large` |
| Perplexity | `perplexity-online` |
| Custom Bots | Use the handle from poe.com/[bot-name] |

### Basic POE Query
```bash
# Ask a simple question with specific model
@poe --model claude-3-5-sonnet What is the fastest way to create a Python virtual environment?

# Expected output:
# Claude will respond with: "Use `python -m venv <directory>` to create a virtual environment. 
# Activate it with `source <directory>/bin/activate` on Linux/macOS..."
```

### Query with File Attachment
```bash
# Review a configuration file with Claude 3.5
@poe --model claude-3-5-sonnet Review this Dockerfile for security issues [attach:./Dockerfile]

# Expected output:
# Claude analyzes the file and provides security recommendations:
# "Found potential issues: 1) Running as root user, 2) No health check defined..."
```

### Context-Aware Query
```bash
# Get help with a recent error (POE sees your terminal output)
@poe --model gpt-4o Why did my git push fail?

# Expected output:
# GPT-4o analyzes recent terminal output and responds:
# "The push failed because the remote has changes not in your local branch. 
# Run `git pull --rebase` first..."
```

### Execute Terminal Commands
```bash
# Let POE execute safe commands using Gemini
@poe --model google-gemini-pro Find all Python files modified today and show their sizes

# Expected output:
# Gemini generates and executes: find . -name "*.py" -mtime 0 -ls
# Shows results directly in terminal
```

### Stream Long Responses
```bash
# Get streaming output for complex tasks with Claude Opus
@poe --model claude-3-opus-20240229 --stream Generate a complete FastAPI application with authentication

# Expected output:
# Claude Opus streams the code generation in real-time, showing each part as it's created
```

### Session Management
```bash
# Clear conversation context
@poe clear session

# Expected output:
# "Session cleared. Starting fresh conversation."
```

### List Available Models
```bash
# See all available AI models
@poe list models

# Expected output:
# Available models:
# - claude-3-opus: Advanced reasoning and analysis
# - gpt-4o: Latest GPT-4 variant
# - gemini-pro: Google's advanced model
# - perplexity: Web-aware responses
```

### Health Check
```bash
# Check server health
@poe health check

# Expected output:
# Server Status: Healthy ✓
# Uptime: 2h 34m
# Active Sessions: 3
# Request Rate: 45 RPM
```

## 🛠️ Advanced Configuration

### Server Variants

The project includes multiple server implementations for different use cases:

| Server File | Description | Use Case |
|------------|-------------|----------|
| `poe_server.py` | Basic MCP server | Simple POE proxy |
| `enhanced_poe_server.py` | Enhanced with Warp actions | Terminal automation |
| `poe_server_v2.py` | SDK-compatible | OpenAI SDK replacement |
| `poe_server_phase2.py` | Production server | Full features + monitoring |

### Running Different Modes

```bash
# Basic server
python poe_server.py

# Enhanced server with Warp integration
python enhanced_poe_server.py

# Production server (recommended)
python poe_server_phase2.py

# SSE mode for web clients
python run_sse_server.py [port]
```

### Environment Variables Reference

| Variable | Description | Default | Required |
|----------|-------------|---------|----------|
| `POE_API_KEY` | Your POE API key | - | ✅ |
| `OPENAI_API_KEY` | OpenAI API key (for SDK mode) | - | ❌ |
| `DEBUG_MODE` | Enable verbose logging | `false` | ❌ |
| `USE_CLAUDE_COMPATIBLE` | Claude thinking protocol | `true` | ❌ |
| `MAX_FILE_SIZE_MB` | Max file upload size | `10` | ❌ |
| `SESSION_EXPIRY_MINUTES` | Session lifetime | `60` | ❌ |
| `RATE_LIMIT_RPM` | Requests per minute limit | `500` | ❌ |
| `MAX_RETRIES` | Retry attempts for failures | `3` | ❌ |
| `STREAM_BUFFER_SIZE` | SSE buffer size (KB) | `64` | ❌ |
| `METRICS_ENABLED` | Enable metrics collection | `true` | ❌ |
| `HEALTH_CHECK_INTERVAL` | Health check interval (seconds) | `30` | ❌ |

## 📊 Monitoring & Metrics

### Health Check Endpoint
```python
# Check server health programmatically
import requests
health = requests.get("http://localhost:8000/health")
print(health.json())
# Output: {"status": "healthy", "uptime": 3600, "active_sessions": 5}
```

### Metrics Endpoint
```python
# Get performance metrics
metrics = requests.get("http://localhost:8000/metrics")
print(metrics.json())
# Output: {"total_requests": 1234, "error_rate": 0.02, "avg_latency_ms": 250}
```

## 🐛 Troubleshooting

### MCP Server Won't Start in Warp

**Issue**: Server fails to start or shows as "Error" in Warp MCP panel

**Solutions**:
1. Verify Python path: `which python3` and update configuration
2. Check file permissions: `chmod +x poe_server_phase2.py`
3. Test manually: `cd /path/to/server && python3 poe_server_phase2.py`
4. Check logs: Look for errors in terminal output

### Authentication Errors

**Issue**: "Invalid API key" or "Authentication failed"

**Solutions**:
1. Verify POE_API_KEY in `.env` file
2. Ensure key is added to Warp MCP config environment
3. Test key at [poe.com/api_key](https://poe.com/api_key)

### Rate Limiting Issues

**Issue**: "Rate limit exceeded" errors

**Solutions**:
1. Increase `RATE_LIMIT_RPM` in configuration
2. Enable request queuing (automatic in Phase 2 server)
3. Implement exponential backoff in client code

### Context Not Working

**Issue**: POE doesn't see terminal output or context

**Solutions**:
1. Use `poe_server_phase2.py` (not basic server)
2. Ensure Warp context permissions are enabled
3. Update to latest Warp version

### Linux-Specific Issues

**Issue**: Permission denied or module not found

**Solutions**:
```bash
# Fix permissions
chmod -R 755 /path/to/enhanced-poe-mcp
chown -R $USER:$USER /path/to/enhanced-poe-mcp

# Install missing Python packages
pip install -r requirements.txt

# Use virtual environment
source venv/bin/activate
```

## 🚀 Remote Deployment Guide (Railway)

### Why Host Remotely?
- Avoids local stability issues
- Always available, even when your machine is off
- Centralized configuration management
- Better for team collaboration

### Step-by-Step Railway Deployment

1. **Prepare Your Project**:
   ```bash
   cd enhanced-poe-mcp
   
   # Create Procfile for Railway
   echo 'web: python poe_server_phase2.py' > Procfile
   
   # Ensure requirements.txt is complete
   pip freeze > requirements.txt
   
   # Create runtime.txt for Python version
   echo "python-3.11.x" > runtime.txt
   
   # Commit changes
   git add .
   git commit -m "Add Railway deployment files"
   git push origin main
   ```

2. **Set Up Railway**:
   - Sign up at [railway.app](https://railway.app) (free with GitHub)
   - Click **"New Project"** → **"Deploy from GitHub repo"**
   - Select your `enhanced-poe-mcp` repository
   - Railway will auto-detect Python and begin deployment

3. **Configure Environment Variables**:
   In Railway dashboard, go to **Variables** tab and add:
   ```
   POE_API_KEY=your_poe_api_key_here
   PORT=8000
   DEBUG_MODE=false
   RATE_LIMIT_RPM=500
   PYTHONUNBUFFERED=1
   ```

4. **Get Your Server URL**:
   - Go to **Settings** tab in Railway
   - Under **Domains**, click **"Generate Domain"**
   - Copy your URL (e.g., `https://your-app.up.railway.app`)

5. **Configure Warp with Remote URL**:
   ```json
   {
     "enhanced-poe-mcp": {
       "url": "https://your-app.up.railway.app/mcp/stream"
     }
   }
   ```

6. **Test the Connection**:
   ```bash
   # Test your remote server
   curl https://your-app.up.railway.app/health
   
   # Should return:
   # {"status": "healthy", "version": "2.0.0"}
   ```

### Monitoring Your Remote Server

- **Logs**: View in Railway dashboard under "Deployments"
- **Metrics**: Check `/metrics` endpoint
- **Health**: Monitor `/health` endpoint
- **Usage**: Railway shows resource consumption in dashboard

## 🌗️ Architecture

```
┌─────────────────┐         ┌──────────────────────────┐
│  Warp Terminal  │ ◄──────►│   POE MCP Server         │
│                 │  MCP     ├──────────────────────────┤
│  - User Input   │  Proto   │ • Request Handler        │
│  - Context      │         │ • Rate Limiter           │
│  - Actions      │         │ • Session Manager        │
└─────────────────┘         │ • Warp Context Handler   │
                            │ • Streaming Engine       │
                            └───────────┬──────────────┘
                                       │
                            ┌───────────▼──────────────┐
                            │      POE API             │
                            │                          │
                            │ • Claude, GPT-4o         │
                            │ • Gemini, Perplexity     │
                            └──────────────────────────┘
```

## 🧪 Testing

```bash
# Run all tests
python run_tests.py

# Run with verbose output
python run_tests.py --verbose

# Test specific components
python -m pytest tests/test_poe_server.py -v
python -m pytest tests/test_rate_limiter.py -v
python -m pytest tests/test_streaming.py -v
```

## 📚 API Documentation

### MCP Tools Reference

| Tool | Description | Parameters |
|------|-------------|------------|
| `ask_poe` | Basic POE query | `prompt`, `model`, `session_id` |
| `ask_with_attachment` | Query with file | `prompt`, `model`, `file_path` |
| `ask_poe_with_warp_context` | Context-aware query | `prompt`, `model`, `warp_context` |
| `stream_poe_to_warp` | Streaming response | `prompt`, `model`, `stream=true` |
| `execute_warp_action` | Run terminal command | `action_type`, `content`, `validate` |
| `clear_session` | Reset conversation | `session_id` |
| `list_available_models` | Get model list | - |
| `health_check` | Server health | - |
| `get_metrics` | Performance stats | - |

## 🤝 Contributing

We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

### Development Setup

```bash
# Clone and setup development environment
git clone https://github.com/Anansitrading/enhanced-poe-mcp.git
cd enhanced-poe-mcp
python3 -m venv venv
source venv/bin/activate
pip install -e ".[dev]"

# Run in development mode
DEBUG_MODE=true python poe_server_phase2.py
```

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- [Poe.com](https://poe.com) for the API access
- [Warp.dev](https://warp.dev) for the amazing terminal
- [FastMCP](https://github.com/jlowin/fastmcp) for the MCP framework
- The open-source community for continuous support

## 📞 Support

- **Issues**: [GitHub Issues](https://github.com/Anansitrading/enhanced-poe-mcp/issues)
- **Discussions**: [GitHub Discussions](https://github.com/Anansitrading/enhanced-poe-mcp/discussions)
- **Documentation**: [Wiki](https://github.com/Anansitrading/enhanced-poe-mcp/wiki)

---

**Note**: This project is not affiliated with Poe.com or Warp.dev. It's an independent integration tool.