diff --git a/mcp-gateway/ARCHITECTURE.md b/mcp-gateway/ARCHITECTURE.md deleted file mode 100644 index 3bacc6b..0000000 --- a/mcp-gateway/ARCHITECTURE.md +++ /dev/null @@ -1,336 +0,0 @@ -# MCP Gateway Architecture - -## Before vs After - -### BEFORE (Claude Only) -``` -┌─────────────────┐ -│ Claude.ai │ -└────────┬────────┘ - │ MCP Protocol - ▼ -┌─────────────────────────────────────┐ -│ MCP Gateway (Port 4444) │ -│ - OAuth 2.1 provider │ -│ - Tool aggregation │ -│ - Session management │ -└─────────────────────────────────────┘ - │ - ┌────┴────┬────────┬──────────┐ - ▼ ▼ ▼ ▼ - ERPNext Wave TrueNAS Home Assistant - ERP Finance Storage Automation -``` - -### AFTER (Claude + Open-UI) -``` -┌─────────────────┐ ┌─────────────────┐ -│ Claude.ai │ │ Open-UI │ -└────────┬────────┘ └────────┬────────┘ - │ MCP Protocol │ OpenAI API - │ │ - └───────────────┬───────────┘ - ▼ -┌─────────────────────────────────────────────┐ -│ MCP Gateway (Port 4444) │ -│ ┌─────────────────────────────────────┐ │ -│ │ OAuth 2.1 (for Claude) │ │ -│ │ /oauth/* endpoints │ │ -│ │ /mcp protocol │ │ -│ └─────────────────────────────────────┘ │ -│ ┌─────────────────────────────────────┐ │ -│ │ OpenAI API (for Open-UI) [NEW] │ │ -│ │ /v1/models │ │ -│ │ /v1/chat/completions │ │ -│ │ Bearer token auth │ │ -│ └─────────────────────────────────────┘ │ -└─────────────────────────────────────────────┘ - │ - ┌────┴────┬────────┬──────────┐ - ▼ ▼ ▼ ▼ - ERPNext Wave TrueNAS Home Assistant - ERP Finance Storage Automation -``` - -## New Components Added - -### 1. OpenAI Routes Module -**File**: `gateway-proxy/openai_routes.py` - -```python -async def list_models() # GET /v1/models -async def chat_completions() # POST /v1/chat/completions -async def _get_mcp_tools() # Fetch available tools -async def _stream_response() # Stream responses to client -``` - -### 2. OpenAI Adapter (Optional) -**File**: `openai_adapter.py` - -High-level abstraction for tool conversion and MCP calls: -```python -class OpenAIAdapter: - async def get_mcp_tools() # Get tools from MCP - async def call_mcp_tool() # Execute a tool - def _convert_mcp_tool_to_openai() # Convert schemas - async def chat_completions() # Handle chat requests -``` - -### 3. Gateway Proxy Enhancement -**File**: `gateway-proxy/gateway_proxy.py` (modified) - -```python -# Imports -from openai_routes import chat_completions, list_models - -# Routes -Route("/v1/models", openai_models, methods=["GET"]), -Route("/v1/chat/completions", openai_completions, methods=["POST"]), -``` - -## Request Flow - -### Claude → MCP Gateway → Tools - -``` -1. Claude sends MCP request - ↓ -2. OAuth 2.1 validation - ↓ -3. Handle /mcp endpoint - ↓ -4. Parse MCP protocol - ↓ -5. Route to appropriate MCP backend - ↓ -6. Execute tool - ↓ -7. Return MCP response - ↓ -8. Claude processes result -``` - -### Open-UI → OpenAI API → Tools [NEW] - -``` -1. Open-UI sends OpenAI request (POST /v1/chat/completions) - ├─ Headers: Authorization: Bearer TOKEN - ├─ Body: { model, messages, stream } - ↓ -2. Bearer token validation - ├─ Extract token from Authorization header - ├─ Hash and check against ACCESS_TOKENS - ↓ -3. Parse OpenAI request - ├─ Extract messages - ├─ Determine if stream needed - ↓ -4. Fetch available MCP tools - ├─ Call MCP gateway: tools/list - ├─ Convert to OpenAI format - ↓ -5. Build OpenAI response - ├─ List available tools - ├─ Format as OpenAI compatible - ↓ -6. Return response (or stream) - ├─ If stream=true: SSE format - ├─ If stream=false: JSON response - ↓ -7. Open-UI receives and displays -``` - -## API Compatibility - -### Endpoints -| Endpoint | Client | Protocol | Auth | -|----------|--------|----------|------| -| `/mcp` | Claude | MCP 2.0 | OAuth 2.1 | -| `/v1/models` | Open-UI | OpenAI | Bearer Token | -| `/v1/chat/completions` | Open-UI | OpenAI | Bearer Token | -| `/health` | Any | JSON | None | -| `/status` | Any | JSON | None | - -### Authentication - -**Claude (MCP):** -- Uses OAuth 2.1 -- Token stored in `ACCESS_TOKENS` dictionary -- Hash-based validation - -**Open-UI (OpenAI):** -- Uses Bearer tokens -- Token in `Authorization: Bearer` header -- Same hash-based validation - -### Response Formats - -**Claude (MCP):** -```json -{ - "jsonrpc": "2.0", - "result": { ... }, - "id": 1 -} -``` - -**Open-UI (OpenAI):** -```json -{ - "id": "chatcmpl-...", - "object": "chat.completion", - "created": 1234567890, - "model": "mcp-gateway", - "choices": [{ "message": {...} }], - "usage": {...} -} -``` - -## Streaming Support - -### Open-UI Streaming Format -Server-Sent Events (SSE): -``` -data: {"id":"...", "object":"chat.completion.chunk", "choices":[...]} - -data: [DONE] -``` - -Implemented in `_stream_response()` function. - -## Tool Execution Flow (Future Enhancement) - -Current: **Tools are listed only** -``` -Open-UI asks: "What tools are available?" -Gateway responds: "Here are the tools..." -``` - -Future: **Tools will be executable** -``` -Open-UI asks: "Create invoice for $100" -Gateway: - 1. Intercepts request - 2. Calls tool with parameters - 3. Returns result - 4. Open-UI shows outcome -``` - -To enable, modify `chat_completions()` to: -1. Parse `tool_use` in messages -2. Call `_call_mcp_tool()` -3. Return structured tool responses - -## Security Architecture - -### Token Management -``` -┌─────────────────┐ -│ Bearer Token │ (64-char urlsafe) -└────────┬────────┘ - │ SHA256 hash - ▼ -┌─────────────────┐ -│ Token Hash │ (stored in ACCESS_TOKENS) -└────────┬────────┘ - │ Compared on each request - ▼ -┌─────────────────┐ -│ Request Valid? │ ✅ / ❌ -└─────────────────┘ -``` - -### Multi-Tenant Ready -Each Open-UI instance can have its own token: -```python -ACCESS_TOKENS = { - "hash_of_token_1": {"client": "open-ui-1"}, - "hash_of_token_2": {"client": "open-ui-2"}, - "hash_of_claude": {"client": "claude.ai"} -} -``` - -## Deployment Architecture - -### Single Container -``` -Docker Container -├─ Python runtime -├─ Starlette web framework -├─ gateway_proxy.py -│ ├─ OAuth 2.1 endpoints -│ ├─ MCP routing -│ └─ OpenAI routes (NEW) -├─ openai_routes.py (NEW) -└─ openai_adapter.py (NEW) -``` - -### Multi-Backend -``` -Gateway connects to: -├─ ERPNext (REST API) -├─ Wave Finance (GraphQL) -├─ TrueNAS (REST API) -└─ Home Assistant (REST API) -``` - -Each as separate MCP servers. - -## Performance Considerations - -### Current Limitations -- No response caching -- No rate limiting -- Sequential tool discovery -- Full tool list returned each request - -### Future Optimizations -- Cache tool definitions (5 min TTL) -- Rate limit by token -- Parallel backend queries -- Filter tools by capability -- Batch tool calls - -## Monitoring & Observability - -### Log Lines Added -``` -INFO - OpenAI-compatible endpoints registered at /v1/* -INFO - Bearer token validated -INFO - MCP tools fetched: N tools available -ERROR - Unauthorized access attempt -ERROR - Tool call failed: X -``` - -### Health Checks -```bash -# Gateway health -GET /health - -# Full status -GET /status -``` - -## Future Enhancements - -### Phase 2: Tool Execution -- [ ] Parse tool_use in messages -- [ ] Execute MCP tools -- [ ] Return structured results - -### Phase 3: Advanced Features -- [ ] Function parameter validation -- [ ] Error recovery -- [ ] Async tool execution -- [ ] Caching layer - -### Phase 4: Enterprise Ready -- [ ] Rate limiting -- [ ] Audit logging -- [ ] Metrics/Prometheus -- [ ] Multi-tenancy -- [ ] Custom LLM routing - ---- - -**Summary**: Your MCP Gateway now runs a dual-protocol architecture supporting both Claude's MCP protocol and Open-UI's OpenAI API, all from a single gateway service.