MCP Server for Odoo

# 🧪 Testing MCP Server con Postman ## ⚠️ IMPORTANTE: Protocolo Streamable-HTTP con Sesiones El MCP server usa **sesiones** cuando corre con `streamable-http`. Debes seguir este flujo: 1. **Iniciar sesión** → Obtienes un `session_id` 2. **Usar ese `session_id`** en todas las peticiones siguientes 3. **Cerrar sesión** cuando termines (opcional) --- ## 1. � PASO 1: Iniciar Sesión **Método:** `POST` **URL:** `https://mcp.aahightech.com/sse` **Headers:** ``` Content-Type: application/json ``` **Body (JSON):** ```json { "jsonrpc": "2.0", "id": "init-session", "method": "initialize", "params": { "protocolVersion": "2024-11-05", "capabilities": { "roots": { "listChanged": false } }, "clientInfo": { "name": "postman-test", "version": "1.0.0" } } } ``` **Respuesta:** ```json { "jsonrpc": "2.0", "id": "init-session", "result": { "protocolVersion": "2024-11-05", "capabilities": {...}, "serverInfo": { "name": "odoo-mcp-server", "version": "..." }, "_meta": { "sessionId": "dd282ead881e49e09fcede6ad09732b1" // ← GUARDA ESTE ID } } } ``` **🔑 Copia el `sessionId` de la respuesta!** --- ## 2. 📋 PASO 2: Usar la Sesión en las Peticiones Ahora usa el `session_id` en el endpoint `/message`: ### A) Listar Herramientas **Método:** `POST` **URL:** `https://mcp.aahightech.com/message?sessionId=dd282ead881e49e09fcede6ad09732b1` **Headers:** ``` Content-Type: application/json ``` **Body (JSON):** ```json { "jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {} } ``` ### B) Buscar Contactos **Método:** `POST` **URL:** `https://mcp.aahightech.com/message?sessionId=dd282ead881e49e09fcede6ad09732b1` **Headers:** ``` Content-Type: application/json ``` **Body (JSON):** ```json { "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "odoo_search", "arguments": { "model": "res.partner", "domain": [["is_company", "=", true]], "limit": 5 } } } ``` ### C) Leer un Registro **Método:** `POST` **URL:** `https://mcp.aahightech.com/message?sessionId=dd282ead881e49e09fcede6ad09732b1` **Headers:** ``` Content-Type: application/json ``` **Body (JSON):** ```json { "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "odoo_read", "arguments": { "model": "res.partner", "ids": [1], "fields": ["name", "email", "phone", "city"] } } } ``` --- ## 3. � Endpoints Disponibles | Endpoint | Método | Descripción | |----------|--------|-------------| | `/sse` | POST | Iniciar sesión y obtener `sessionId` | | `/message?sessionId=XXX` | POST | Enviar comandos MCP (requiere sesión) | --- ## 4. 📦 Colección de Postman Completa Crea estas peticiones en Postman: ### Paso 1: Initialize Session ``` POST https://mcp.aahightech.com/sse { "jsonrpc": "2.0", "id": "init", "method": "initialize", "params": { "protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": { "name": "postman", "version": "1.0" } } } ``` ### Paso 2: List Tools (usar sessionId de paso 1) ``` POST https://mcp.aahightech.com/message?sessionId={{sessionId}} { "jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {} } ``` ### Paso 3: Search Partners ``` POST https://mcp.aahightech.com/message?sessionId={{sessionId}} { "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "odoo_search", "arguments": { "model": "res.partner", "domain": [], "limit": 10 } } } ``` --- ## 5. 💡 Tips para Postman ### Usar Variables de Entorno 1. Crea una variable de entorno llamada `sessionId` 2. En la respuesta de `/sse`, usa un **Test** para guardarla automáticamente: ```javascript // En la pestaña "Tests" de la petición /sse var response = pm.response.json(); if (response.result && response.result._meta && response.result._meta.sessionId) { pm.environment.set("sessionId", response.result._meta.sessionId); console.log("Session ID guardado: " + response.result._meta.sessionId); } ``` 3. Luego usa `{{sessionId}}` en las URLs de las demás peticiones: ``` https://mcp.aahightech.com/message?sessionId={{sessionId}} ``` --- ## 6. 🐛 Troubleshooting ### Error: "Missing session ID" - ✅ Asegúrate de llamar primero a `/sse` para obtener el `sessionId` - ✅ Incluye `?sessionId=XXX` en la URL de `/message` ### Error: "Session not found" - ✅ La sesión expiró, vuelve a llamar `/sse` - ✅ Verifica que el `sessionId` sea correcto ### Error: "Bad Request" - ✅ Verifica que el JSON esté bien formado - ✅ Verifica que el `method` sea correcto (tools/list, tools/call, etc.) --- ## 7. 📚 Métodos MCP Disponibles | Método | Descripción | |--------|-------------| | `initialize` | Iniciar sesión (solo en `/sse`) | | `tools/list` | Listar herramientas disponibles | | `tools/call` | Ejecutar una herramienta | | `resources/list` | Listar recursos disponibles | | `resources/read` | Leer un recurso | --- ## 8. 🎯 Ejemplo Completo con curl Si prefieres probar con curl: ```bash # 1. Iniciar sesión SESSION_RESPONSE=$(curl -X POST https://mcp.aahightech.com/sse \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": "init", "method": "initialize", "params": { "protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "curl", "version": "1.0"} } }') # Extraer sessionId (requiere jq) SESSION_ID=$(echo $SESSION_RESPONSE | jq -r '.result._meta.sessionId') # 2. Listar tools curl -X POST "https://mcp.aahightech.com/message?sessionId=$SESSION_ID" \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {} }' ``` ## 5. Modelos Comunes de Odoo Aquí están los modelos más usados que puedes probar: | Modelo | Descripción | |--------|-------------| | `res.partner` | Contactos/Clientes | | `sale.order` | Órdenes de Venta | | `product.product` | Productos | | `account.move` | Facturas | | `stock.picking` | Entregas | | `crm.lead` | Oportunidades CRM | | `res.users` | Usuarios | | `hr.employee` | Empleados | ## 6. Colección de Postman Puedes importar esta colección en Postman: ```json { "info": { "name": "MCP Odoo Server", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }, "item": [ { "name": "List Tools", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"method\": \"tools/list\",\n \"params\": {}\n}" }, "url": { "raw": "https://mcp.aahightech.com/mcp/v1/tools/list", "protocol": "https", "host": ["mcp", "aahightech", "com"], "path": ["mcp", "v1", "tools", "list"] } } }, { "name": "Search Partners", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"jsonrpc\": \"2.0\",\n \"id\": 2,\n \"method\": \"tools/call\",\n \"params\": {\n \"name\": \"odoo_search\",\n \"arguments\": {\n \"model\": \"res.partner\",\n \"domain\": [[\"is_company\", \"=\", true]],\n \"limit\": 10\n }\n }\n}" }, "url": { "raw": "https://mcp.aahightech.com/mcp/v1/tools/call", "protocol": "https", "host": ["mcp", "aahightech", "com"], "path": ["mcp", "v1", "tools", "call"] } } } ] } ``` ## 7. Troubleshooting ### Error 404 - Verifica que el contenedor esté corriendo - Verifica la URL y el endpoint - Revisa los logs: `docker-compose logs -f mcp` ### Error 401/403 - Verifica el `ODOO_API_KEY` - Verifica el `ODOO_USER` ### Error de conexión - Asegúrate de que `ODOO_YOLO=read` (no `YOLO_MODE`) - Verifica que el servicio `web` esté corriendo - Verifica la variable `ODOO_URL=http://web:8069` ## 8. Nota sobre el Protocolo MCP El Model Context Protocol usa JSON-RPC 2.0, por eso todas las peticiones tienen este formato: ```json { "jsonrpc": "2.0", // Versión del protocolo "id": 1, // ID único de la petición "method": "...", // Método a llamar "params": {...} // Parámetros del método } ``` Y las respuestas: ```json { "jsonrpc": "2.0", "id": 1, "result": {...} // Resultado exitoso } ``` O en caso de error: ```json { "jsonrpc": "2.0", "id": 1, "error": { "code": -32600, "message": "Error description" } } ```