Poe Proxy MCP Server

# OpenAI-Compatible POE API Implementation ## Overview This document summarizes the successful implementation of OpenAI-compatible API support for the POE MCP server, addressing critical gaps identified in the POE API update. ## Implementation Summary ### Phase 1 ✅ COMPLETED (2025-09-25) #### Key Features Implemented 1. **Dual Client Architecture** - Legacy `fastapi_poe` client maintained for backward compatibility - New `PoeOpenAIClient` using official OpenAI SDK - Seamless switching between clients via `use_openai_client` parameter 2. **Function Calling/Tools Support** - Full support for `tools`, `tool_choice`, and `parallel_tool_calls` parameters - Automatic tool execution with results handling - Dynamic tool registration system - Parallel execution of multiple tool calls 3. **Multi-Modal Generation** - `generate_image` tool for image generation (GPT-Image-1) - `generate_video` tool for video generation (Veo-3) - Proper handling with `stream=False` for media bots 4. **Advanced Parameters** - Temperature control (0-2 range) - Max tokens limiting - Top-p nucleus sampling - Custom stop sequences - Stream options support 5. **Token Usage Tracking** - Complete usage statistics in responses - Prompt, completion, and total token counts - Cost estimation capabilities 6. **OpenAI-Standard Error Handling** - Proper error mapping to OpenAI format - Support for all standard error codes - Consistent error responses across both clients ## Architecture ``` ┌─────────────────────────────────────────────────┐ │ MCP Client Request │ └─────────────────┬───────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────┐ │ POE MCP Server (FastMCP) │ │ │ │ ┌──────────────────┐ ┌──────────────────┐ │ │ │ Legacy Tools │ │ Enhanced Tools │ │ │ │ - ask_poe │ │ - ask_poe_v2 │ │ │ │ - ask_with_ │ │ - ask_poe_with_ │ │ │ │ attachment │ │ tools │ │ │ │ - clear_session │ │ - generate_ │ │ │ │ │ │ image/video │ │ │ └──────────────────┘ └──────────────────┘ │ └─────────────┬───────────────┬──────────────────┘ │ │ ▼ ▼ ┌──────────────────┐ ┌──────────────────────┐ │ Legacy Client │ │ OpenAI Client │ │ (fastapi_poe) │ │ (OpenAI SDK) │ └──────────────────┘ └──────────────────────┘ │ │ ▼ ▼ ┌──────────────────────────────────────────────┐ │ POE API Endpoints │ │ │ │ Legacy: fastapi_poe protocol │ │ New: https://api.poe.com/v1 │ └──────────────────────────────────────────────┘ ``` ## Usage Examples ### Basic Query with Advanced Parameters ```python response = await ask_poe_v2( bot="Claude-Opus-4.1", prompt="Explain quantum computing", max_tokens=500, temperature=0.7, top_p=0.9, use_openai_client=True ) ``` ### Function Calling ```python tools = [ { "type": "function", "function": { "name": "search_web", "description": "Search the web", "parameters": { "type": "object", "properties": { "query": {"type": "string"} }, "required": ["query"] } } } ] response = await ask_poe_with_tools( bot="GPT-4.1", prompt="Find information about the latest SpaceX launch", tools=tools, tool_choice="auto", parallel_tool_calls=True ) ``` ### Multi-Modal Generation ```python # Image Generation image = await generate_image( prompt="A futuristic city at sunset", model="GPT-Image-1" ) # Video Generation video = await generate_video( prompt="A drone flyover of mountains", model="Veo-3" ) ``` ## Model Support ### Text Models (with Function Calling) - Claude-Opus-4.1 ✅ - Claude-Sonnet-4 ✅ - Gemini-2.5-Pro ✅ - GPT-4.1 ✅ - Grok-4 ✅ ### Text Models (without Function Calling) - Llama-3.1-405B ✅ ### Media Models - GPT-Image-1 (Image Generation) ✅ - Veo-3 (Video Generation) ✅ ## Testing Comprehensive test suite implemented in `tests/test_openai_client.py`: - ✅ Basic chat completions - ✅ Function calling with tools - ✅ Streaming responses - ✅ Advanced parameters - ✅ Error handling - ✅ Multi-modal generation Run tests: ```bash python tests/test_openai_client.py ``` ## Migration Guide ### From Legacy to OpenAI Client #### Before (Legacy) ```python response = await ask_poe( bot="claude", prompt="Hello world", session_id="123" ) ``` #### After (OpenAI-Compatible) ```python response = await ask_poe_v2( bot="Claude-Opus-4.1", prompt="Hello world", session_id="123", use_openai_client=True, temperature=0.7, max_tokens=1000 ) ``` ## Phase 2 Planning (KIJ-161) ### Upcoming Features - Rate limiting with exponential backoff - Enhanced streaming with `stream_options` - Response format handling - Metrics collection - Health check endpoint ### Timeline - Start: Next sprint - Duration: 2 weeks - Priority: High ## Performance Considerations 1. **API Call Latency** - OpenAI client adds ~50ms overhead - Mitigated by connection pooling - Retry logic adds resilience 2. **Token Usage** - Track usage to optimize costs - Use `max_tokens` to control generation - Monitor with usage statistics 3. **Rate Limiting** - Current limit: 500 RPM - Phase 2 will add automatic handling - Manual backoff recommended for now ## Security Notes 1. **API Key Management** - Single POE API key for both clients - Stored in environment variables - Never logged or exposed 2. **Tool Execution** - Tools are sandboxed - Input validation required - Error handling prevents crashes 3. **Session Management** - Sessions expire after 60 minutes - UUID-based identification - Memory-based storage (consider Redis for production) ## Troubleshooting ### Common Issues 1. **Authentication Errors** - Verify POE_API_KEY is set - Check key validity at https://poe.com/api_key 2. **Model Not Found** - Use exact model names (e.g., "Claude-Opus-4.1" not "claude") - Check `list_available_models_v2()` for valid models 3. **Function Calling Failures** - Ensure model supports tools (check model capabilities) - Validate tool definitions match OpenAI schema - Check tool implementation for errors ## References - [POE API Documentation](https://poe-developers.gitbook.io/documentation/) - [OpenAI API Reference](https://platform.openai.com/docs/api-reference) - [POE_API_GAPS_ANALYSIS.md](../POE_API_GAPS_ANALYSIS.md) - Linear Issues: KIJ-160 (Phase 1), KIJ-161 (Phase 2) ## Contributors - Implementation: David @ Kijko - Review: Perplexity AI Research - Testing: Automated test suite --- Last Updated: 2025-09-25 Version: 1.0.0