Saltar a contenido

Conexión y descubrimiento

Novedades en v1.6.0

odoo_version nombra la copia de odoo-tools que responde (bloque plugin), también con la política bloqueada. Una respuesta sin policy viene de una copia anterior a la 1.5.0, y /odoo-doctor se detiene ahí; en Claude Code también corre la revisión de copias. Ver Identificar el entorno. Si las herramientas de Odoo no están cargadas, /odoo-doctor reconoce el estado not_started de la app como el caso de Cowork y Claude chat, distingue una sesión en la nube y, si falta python3, da la solución para tu sistema. Ver Chequeo de salud.

Novedades en v1.5.1

/odoo-doctor empieza por revisar si las herramientas de Odoo están cargadas donde corre, da consejos del lado de Odoo solo cuando Odoo rechazó la conexión, y siempre termina con un reporte de soporte sin keys, URLs, logins ni datos de registros. Ver Chequeo de salud.

Novedades en v1.5.0

odoo_version devuelve también un bloque policy con la política de permisos en vigor, y /odoo-doctor lo reporta. odoo_list_models deja fuera los modelos en los que la política no permite nada, y odoo_access_check agrega la respuesta de la política junto a la de Odoo. Ver Política de permisos.

Antes de operar contra una instancia nueva, identifica su versión, edición y despliegue. La capa de compatibilidad usa estos datos para resolver nombres de modelos y campos, así que casi nunca necesitas ramificar tus consultas por versión.

1. Identificar el entorno

Llama a odoo_version. Devuelve:

  • version: entero mayor (10-19)
  • raw_version: la cadena de versión completa reportada por Odoo
  • edition: community | enterprise | unknown
  • deployment: onprem | saas
  • transport: el transporte activo: json2 en Odoo saas~18.4 / 19.0+ con una API key; jsonrpc(auto), o jsonrpc / xmlrpc tras un fallback, en los demás casos
  • transport_notice: null, o por qué se usan los endpoints obsoletos /xmlrpc o /jsonrpc en Odoo 19+ y cómo pasar a JSON-2 (por ejemplo, crear una API key y ponerla en las opciones del plugin)
  • policy (desde la v1.5.0): el perfil (profile), el archivo de política (file), el digest, si Read-only mode está activo (readonly), las herramientas ocultas (hidden_tools), las aperturas de modelos sensibles con su razón y caducidad (opened_sensitive), los campos liberados (released_fields), las advertencias (warnings) y, si la política no se pudo cargar, error y error_code. Ver Qué reportan las herramientas.
  • plugin (desde la v1.6.0): la versión de odoo-tools que respondió (version) y, en Claude Code, su copia instalada (copy, plugin@marketplace, por ejemplo odoo-tools@transgenia-odoo-tools), leída del nombre de la carpeta de datos que Claude Code da a cada copia. Con dos copias instaladas, dice cuál corre.

Desde la v1.4.0, odoo_version inicia sesión antes de responder: una API key o contraseña equivocada devuelve un error de autenticación en lugar de pasar como conexión correcta.

Cuando el usuario de Odoo es administrador (base.group_system), policy.warnings trae la advertencia W10: los derechos de acceso de Odoo no acotan nada y la política de permisos es la única capa que acota. Prefiere un usuario dedicado con los menos grupos que funcionen. Si la política está bloqueada, odoo_version responde solo con los bloques plugin y policy y una nota (note) que nombra la opción o el archivo que corregir, sin contactar a Odoo.

Una respuesta sin bloque policy (y sin note) viene de una copia de odoo-tools anterior a la 1.5.0, sin política de permisos; suele ser una segunda copia instalada desde otro lugar. La ruta guiada y /odoo-doctor se detienen ahí, antes de cualquier escritura. Ver Dos copias de odoo-tools.

Solo en Claude Code

Si odoo_version no aparece entre las herramientas, el servidor MCP no está corriendo en esta superficie. En Cowork y Claude chat no corre nunca (ver Dónde funciona); en Claude Code, revisa las opciones del plugin y Solución de problemas. /odoo-doctor empieza por esta revisión.

2. Chequeo de salud con /odoo-doctor

El comando /odoo-doctor hace un diagnóstico completo, sin escribir nada, en este orden, y se detiene en el primer paso que explica el problema:

  1. ¿Están cargadas las herramientas de Odoo? Antes de ejecutar nada, revisa su lista de herramientas. Si odoo_version no está, el servidor MCP no corre en esta sesión, así que no corre comandos de shell ni revisa Python antes de saber dónde usas Claude (en Cowork, los comandos corren en una máquina virtual, no en tu equipo) y no da consejos del lado de Odoo (plan, API key, transporte, base de datos). Lee la línea odoo-tools session diagnostics: que el hook de inicio de sesión escribe desde tu equipo (Cowork corre los hooks del plugin en tu equipo, fuera de la máquina virtual; Claude chat no corre ninguno) y, si no lo sabe, te pregunta dónde usas Claude. Si la app muestra el servidor del plugin con el estado not_started y el motivo user_config_unsupported, sabe que estás en Cowork o Claude chat. En Cowork o Claude chat te dice que las herramientas de Odoo no corren ahí, por diseño de esas apps, y que nada está mal con tu cuenta, tu Odoo ni tu Python; ese estado es lo esperado, no un error, y ninguna actualización lo cambia. Te ofrece una sesión local de la pestaña Code de Claude Desktop o Claude Code, donde el plugin aparece sincronizado con la misma cuenta, y la configuración asistida de Transgenia. En una sesión en la nube (de la pestaña Code, o Claude Code en la web), el plugin puede estar sincronizado, pero sus opciones se quedan en el equipo donde las capturaste, así que el servidor no arranca: no te pide las opciones ahí y te ofrece lo mismo. En Claude Code en tu equipo, el servidor no arrancó. Las causas habituales son la URL, la base de datos o el login vacíos, una segunda copia del plugin o que no exista el comando python3 (en Windows, claude mcp list reporta entonces el servidor como Failed to connect con Connection closed, sin nombrar a Python; en macOS, python3 viene con las Command Line Tools de Apple). Corre la revisión de copias y, para la copia que conserva, la de opciones: leen lo que imprime Claude Code, no contactan nada y nunca muestran la key (ver Dos copias de odoo-tools). Si no encuentra python3 o no imprime una versión, esa es la causa: te da la solución para tu sistema y se detiene. Si no, te muestra las dos salidas tal cual y te lleva al Paso 0b de la ruta guiada. Los comandos que imprime la revisión de copias son para una terminal (PowerShell o Terminal), no para /plugin.
  2. Llama a odoo_version. Primero lee su bloque plugin: la versión de odoo-tools que respondió y su copia (plugin@marketplace). Si la respuesta no trae policy, respondió una copia anterior a la 1.5.0, sin política de permisos: te lo dice, corre la revisión de copias y se detiene ahí. Si no, reporta versión / edición / despliegue / transporte y, si no es null, el transport_notice con su solución. También reporta el bloque policy: el perfil, si hay un archivo de política, el digest, las herramientas ocultas, las aperturas con su razón y caducidad, y cada advertencia; muestra W10 de forma destacada y recomienda un usuario dedicado de mínimo privilegio. Si error tiene valor, la política está bloqueada: te dice que las demás herramientas de Odoo quedan apagadas hasta que corrijas el archivo o las opciones Permission profile / Permission policy file y reconectes (/mcp), y se detiene ahí. Después corre una vez la revisión de copias y agrega su resultado a la tabla: dos copias pueden estar activas mientras la conexión funciona, y entonces el diálogo de opciones y las herramientas pueden ser de copias distintas.
  3. Llama a odoo_connections y lista las sesiones activas.
  4. Hace una lectura acotada de prueba: odoo_search_read { "model": "res.partner", "fields": ["name"], "limit": 1 }. Después llama a odoo_online_profile (solo lectura) y agrega a la tabla la serie (p. ej. saas~19.2 en Odoo Online), qué tan segura es la detección del despliegue (deployment_confidence) y cualquier aviso, como una API key que caduca pronto. Si el despliegue es saas, también los límites de Odoo Online. Solo entonces, si Odoo rechazó la conexión, aplican las revisiones del lado de Odoo: en Odoo Online, el acceso a la API externa necesita un plan Custom; una API key caducada o revocada; el nombre de la base de datos.
  5. Si algún paso falla, indica el error exacto y te dirige a /odoo-tools:odoo-setup-mcp (o odoo-setup-cli). Siempre termina con un reporte de soporte que puedes enviar a Transgenia, sin keys, URLs, logins ni datos de registros: en Claude Code corre --diagnose sobre las carpetas locales del plugin; en Cowork lo escribe a partir del paso 1, y en Claude chat solo nombra la superficie. Ver Soporte.

3. Explorar el esquema

Cada instancia difiere. Antes de consultar campos que no conoces:

  • odoo_list_models: lista los modelos instalados, opcionalmente filtrando por un fragmento de nombre (like). Desde la v1.5.0 deja fuera los modelos en los que la política de permisos no permite nada y dice cuántos son (hidden_by_policy).
  • odoo_fields_get: devuelve las definiciones de campos de un modelo (con caché). Acepta nombres históricos o modernos; la capa de compatibilidad resuelve al correcto.
  • odoo_module_info: estado de instalación y metadatos de un módulo por su nombre técnico (útil para saber si un módulo Enterprise está presente).
  • odoo_access_check: si el usuario conectado puede leer, escribir, crear y borrar en un modelo (por registro con ids en Odoo 18+), y si puede exportar. Útil cuando una llamada se rechaza por permisos. Desde la v1.5.0 devuelve también policy (qué permite la política de permisos) y una nota cuando Odoo permite algo que la política rechaza.
  • odoo_api_catalog: los métodos de un modelo con sus nombres de parámetros en orden, para JSON-2 y odoo_execute.

Todas se describen en la Referencia de herramientas.

Ejemplo: descubrir los campos de contactos

odoo_fields_get {
  "model": "res.partner",
  "attributes": ["string", "type", "required"]
}

4. Elegir la superficie correcta

  • Si usas Claude Code y python3 3.9+ está disponible → servidor MCP (todas las herramientas + compatibilidad; sin dependencias de terceros).
  • Si usas Claude Code sin Python pero con Docker → el servidor MCP en contenedor (/odoo-tools:deploy-local, ver Despliegue local).
  • Si solo tienes Node → CLI de respaldo (ver CLI de respaldo).

Continúa con la Referencia de herramientas.