# ivnvxd/mcp-server-odoo architecture

> Architecture diagram of the GitHub repository ivnvxd/mcp-server-odoo, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ivnvxd/mcp-server-odoo
- Repository: https://github.com/ivnvxd/mcp-server-odoo

## Overview

##### Project type and purpose
- This is a self-contained Python full-stack “MCP Server” that exposes Odoo ERP functionality over a Model Context Protocol interface. It’s essentially a microservice: a CLI/HTTP-like server that connects to an external Odoo instance, enforces access control, performs searches and CRUD operations, formats results for LLMs, and returns them to the calling AI assistant or client.

##### File structure
- Top-level:
- mcp_server_odoo/        ← core service package
- pyproject.toml          ← build/config
- .github/ci workflows
- tests/                  ← unit and integration tests
- Inside mcp_server_odoo:
- __main__.py & server.py           ← entrypoint and server loop
- config.py & logging_config.py     ← environment & logging setup
- access_control.py                 ← API key / user‐pass auth
- odoo_connection.py                ← XMLRPC/HTTP connectivity to Odoo
- resources.py & uri_schema.py      ← URI parsing & resource dispatch
- formatters.py                     ← LLM-optimized output formatting
- error_handling.py                 ← exception mapping & responses
- performance.py & tools.py         ← caching, throttling, utility functions

##### README for additional insights
- The README confirms a CLI command (“uvx mcp-server-odoo”) that spawns a service listening for MCP requests.
- It lists the high-level tools (search_records, get_record, etc.) and the required environment variables (ODOO_URL, ODOO_API_KEY, etc.).

##### Main components & their interactions
a. Client / AI assistant
- Initiates requests via the MCP protocol (JSON-RPC or CLI pipes).
b. CLI / Server entrypoint
- __main__.py → server.py: boots the server, reads env vars (config), sets up logging.
c. Access control module
- Validates API key or username/password against Odoo rules.
d. URI Schema & Router
- Parses incoming “odoo://…” URIs or JSON payloads, dispatches to resources.
e. Resource Handlers
- resources.py: implements search, get, create, update, delete operations.
f. Odoo Connection
- odoo_connection.py: manages HTTP/XMLRPC calls to external Odoo instance, handles sessions.
g. Formatting & Response
- formatters.py: post-processes raw Odoo JSON/XML data into hierarchical text for LLMs.
h. Error Handling
- error_handling.py: catches exceptions, maps to MCP error codes/messages.
i. Performance & Utilities
- performance.py: caching, pagination logic
- tools.py: shared helpers
j. External System
- Odoo ERP instance with installed MCP module.

Flow summary:
Client → Entrypoint → AccessControl → Router/URI Schema → Resource Handler → Odoo Connection → Odoo ERP
← Raw data ← Formatting ← ErrorHandling → Response → Client

##### Architectural patterns & design principles
- Modularity: each concern (config, auth, routing, connection, formatting, error handling) is in its own module.
- Layered architecture: transport (CLI/MCP) → authentication → routing → business logic → external system.
- Dependency injection via environment variables (config.py).
- Single responsibility: resources.py only implements high-level operations, odoo_connection.py only manages RPC plumbing.
- Test coverage: conftest and tests ensure each layer is isolated and mockable.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client"
        Client(("Client (AI Assistant / MCP CLI)")):::external
    end

    subgraph "Service Boundary"
        subgraph "Entrypoint & Server"
            Main["__main__.py"]:::entry
            Server["server.py"]:::entry
        end

        subgraph "Configuration & Logging"
            Conf["config.py"]:::config
            Log["logging_config.py"]:::config
        end

        Access["AccessControl"]:::internal
        Router["Router & URI Schema"]:::internal

        subgraph "Business Logic"
            Resources["Resource Handlers<br/>(search_records, get_record, create, update, delete)"]:::internal
            Conn["Odoo Connection"]:::internal

            subgraph "Formatter & Performance Tools"
                Fmt["formatters.py"]:::internal
                Perf["performance.py"]:::internal
                Tools["tools.py"]:::internal
            end

            Err["Error Handling"]:::internal
        end
    end

    ERP[(Odoo ERP Instance)]:::external

    Client --> Main
    Main --> Server
    Server --> Conf
    Server --> Log
    Server --> Access
    Access --> Router
    Router --> Resources
    Resources --> Conn
    Conn --> ERP
    ERP --> Conn
    Conn --> Resources
    Resources --> Fmt
    Fmt --> Err
    Err --> Server
    Server --> Client

    Resources -.->|caching| Perf

    classDef internal fill:#E0F7FA,stroke:#0288D1,color:#01579B;
    classDef config fill:#E8F5E9,stroke:#43A047,color:#1B5E20;
    classDef external fill:#FFF3E0,stroke:#FB8C00,color:#E65100;
    classDef entry fill:#ECEFF1,stroke:#90A4AE,color:#37474F;

    click Main "https://github.com/ivnvxd/mcp-server-odoo/blob/main/mcp_server_odoo/__main__.py"
    click Server "https://github.com/ivnvxd/mcp-server-odoo/blob/main/mcp_server_odoo/server.py"
    click Conf "https://github.com/ivnvxd/mcp-server-odoo/blob/main/mcp_server_odoo/config.py"
    click Log "https://github.com/ivnvxd/mcp-server-odoo/blob/main/mcp_server_odoo/logging_config.py"
    click Access "https://github.com/ivnvxd/mcp-server-odoo/blob/main/mcp_server_odoo/access_control.py"
    click Router "https://github.com/ivnvxd/mcp-server-odoo/blob/main/mcp_server_odoo/uri_schema.py"
    click Resources "https://github.com/ivnvxd/mcp-server-odoo/blob/main/mcp_server_odoo/resources.py"
    click Conn "https://github.com/ivnvxd/mcp-server-odoo/blob/main/mcp_server_odoo/odoo_connection.py"
    click Fmt "https://github.com/ivnvxd/mcp-server-odoo/blob/main/mcp_server_odoo/formatters.py"
    click Err "https://github.com/ivnvxd/mcp-server-odoo/blob/main/mcp_server_odoo/error_handling.py"
    click Perf "https://github.com/ivnvxd/mcp-server-odoo/blob/main/mcp_server_odoo/performance.py"
    click Tools "https://github.com/ivnvxd/mcp-server-odoo/blob/main/mcp_server_odoo/tools.py"
```
