admin-mcp

Servidor MCP (Model Context Protocol) en Python para operaciones de administración Odoo. Scaffold arquitectónico basado en ApkMCP, con FastMCP y transporte Streamable HTTP.

Incluye búsqueda de clientes conectada: service → resource → tool.

Requisitos

• Python 3.11+

• Para desarrollo con MCP Inspector: Node.js 22.7.5+ y pnpm

Related MCP server: mcp-server-odoo

Instalación

cd AdminMCP
python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e ".[lambda]"

Con uv:

uv sync --all-extras

Configuración

Copia .env.example a .env:

Autenticación (auth-key)

Cada petición HTTP al endpoint MCP debe incluir la cabecera auth-key: Bearer + base64(BASE_URL|API_KEY[|database]).

• BASE_URL: URL HTTPS del servidor Odoo (sin barra final), p. ej. https://mi-empresa.onrender.com

• API_KEY: clave API de un usuario bot de Odoo (scope rpc)

• database (opcional): nombre de la base de datos cuando el servidor tiene varias (X-Odoo-Database)

Generar el valor en local:

# Sin base de datos explícita
pnpm auth-key -- https://mi-empresa.onrender.com|99031c76-d288-41ea-866b-ef656f58e497

# Con base de datos (multi-DB)
pnpm auth-key -- https://mi-empresa.onrender.com|99031c76-d288-41ea-866b-ef656f58e497|mi_db

El servidor decodifica URL, API key y database opcional, y prepara el cliente httpx para llamadas JSON-2 a Odoo (POST /json/2/{modelo}/{metodo}).

Ejecución

python -m app
# o
admin-mcp

Desarrollo con Inspector:

pnpm install
pnpm dev

Inspector usa dev/mcp-inspector.config.json (puerto 8001, distinto de ApkMCP en 8000). Configura el header auth-key en el Inspector antes de invocar tools/resources.

Flujo de pedido (ChatGPT)

Formato abreviado: Pepe, arroz 2, aceite (cliente + productos; sin cantidad → 1 unidad).

Desambiguación: si hay varios clientes o productos, se listan todos con id y el usuario elige por id.

Búsqueda de productos por nombre: add_to_cart(product_search="arroz", quantity=2) — no requiere conocer el product_id de antemano.

ChatGPT impone un límite de ~5000 tokens en el schema total de tools; las descripciones se mantienen breves para que el conector importe todas las tools (incluido catálogo).

Verificar versión en ChatGPT

Tras un despliegue, el usuario puede comprobar qué build está respondiendo:

• Preguntar: "¿Qué versión de AdminMCP tienes?"

• El asistente invoca read_server_info y responde con version, build_id, instructions_revision, tools y prompts.

Cada respuesta de cualquier tool incluye _server.version y _server.build_id.

Superficie MCP

Arquitectura

app/
├── server/          # FastMCP, lifespan, middleware auth-key, DI, instructions
├── clients/         # OdooJson2Client (JSON-2 API oficial)
├── services/        # Lógica reutilizable (sin decoradores MCP)
├── resources/       # @mcp.resource  app://...
├── tools/           # @mcp.tool acciones
│   └── tool_resources/  # read_* espejo de resources
├── prompts/         # @mcp.prompt
├── utils/           # app_key_codec, excepciones
└── cli/             # admin-mcp-auth-key

Registro por imports con efecto lateral en app/server/__init__.py.

Flujo de búsqueda de clientes:

1. AppKeyMiddleware decodifica auth-key → AppContext

2. Resource app://customers o tool read_customers → services/customers.py

Cómo extender

1. Añadir función en app/services/<dominio>.py

2. Exponer @mcp.resource en app/resources/<dominio>.py

3. Espejo read_* en app/tools/tool_resources/<dominio>.py

4. Tools de acción en app/tools/<dominio>.py

5. Registrar módulos en los __init__.py correspondientes

6. Actualizar app/server/instructions.py

Configuración Cursor MCP

{
  "mcpServers": {
    "admin-mcp": {
      "url": "http://127.0.0.1:8001/mcp",
      "headers": {
        "auth-key": "Bearer <base64(BASE_URL|API_KEY[|database])>"
      }
    }
  }
}

Tests

pnpm test
# o
pytest

Despliegue (AWS Lambda)

pnpm deploy

Requiere credenciales AWS y SERVERLESS_ACCESS_KEY. El workflow .github/workflows/main.yml despliega en push a main.

Relación con ApkMCP

AdminMCP replica la arquitectura de ApkMCP (capas, auth-key, Lambda, Inspector) con operaciones admin: clientes, catálogo, carrito y pedidos confirmados.