# Contributing to MCP Server for Odoo
Thanks for your interest in contributing! Whether it's a bug report, new feature, documentation improvement, or test coverage — all contributions are welcome.
## Development Setup
### Prerequisites
- Python 3.10 or higher
- [uv](https://docs.astral.sh/uv/) package manager
### Getting Started
1. Fork and clone the repository:
```bash
git clone https://github.com/<your-username>/mcp-server-odoo.git
cd mcp-server-odoo
```
2. Install in development mode:
```bash
uv pip install -e ".[dev]"
```
3. *(Optional)* Create a `.env` file for integration tests:
```env
ODOO_URL=http://localhost:8069
ODOO_USER=admin
ODOO_PASSWORD=admin
ODOO_DB=demo
ODOO_YOLO=true
```
## Running Tests
The project has three test tiers. Unit tests require no external services — integration tests auto-skip when Odoo is unavailable.
```bash
# Unit tests (no Odoo needed)
uv run pytest -m "not yolo and not mcp" --cov
# YOLO integration tests (vanilla Odoo, no MCP module)
uv run pytest -m "yolo" -v
# MCP integration tests (Odoo + MCP module installed)
uv run pytest -m "mcp" -v
# All tests
uv run pytest --cov
# Single test by name
uv run pytest -k "test_search_records" -v
```
## Code Style
The project uses [Ruff](https://docs.astral.sh/ruff/) for formatting and linting, and [ty](https://github.com/astral-sh/ty) for type checking. Run all checks before submitting:
```bash
uv run ruff check . && uv run ruff format --check . && uv run ty check .
```
Key settings:
- **Line length**: 100
- **Lint rules**: E, F, I, N, W, B, Q
- **Python target**: 3.10
To auto-fix formatting: `uv run ruff format .`
## Commit Messages
This project uses [Conventional Commits](https://www.conventionalcommits.org/). Use lowercase, imperative mood, no trailing period.
**Format**: `<type>: <description>`
| Type | Purpose |
|------|---------|
| `feat` | New feature |
| `fix` | Bug fix |
| `refactor` | Code change that neither fixes a bug nor adds a feature |
| `docs` | Documentation only |
| `ci` | CI/CD changes |
| `chore` | Dependency updates, tooling |
**Examples**:
```
feat: add multi-language support via ODOO_LOCALE
fix: handle models without name field in create_record
refactor: rename test markers — integration→mcp, e2e→yolo
```
For non-trivial changes, add a body explaining **why**:
```
fix: use password auth for MCP integration tests in CI
Remove fake ODOO_API_KEY from CI env vars — it caused Access Denied
errors because Odoo rejected the dummy key at the XML-RPC dispatch
level. Tests now use password-only auth which works with
use_api_keys=False.
```
## Pull Request Process
1. **Fork** the repository and create a branch from `dev`
2. **Keep it focused** — one logical change per PR
3. **Add tests** for new functionality
4. **Update** `CHANGELOG.md` under the `[Unreleased]` section using [Keep a Changelog](https://keepachangelog.com/) format
5. **Run checks** locally — CI runs lint, unit tests, and integration tests
6. **Open a PR** targeting the `dev` branch
7. **Describe** what changed and why in the PR description
## Reporting Issues
### Bug Reports
Please include:
- Steps to reproduce the issue
- Expected vs actual behavior
- Odoo version and mode (standard or YOLO)
- MCP server version (`python -m mcp_server_odoo --version`)
- Relevant error messages or logs
### Feature Requests
Describe the use case and motivation. Explain how the feature would benefit users of the MCP server.
## Project Architecture
A quick orientation for navigating the codebase:
```
__main__.py → OdooConfig → OdooMCPServer → OdooConnection → FastMCP
```
| Module | Responsibility |
|--------|---------------|
| `server.py` | Orchestrates startup, registers handlers on FastMCP |
| `config.py` | `OdooConfig` dataclass from env vars, singleton via `get_config()` |
| `odoo_connection.py` | XML-RPC proxies, auth, CRUD convenience methods, caching |
| `tools.py` | MCP tool handlers (search, get, create, update, delete, list) |
| `resources.py` | MCP resource handlers with URI patterns |
| `schemas.py` | Pydantic models for structured tool return types |
| `access_control.py` | Model permission checks |
| `formatters.py` | LLM-friendly hierarchical text output |
| `performance.py` | Connection pooling, record/field caching |
| `error_handling.py` | Centralized error types and handler |
| `error_sanitizer.py` | Strips sensitive data from error messages |
The server operates in two modes: **Standard** (requires the Odoo MCP module with `/mcp/` endpoints) and **YOLO** (connects directly to `/xmlrpc/` endpoints, no module needed).
## License
By contributing, you agree that your contributions will be licensed under the [Mozilla Public License 2.0](LICENSE).
