Odoo Best Practices — AI-powered Odoo Engineering Platform

Static analysis engine + domain knowledge platform + MCP server for Odoo module development. Covers 136 rules, 12 anti-patterns, 6 Odoo versions, and provides 14 MCP tools for AI-assisted code review.

---

Quick Start (5 minutes)

<details> <summary><b>🐍 Python (recommended for full features)</b></summary>

# 1. Clone
git clone https://github.com/FoxPink-dev/odoo-best-practices.git
cd odoo-best-practices

# 2. Run analysis on your Odoo addon (use python3 on Linux, full path on Windows)
python -m analyzer.cli /path/to/your/addon --check

</details>

<details> <summary><b>📦 npm (quick start — config generation)</b></summary>

npx @foxpink-dev/odoo-best-practices init /path/to/your/addon

</details>

Expected output:

Models: 12
Fields: 142
Violations: 3 violations found
  CRITICAL: 1
  HIGH:     1
  MEDIUM:   1
  LOW:      0

If you see output like above, the analyzer is working. You just ran your first Odoo analysis in 5 minutes.

Try with demo data

python -m analyzer.cli tests/fixtures/demo_addon --check --format json

---

GitHub Action Setup

1. Add workflow file

Create .github/workflows/odoo-review.yml:

name: Odoo Review
on:
  pull_request:
    paths:
      - '**.py'
      - '**/__manifest__.py'
      - '**/*.xml'
      - '**/security/*.csv'

jobs:
  analyze:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
      security-events: write
    steps:
      - uses: actions/checkout@v4

      - name: Odoo Static Analysis
        uses: ./.github/actions/odoo-review
        with:
          addon-path: '.'
          fail-on-critical: 'true'
          fail-on-high: 'true'
          baseline: 'true'
          github-token: ${{ secrets.GITHUB_TOKEN }}

      - name: Upload SARIF to Code Scanning
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: odoo-review-results.sarif
          category: odoo-analyzer
        continue-on-error: true

2. PR Results

After running, you will see in the PR:

Feature	Display
PR Comment	Violations table grouped by severity with file:line
Annotations	Inline error/warning markers on each code line
Code Scanning	SARIF upload → GitHub Security tab

┌─────────────────────────────────────────────┐
│  ## Odoo Analysis Report                     │
│  | Severity | Count |                       │
│  |----------|-------|                       │
│  | 🔴 CRITICAL | 1 |                        │
│  | 🟠 HIGH     | 1 |                        │
│  | 🟡 MEDIUM   | 1 |                        │
│  | **Total**   | **3** |                    │
│                                              │
│  ### 🔴 CRITICAL (1)                         │
│  - **`models/sale.py:42`** — search() inside │
│    loop                                      │
│    <sub>rule: `search-inside-loop`</sub>     │
└─────────────────────────────────────────────┘

Tip: On first run against a legacy repo, use generate-baseline: 'true' to baseline existing violations.

Note: PyPI publish is currently skipped (npm-only distribution). See publish-npm.yml for npm CI publish workflow.

---

MCP Server (AI Agent Integration)

Cursor

{
  "mcpServers": {
    "odoo-analyzer": {
      "command": "python",
      "args": ["-m", "analyzer.mcp_server", "/path/to/addon"]
    }
  }
}

Claude Code

{
  "mcpServers": {
    "odoo-analyzer": {
      "command": "python",
      "args": ["-m", "analyzer.mcp_server", "/path/to/addon"]
    }
  }
}

OpenCode

{
  "mcpServers": {
    "odoo-analyzer": {
      "command": "python",
      "args": ["-m", "analyzer.mcp_server", "/path/to/addon"]
    }
  }
}

14 MCP Tools Available

Tool	Description
analyze_module	Full module analysis: models, views, security, dependencies
search_model	Model definition with fields, methods, inheritance
search_view	View definition with inheritance chain
search_action	Action definition with linked views
check_repository	AST rule engine + security audit
explain_model	Rich model explanation with knowledge base
list_models	List all models in repository
list_views	List all views in repository
list_actions	List all actions in repository
repository_summary	High-level repository stats
models_missing_acl	Security audit: models without ACL
inheritance_graph	Model inheritance graph as Mermaid
build_index	Rebuild repository index
list_knowledge_topics	List domain knowledge topics

Example: AI-assisted debugging

User: "Why does sale.order have no ACL?"
→ Agent calls `search_model("sale.order")` + `models_missing_acl`
→ "Model sale.order is defined at models/sale.py:10 but has no ACL entry in security/ir.model.access.csv"

---

CLI Reference

# Full analysis with markdown report
python -m analyzer.cli path/to/addon

# JSON output for CI pipelines
python -m analyzer.cli path/to/addon --format json

# SARIF for GitHub Code Scanning
python -m analyzer.cli path/to/addon --format sarif -o results.sarif

# Quick check (violations only)
python -m analyzer.cli path/to/addon --check

# Check with baseline suppression (legacy repos)
python -m analyzer.cli path/to/addon --check --baseline

# Generate baseline from existing violations
python -m analyzer.cli path/to/addon --baseline

# Build searchable index for AI tools
python -m analyzer.cli path/to/addon --index -o repo_index

# Rule statistics
python -m analyzer.cli path/to/addon --stats

# Inheritance graph (Mermaid format)
python -m analyzer.cli path/to/addon --graph

---

Rule Statistics

python -m analyzer.cli path/to/addon --stats

Output:

Repository: my_addon
  Models: 12
  Fields: 142
  Views:  8
  Actions: 5
  ACLs:   10
  Record Rules: 3

Violations by severity:
  CRITICAL:  2
  HIGH:      7
  MEDIUM:    13
  LOW:       21
  ─────────────────
  Total:     43

Top rules violated:
  orm-no-n-plus-1 (CRITICAL)    → 3 violations
  orm-raw-sql (HIGH)            → 2 violations
  security-acl (CRITICAL)       → 2 violations

---

Confidence Score

Each violation includes a confidence score to help prioritize review:

search-inside-loop
  Severity:   CRITICAL
  Confidence: 98%              ← High accuracy → fix immediately

missing-index
  Severity:   MEDIUM
  Confidence: 60%              ← Possible false positive → review needed

Confidence	Meaning	Action
90-100%	Static analysis certainty	Fix immediately
70-89%	Clear pattern match	Quick review
50-69%	Heuristic-based	Needs verification
< 50%	Low confidence	May ignore

---

Use Cases

1. Code Review Automation

GitHub Action automatically reviews every PR:

# .github/workflows/odoo-review.yml
- name: Odoo Review
  uses: ./.github/actions/odoo-review
  with:
    fail-on-critical: 'true'

2. Legacy Repository Onboarding

# Step 1: Baseline existing violations
python -m analyzer.cli /path/to/legacy/addon --baseline
# → Creates odoo-baseline.json with 387 accepted violations

# Step 2: Only NEW violations are reported from now on
python -m analyzer.cli /path/to/legacy/addon --check --baseline
# → Only 3 new violations remain

3. AI-assisted Development

MCP server enables AI agents to understand your Odoo codebase:

→ "Explain model sale.order"
→ Agent returns: fields, methods, views, inheritance chain, knowledge docs

4. CI Pipeline Quality Gate

# Fail build if CRITICAL or HIGH violations exist
- name: Quality Gate
  run: |
    python -m analyzer.cli . --check --format json -o report.json
    python -m ci_tools/check_gate.py report.json

---

Baseline System

Enables onboarding legacy repositories without being overwhelmed by existing violations.

# Generate baseline
python -m analyzer.cli /path/to/addon --baseline

# Check with baseline
python -m analyzer.cli /path/to/addon --check --baseline

Baseline data is stored as odoo-baseline.json:

{
  "version": 1,
  "addon": "my_addon",
  "timestamp": "2026-06-20T12:00:00Z",
  "total_accepted": 387,
  "accepted": [
    {"rule": "orm-no-n-plus-1", "file": "models/foo.py", "line": 54}
  ]
}

---

Programmatic API

from analyzer import RepositoryStore

store = RepositoryStore("path/to/addon")
store.load()

# Model queries
store.search_model("sale.order")
store.fields_for_model("sale.order")
store.methods_for_model("sale.order")

# Analysis
store.check_code()
store.violations_by_severity("CRITICAL")

# Security audit
store.models_missing_acl()
store.list_acls()

# Graphs
print(store.inheritance_graph_mermaid())

# Summary
print(store.repository_summary())

---

Project Structure

odoo-best-practices/
├── SKILL.md                       # Entry point — rule index + triggers
├── AGENTS.md                      # Full compiled reference (136 rules)
├── README.md                      # This file
├── rules/                         # 136 rule files (13 categories)
├── bad_patterns/                  # 12 anti-pattern detectors
├── knowledge/                     # 12 core model domain files
├── versions/{14,15,16,17,18,19}/ # Version-specific guides
├── docs/                          # 60 official Odoo docs (14-19)
├── analyzer/                      # Python static analysis engine
│   ├── cli.py                     # CLI: 7 sub-commands
│   ├── checker.py                 # AST rule engine (4 checks)
│   ├── constants.py               # Shared severity constants
│   ├── indexer.py                 # Repository index builder
│   ├── reporter.py                # Markdown/JSON/SARIF report generator
│   ├── baseline.py                # Baseline suppression system
│   ├── sarif.py                   # SARIF v2.1.0 output with fix suggestions
│   ├── store.py                   # RepositoryStore (unified API)
│   ├── mcp_server.py              # MCP protocol server (14 tools)
│   ├── graph.py                   # Inheritance + dependency graphs
│   ├── init_generator.py          # Per-IDE config generator (5 IDEs)
│   └── parsers/
│       ├── common.py              # Shared AST helpers (ast_node_to_value)
│       ├── manifest_parser.py     # AST-safe manifest parsing
│       ├── model_parser.py        # Models, fields, methods, decorators
│       ├── view_parser.py         # Views, actions, menus, templates
│       └── security_parser.py     # ACLs, record rules, groups, categories
├── package.json                   # npm package (scoped @foxpink-dev)
├── bin/                           # npm CLI entry point
├── .npmignore
├── .github/
│   ├── workflows/odoo-review.yml  # PR review CI
│   ├── workflows/publish-npm.yml  # npm publish
│   └── actions/odoo-review/       # Docker action for GitHub CI
│       └── entrypoint.py

---

Version Support

Version	Status	Key Features
14	✅ Legacy	Pre-OWL, Classic Widgets
15	✅ Legacy	OWL 1.x introduced
16	✅ Stable	OWL 2.x Default
17	✅ Stable	OWL Required, t-out
18	✅ Current	Legacy JS removed, OWL 3
19	✅ Latest	<list> tag canonical

---

License

MIT

---

Portfolio Note

Built an Odoo Engineering Platform featuring repository intelligence, static analysis, MCP integration, GitHub-native code review, SARIF reporting, baseline suppression, and AI-assisted development workflows for Odoo 14–19.

This project demonstrates:

• AST parsing — Python source code analysis
• Static analysis — Rule engine, pattern detection
• DevSecOps — CI/CD integration, quality gates
• MCP/AI tooling — 14 tools for AI agents
• Rule engine design — 136 rules across 13 categories
• Platform engineering — From CLI to GitHub Action to AI integration