odoo-pulse: Instructions file for Codex

AGENTS.md

This file provides guidance to AI coding agents when working with code in this repository.

Commands

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests (no live Odoo needed)
pytest

# Run a single test file
pytest tests/unit/core/test_client.py

# Run a single test by name
pytest tests/unit/tools/test_tools_write.py::test_create_record_preview_does_no_write

# Live smoke test against a real Odoo instance (reads only, never writes)
python scripts/smoke/live.py

# Playground: boot a real Odoo in Docker, seed a demo story, assert reports
make playground          # boot + seed (follows the seed logs)
make playground-smoke    # end-to-end: boot, seed, assert reports, tear down
make playground-reset    # wipe the playground (drops the database)

Architecture

This is an MCP server that exposes Odoo's XML-RPC external API as MCP tools. The entry point is src/odoo_pulse/server.py, which calls mcp.registry.load_enabled_modules() to import the tool modules selected by ODOO_TOOL_GROUPS as side effects — each import registers @mcp.tool() (and, for mcp.resources, @mcp.resource()) functions with the shared FastMCP instance.

As of this refactor the package is split into layered subpackages (core, mcp, common, services, tools). All report business logic is consolidated under services/ (report_context.py, pulse.py, crm/, sales/, finance/, hr/, inventory/, operations/, and projects/), while all @mcp.tool() adapters are organized in tools/ (tools/generic.py, tools/writes.py, tools/lists/, tools/reports/).

Module responsibilities:

• src/odoo_pulse/core/ — config, errors, cache, timeout transports, XML-RPC client, write guards
• src/odoo_pulse/mcp/ — FastMCP app, lazy client runtime, JSON result boundary, registry, resource adapter (resources.py)
• src/odoo_pulse/common/ — dates/domains, paging, schema, money, reporting, concurrency; no MCP/global client
• src/odoo_pulse/services/ — pure Python business logic services (record read, write execution, reports, project queries)
• src/odoo_pulse/tools/ — thin decorated adapters (generic.py, writes.py, lists/, reports/)