Magenest Odoo MCP Server

Servidor MCP Magenest Odoo (mgn_mcp_server)

Um módulo Odoo 19 que expõe uma instância Odoo ativa para assistentes de IA e agentes através do Model Context Protocol (MCP). Ele permite que clientes compatíveis com MCP leiam e escrevam registros Odoo usando chamadas de ferramentas orientadas por linguagem natural, aplicando os mesmos controles de acesso e permissões já configurados no Odoo.

• Repositório: MagenestJSC/advanced_mcp_server
• Versão Odoo: 19.0
• Licença: OPL-1
• Autor: Magenest

Visão Geral

O módulo adiciona um gateway JSON-RPC 2.0 (POST /mcp_server) ao Odoo que fala um conjunto pequeno e uniforme de "ferramentas" em vez de expor chamadas ORM/XML-RPC brutas. Cada requisição é executada como um usuário Odoo real, então regras de registro, segurança em nível de campo e acesso a módulos definidos no Odoo são respeitados automaticamente. Além dessa base, o módulo adiciona uma camada dedicada de controle de acesso configurável pelo administrador, OAuth 2.1 para clientes baseados em navegador, limitação de taxa e um log de auditoria de cada chamada.

Principais Recursos

• Superfície unificada de ferramentas — um conjunto pequeno de ferramentas genéricas (describe, get, search, aggregate, me, count, explain, compare, resources para leituras; add, edit, drop, run, attach, pipeline para escritas) cobre modelos Odoo arbitrários em vez de um endpoint por modelo.
• Controle de acesso refinado — sobreposições por módulo (adv.module.access) e por modelo (adv.model.access) decidem quais modelos e operações (leitura/escrita/exclusão/chamadas de método) são acessíveis através do gateway, independentemente das permissões normais do usuário no Odoo.
• Ferramentas personalizadas — administradores podem expor suas próprias ações ir.actions.server como ferramentas MCP de primeira classe (adv.custom.tool), com validação de entrada JSON Schema.
• Dois modos de autenticação
  • Chaves de API — chaves com escopo criadas a partir do assistente padrão de chaves de API do Odoo.
  • OAuth 2.1 — um servidor de autorização integrado (server/oauth/) que suporta os tipos de concessão padrão, PKCE, registro dinâmico de clientes e um endpoint de descoberta, para clientes baseados em navegador e terceiros.
• Controles de segurança e abuso — um interruptor mestre de ativação/desativação, limitação de taxa por usuário e por administrador com janela deslizante (server/rate_limiter.py), limites de tamanho de requisição, lista de permissões de origem CORS e respostas de erro sanitizadas que nunca vazam tracebacks internos (server/sanitizer.py).
• Log de auditoria — cada chamada é registrada em adv.event.log (ator, recurso, operação, payloads de requisição/resposta, erros) com retenção configurável, independente da transação chamadora, para que uma requisição com falha ainda seja registrada.
• Payloads amigáveis para LLM — seleção inteligente de campos (tools/smart_fields.py) e formatadores de texto hierárquicos (tools/formatters.py) reduzem e moldam a saída read/fields_get do Odoo para consumo eficiente de tokens, além de um esquema de URI odoo:// (tools/uri_schema.py) para referenciar campos binários e anexos como recursos MCP.
• Proxy XML-RPC legado — server/rpc_proxy.py conecta clientes XML-RPC através do mesmo pipeline de gateway, auditoria e limitação de taxa.

Arquitetura

mgn_mcp_server/
├── models/         # Access control, OAuth entities, custom tools, audit log, tool_mixin (adv_tool registry)
├── server/         # HTTP gateway, JSON-RPC dispatcher/protocol, auth, rate limiting, sanitizer, audit writer
│   └── oauth/      # OAuth 2.1 authorization server (grants, endpoints, discovery)
├── tools/          # Field selection, output formatting, odoo:// URI helpers
├── views/          # Backend UI for configuration, access control, audit log, API keys, OAuth clients
├── wizard/         # Module picker / bulk action wizards
├── security/       # Access rights and record rules
└── data/           # Default gateway configuration, OAuth maintenance cron

As capacidades de leitura e escrita são implementadas como métodos Python simples marcados com @adv_tool em adv.tool.mixin (veja models/read_tools.py e models/write_tools.py); qualquer módulo que herde este mixin pode contribuir com ferramentas adicionais, que são descobertas automaticamente via varredura MRO — sem registro central para editar.

Ferramentas disponíveis

Ferramenta	Tipo	Propósito
describe	leitura	Listar recursos acessíveis, ou retornar o esquema completo de um modelo
get	leitura	Buscar um único registro por ID, com expansão opcional de relações (depth)
search	leitura	Pesquisar registros via domínio Odoo ou um spec simplificado de chave-valor
aggregate	leitura	Agrupar/pivotar registros por uma ou duas dimensões
me	leitura	Identidade da sessão atual: usuário, fuso horário, empresa, recursos permitidos, escopo OAuth ativo
count	leitura	Contar registros que correspondem a um domínio, sem buscá-los
explain	leitura	Resumo contextual de um registro: campos-chave, chatter recente, estado, anexos
compare	leitura	Comparar dois registros do mesmo modelo, campo por campo
resources	leitura	Listar URIs de recursos odoo:// para campos binários/anexos
add	escrita	Criar um registro (suporta validação dry_run)
edit	escrita	Atualizar campos específicos em um registro existente
drop	escrita	Excluir um registro (relata registros que seriam afetados por cascata)
run	escrita	Chamar um método público do modelo (incluindo message_post para chatter)
attach	escrita	Enviar um arquivo como ir.attachment, retornando uma URI odoo://
pipeline	escrita	Executar múltiplas operações add/edit/drop/run atomicamente, com encadeamento de resultados

Requisitos

• Odoo 19.0
• Dependências Python: authlib>=1.6.12,<1.7.0, defusedxml, packaging
• Dependências de módulos Odoo: base, base_setup, mail, rpc, web

Instalação

1. Copie mgn_mcp_server para o seu caminho addons do Odoo.
2. Instale as dependências Python:

   pip install "authlib>=1.6.12,<1.7.0" defusedxml packaging
   

3. Atualize a lista de aplicativos e instale Magenest Odoo MCP Server a partir do menu de Aplicativos do Odoo.
4. Vá para as configurações do módulo para habilitar o gateway, configurar a limitação de taxa e definir o controle de acesso para os modelos que você deseja expor.

Configuração

Todas as configurações do gateway ficam no registro singleton adv.server.config, editável na tela de Configurações do módulo:

Configuração	Padrão	Descrição
Gateway Habilitado	False	Interruptor mestre para o endpoint /mcp_server
OAuth 2.1	True	Habilita o fluxo de autorização OAuth 2.1 integrado
Limitação de Taxa	False	Habilita a limitação de requisições por usuário
Requisições / Minuto (por usuário)	300	Limite de taxa por usuário quando a limitação está ativa
Requisições de Admin / Minuto	0 (= igual ao regular)	Limite maior para administradores do gateway
Log de Eventos	True	Habilita o log de auditoria em adv.event.log
Retenção de Log (dias)	30	0 = manter para sempre
Limite Padrão de Registros	10	Tamanho de página padrão para search/aggregate
Limite Máximo de Registros	100	Limite máximo de tamanho de página
Máximo de Campos Inteligentes	15	Máximo de campos auto-selecionados por registro na saída amigável para LLM
Máximo de Itens Relacionados	3	Máximo de registros relacionados buscados automaticamente ao expandir relações
Origens Permitidas	(vazio = sem restrições)	Lista separada por vírgulas de Origens de navegador permitidas para CORS

O acesso em nível de modelo é concedido via registros Adv MCP Module Access / Adv MCP Per-Model Permission Override, que decidem quais modelos e operações são acessíveis independentemente das permissões normais de grupo do usuário no Odoo.

Endpoint

Uma vez habilitado, o gateway é acessível em:

POST /mcp_server
POST /mcp_server/rpc

usando envelopes de requisição/resposta JSON-RPC 2.0, autenticados com uma chave de API Odoo ou um token bearer OAuth 2.1 obtido através do servidor de autorização integrado do módulo.

Notas de Segurança

• O gateway está desabilitado por padrão — ele deve ser explicitamente ativado nas configurações.
• Todo acesso ainda passa pelas regras de registro e segurança de campo do próprio Odoo, além da camada de controle de acesso do módulo.
• Erros internos são sanitizados antes de serem retornados aos clientes; apenas exceções Odoo reconhecidas (UserError, AccessError, ValidationError, MissingError) expõem sua mensagem, todo o resto retorna um erro genérico.
• run (chamadas de método) é bloqueado para internos ORM e métodos privados (prefixados com sublinhado), e deve ser explicitamente permitido por modelo.