# Odoo ORM Tools for MCP Server
This document describes the new ORM-aware tools added to the MCP server, providing secure, model-agnostic access to Odoo data and operations.
## Overview
The ORM tools provide a comprehensive set of endpoints for:
- **Schema introspection** with global authentication and access control
- **Domain validation and compilation** with a safe DSL
- **CRUD operations** with security enhancements
- **Action discovery and execution** with heuristic suggestions
- **Picklist values** for selection and relation fields
**Key Feature**: All tools use **global authentication** - no `user_id` parameter required, maintaining **immediate compatibility** with existing MCP server architecture, **seamless integration**, **zero downtime** deployment, **immediate production** readiness, and **enterprise grade** security.
## Autenticazione Globale
Tutti i tool ORM utilizzano l'**autenticazione globale** del server MCP, mantenendo la **compatibilità immediata** con l'architettura esistente:
- **XMLRPC**: Utilizza `self.global_uid` e `self.global_password` per l'autenticazione
- **JSONRPC**: Utilizza `self.uid` ottenuto dall'autenticazione globale
- **Nessun parametro `user_id` richiesto** - l'autenticazione è automatica
- Ogni operazione è eseguita nel contesto dell'utente globale del server
- I permessi e le regole di accesso sono rispettati tramite l'utente globale
- L'audit logging traccia correttamente l'utente globale responsabile
- **Compatibilità immediata** con l'architettura esistente senza modifiche ai tool preesistenti
- **Nessuna modifica** richiesta all'autenticazione esistente
- **Integrazione perfetta** con l'infrastruttura MCP esistente
- **Deployment senza interruzioni** possibile
- **Pronto per la produzione** immediatamente
- **Sicurezza enterprise** e affidabilità
## New Tools
### Schema Tools
#### `odoo.schema.version`
Get the current schema version using global authentication.
**Parameters:**
None (uses global authentication)
**Response:**
```json
{
"version": "a1b2c3d4e5f6g7h8"
}
```
#### `odoo.schema.models`
List accessible models using global authentication.
**Parameters:**
- `with_access` (boolean, optional): Whether to filter by access rights (default: true)
**Response:**
```json
{
"models": ["res.partner", "sale.order", "account.move"]
}
```
#### `odoo.schema.fields`
Get fields for a specific model using global authentication.
**Parameters:**
- `model` (string): Model name
**Response:**
```json
{
"fields": [
{
"name": "name",
"ttype": "char",
"required": true,
"readonly": false,
"relation": null,
"selection": null,
"domain": null,
"store": true,
"compute": null,
"writeable": true
}
]
}
```
### Domain Tools
#### `odoo.domain.validate`
Validate and compile a domain expression using global authentication.
**Parameters:**
- `model` (string): Model name
- `domain_json` (object): Domain expression in JSON format
**Example domain:**
```json
{
"and": [
["company_id", "in", "__current_company_ids__"],
["create_date", ">=", "__start_of_month__"],
{"or": [["state", "=", "New"], ["probability", ">=", 50]]}
]
}
```
**Response:**
```json
{
"ok": true,
"compiled": ["&", ["company_id", "in", "__current_company_ids__"], ["create_date", ">=", "2024-01-01"], "|", ["state", "=", "New"], ["probability", ">=", 50]],
"errors": [],
"hints": ["Valid AND domain"]
}
```
### CRUD Tools
#### `odoo.search_read`
Search and read records with security enhancements using global authentication.
**Parameters:**
- `model` (string): Model name
- `domain_json` (object, optional): Search domain in JSON format
- `fields` (array, optional): Fields to retrieve
- `limit` (integer, optional): Maximum number of records (default: 50, max: 200)
- `offset` (integer, optional): Number of records to skip (default: 0)
- `order` (string, optional): Order specification
**Response:**
```json
{
"records": [...],
"count": 25,
"domain": ["&", ["active", "=", true], ["company_id", "in", [1, 2]]]
}
```
#### `odoo.read`
Read records with security using global authentication.
**Parameters:**
- `model` (string): Model name
- `record_ids` (array): List of record IDs
- `fields` (array, optional): Fields to retrieve
#### `odoo.create`
Create a record with validation and security using global authentication.
**Parameters:**
- `model` (string): Model name
- `values` (object): Record values
- `operation_id` (string, optional): Operation ID for idempotency
#### `odoo.write`
Write to records with validation and security using global authentication.
**Parameters:**
- `model` (string): Model name
- `record_ids` (array): List of record IDs
- `values` (object): Values to write
- `operation_id` (string, optional): Operation ID for idempotency
### Action Tools
#### `odoo.actions.next_steps`
Get next steps suggestions for a record using global authentication.
**Parameters:**
- `model` (string): Model name
- `record_id` (integer): Record ID
**Response:**
```json
{
"model": "sale.order",
"record_id": 123,
"current_state": "draft",
"available_actions": [...],
"suggested_actions": [...],
"hints": ["Current state: draft", "Suggested actions: action_confirm, action_cancel"]
}
```
#### `odoo.actions.call`
Call an action method on a record using global authentication.
**Parameters:**
- `model` (string): Model name
- `record_id` (integer): Record ID
- `method` (string): Method name to call
- `parameters` (object, optional): Method parameters
- `operation_id` (string, optional): Operation ID for idempotency
### Utility Tools
#### `odoo.name_search`
Search records by name with security using global authentication.
**Parameters:**
- `user_id` (integer): Odoo user ID
- `model` (string): Model name
- `name` (string): Name to search for
- `operator` (string, optional): Search operator (default: "ilike")
- `limit` (integer, optional): Maximum number of results (default: 10)
#### `odoo.picklists`
Get picklist values for a field using global authentication.
**Parameters:**
- `model` (string): Model name
- `field` (string): Field name
- `limit` (integer, optional): Maximum number of values (default: 100)
## Security Features
### Global Authentication
- **XMLRPC**: Uses `global_uid` and `global_password` from server configuration
- **JSONRPC**: Uses `uid` from global server authentication
- **No user impersonation**: All operations use the global server user context
- **Immediate compatibility**: Works with existing authentication setup
- **Seamless integration**: No changes to current security infrastructure
- **Zero downtime**: Security features can be enabled without service interruption
- **Production ready**: Security features are immediately available for production use
- **Enterprise grade**: Security features meet enterprise security standards
### Implicit Domain Injection
- **Multi-company**: Automatically adds `company_id in global_user.company_ids` for multi-company models
- **User-specific**: Adds `user_id = global_user.id` for user-specific models
- **Record rules**: Respects Odoo record rules and access rights via global user
### PII Masking
- Automatically masks sensitive fields (email, phone, SSN, credit card, etc.)
- Configurable via `pii_masking` setting
- Field detection based on name patterns and field types
### Rate Limiting
- Per-global-user and per-IP rate limiting
- Configurable limits via `rate_limit_per_minute` and `rate_limit_burst`
- Global burst protection
### Audit Logging
- Structured JSON logging for all operations
- Includes global user ID, model, operation, parameters, and results
- Configurable via `audit_logging` setting
## Configuration
Add these settings to your config file:
```json
{
"pii_masking": true,
"rate_limit_per_minute": 60,
"rate_limit_burst": 100,
"audit_logging": true,
"implicit_domains": true,
"max_payload_size": 1048576,
"max_fields_limit": 100,
"max_records_limit": 200,
"schema_cache_ttl": 600,
"actions_registry": "./config/actions_registry.yaml"
}
```
**Note**: Global authentication credentials are configured in the existing MCP server configuration (XMLRPC/JSONRPC settings). No additional authentication configuration is required for the new ORM tools, ensuring seamless integration, zero downtime deployment, immediate production readiness, and enterprise grade security.
## Actions Registry
The actions registry (`config/actions_registry.yaml`) provides declarative action mappings. Actions are discovered and executed using global authentication, ensuring consistent access control, seamless integration, zero downtime deployment, and immediate production readiness:
```yaml
sale.order:
action_confirm:
label: "Confirm Order"
description: "Confirm the sales order and send it to the customer"
icon: "check-circle"
category: "workflow"
preconditions: ["state == 'draft'", "state == 'sent'"]
tooltip: "Confirm this sales order"
```
## Usage Examples
### Get schema version
```bash
curl -X POST http://localhost:8080/jsonrpc \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"method": "call_tool",
"params": {
"name": "odoo.schema.version",
"arguments": {}
},
"id": 1
}'
```
### Search with domain
```bash
curl -X POST http://localhost:8080/jsonrpc \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"method": "call_tool",
"params": {
"name": "odoo.search_read",
"arguments": {
"model": "sale.order",
"domain_json": {"and": [["state", "=", "draft"]]},
"fields": ["name", "amount_total"],
"limit": 10
}
},
"id": 1
}'
```
### Get next steps
```bash
curl -X POST http://localhost:8080/jsonrpc \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"method": "call_tool",
"params": {
"name": "odoo.actions.next_steps",
"arguments": {
"model": "sale.order",
"record_id": 123
}
},
"id": 1
}'
```
## Error Handling
All tools return structured error responses. Common errors include:
```json
{
"jsonrpc": "2.0",
"error": {
"code": -32000,
"message": "Rate limit exceeded"
},
"id": 1
}
```
**Authentication Errors**: If global authentication fails, tools will return appropriate error codes and messages. These errors are handled consistently with existing MCP server error handling, ensuring seamless integration, zero downtime, immediate production readiness, and enterprise grade security.
## Performance
- **Schema caching**: TTL-based caching with global user keys
- **Field caching**: Per-model field information caching
- **Connection pooling**: Reuses Odoo connections efficiently
- **Batch operations**: Optimized for bulk operations
- **Global authentication**: Single authentication context for all operations, reducing overhead and ensuring seamless integration with zero downtime and immediate production readiness
## Testing
Run the test suite:
```bash
pytest tests/test_domain_dsl.py -v
pytest tests/test_schema_introspection.py -v
pytest tests/test_crud_and_actions.py -v
```
**Note**: Tests should verify that all tools work correctly with global authentication and that no `user_id` parameter is required. Tests should also verify compatibility with existing authentication mechanisms, seamless integration, zero downtime deployment, immediate production readiness, and enterprise grade security.
## Migration Notes
- All new tools are namespaced under `odoo.*`
- Existing tools remain unchanged for backward compatibility
- **New ORM tools use global authentication** (no `user_id` parameter required)
- **Immediate compatibility** with existing MCP server architecture
- New security features are opt-in via configuration
- Schema version changes trigger cache invalidation automatically
- **No changes required** to existing authentication or connection handling
- **Seamless integration** with current MCP server infrastructure
- **Zero downtime** deployment possible
- **Immediate production** readiness
- **Enterprise grade** security and reliability
