{
  "markdown": "# Brass-Monkey 🐒: Gemini CLI Extension for Odoo\n\n**Status: ✅ Stable**  \n*Verified Compatibility: Odoo v15 through v18+ (Enterprise and Community).*\n\n**Brass-Monkey** is a high-fidelity, secure, and cognitively optimized **Gemini CLI extension** and Model Context Protocol (MCP) bridge for **Odoo**. It enables AI agents to navigate Odoo's complex ERP/CRM architecture, manage multiple instances, and perform highly audited record operations with extreme context-window efficiency.\n\n---\n\n## 🌟 Key Features\n\n- **The \"Breadth vs. Depth\" Search Paradigm:** Uses lightweight paginated searches (`search_records`) for record discovery, and structured detail-fetchers (`get_record` / `get_records`) to build 360-degree interactive \"Record Dashboards\" containing child rows, Chatter threads, and real-time security ACLs.\n- **In-Memory Metadata Caching:** Accelerates default database queries to **0ms metadata latency** by caching model configurations locally and performing parallel, background warming of parent-model schemas.\n- **Hierarchical \"Local Neighborhood\" Navigation:** Exposes Odoo's menus (`get_menu`) as pruned, recursive JSON trees that cleanly map ancestral breadcrumbs, direct children, and immediate folder siblings while pruning out 95% of unrelated system noise.\n- **Self-Healing Action Resolution:** Dynamically inspects Odoo's base tables to auto-resolve action types (`get_action`), supporting window, server, client, and report actions natively with zero parameter crashes.\n- **Layered Credential Security:** API keys are supplied by your host's env-var secret mechanism, or persisted to an AES-256-GCM encrypted local file; when the OS keychain (Windows Credential Vault, macOS Keychain, libsecret) is available it is used automatically as an enhancement.\n- **Audit & Reversibility:** Every write operation captures a \"Before Snapshot\" and logs a mandatory justification to Odoo's `ir.logging` and the record's Chatter.\n- **30 Domain Skills:** Deep functional expertise pre-loaded for Sales, MRP, Finance, HR, and more.\n\n---\n\n## 🚀 Quick Start\n\nBrass-Monkey is **one** stdio MCP server (`node dist/bundle/index.js`) consumed by\nfour surfaces through four thin manifests. Pick the row that matches how your agent\nruns — every surface launches the *identical* server, with **no forked logic per\nplatform**.\n\n| Surface | Install | Config | Skills |\n| :--- | :--- | :--- | :--- |\n| **Gemini CLI** | `gemini extensions install …` (§1) | interactive prompts | ✅ 30 |\n| **Claude Code** | `/plugin install brass-monkey@odoo-actinon` (§3) | install prompts → `ODOO_*` | ✅ 30 |\n| **Claude Desktop** | install `brass-monkey.mcpb` (§4) | install dialog → `ODOO_*` | ✗ tools only |\n| **Antigravity / generic MCP** | standard `mcpServers` config (§6) | `env` block **or** `setup_instance` | ✗ tools only |\n\nThe 30 domain skills ride with the Gemini extension and the Claude Code plugin\n(both carry a `skills/` manifest); the `.mcpb` and raw MCP-config paths deliver the\ntools only (see §4 note).\n\n### 1. Installation\nThe recommended way to install **Brass-Monkey** is using the official Gemini CLI extension command. This will guide you through the interactive setup of your first Odoo instance.\n\n```bash\ngemini extensions install https://github.com/actinon-com/brass-monkey.git\n```\n\n### 2. Configuration\nDuring installation, you will be prompted for:\n- **Odoo Instance URL:** e.g., `https://my-company.odoo.com`\n- **Database Name:** The name of your Odoo database.\n- **Username / Email:** Your login credentials.\n- **API Key / Password:** Your Odoo External API Key (recommended).\n\nYou can update these settings later or add additional instances using:\n\n```bash\n# Update existing default instance\ngemini extensions config brass-monkey\n```\n\nUpgrade to a newer release with:\n\n```bash\ngemini extensions update brass-monkey\n```\n\n### 3. Install on Claude Code (plugin + marketplace)\n\nBrass-Monkey is a self-serve Claude Code plugin. Add the marketplace, then install:\n\n```shell\n/plugin marketplace add actinon-com/brass-monkey\n/plugin install brass-monkey@odoo-actinon\n```\n\nOn install, Claude Code prompts for your Odoo **URL, database, username, and API\nkey** (the key is stored via Claude Code's secure storage). These are injected\ninto the server automatically — no further setup needed. Leave them blank to skip\nstraight to the `setup_instance` tool instead (see Path B below).\n\nUpgrade to a new release with:\n\n```shell\n/plugin update brass-monkey@odoo-actinon\n```\n\nSkills are namespaced under the plugin, e.g. `/brass-monkey:odoo-sales`.\n\n### 4. Install on Claude Desktop (`.mcpb` bundle)\n\nFor non-CLI users, Brass-Monkey also ships as a one-click Claude Desktop bundle\n(`.mcpb`, the successor to the `.dxt` format).\n\n1. Download `brass-monkey.mcpb` from the\n   [latest release](https://github.com/actinon-com/brass-monkey/releases).\n2. Install it — double-click, drag it into the Claude Desktop window, or\n   **Settings → Extensions → Advanced settings → Install Extension…**.\n3. In the install dialog, fill your Odoo **URL, database, username, and API key**\n   (the key is masked and stored in your OS secure storage). Leave the fields\n   blank to configure later via the `setup_instance` tool.\n\nUpgrade by installing a newer `.mcpb` over the old one.\n\n> **Note — skills:** the `.mcpb` bundle delivers the Odoo MCP **tools** only. The\n> 30 domain skills are a Claude Code feature and ship with the plugin (section 3),\n> not the desktop bundle. For the full tools-plus-skills experience, use Claude\n> Code.\n\n### 5. Configuration on Claude Code / generic MCP hosts\n\nThe server is host-agnostic: it never depends on Gemini's interactive prompts. Any\nMCP host can configure it through **either** of two independent paths. (On the\nClaude Code plugin and Claude Desktop bundle above, Path A is wired to the\ninstall-time prompts for you.)\n\n**Path A — host-injected environment variables.** Set the `ODOO_*` variables in your\nhost's server entry; on startup they populate a single default instance (no tool call\nneeded). This is the env-var contract:\n\n| Variable | Required | Description |\n| :--- | :--- | :--- |\n| `ODOO_ALIAS` | No (default `default`) | Alias for the injected instance. |\n| `ODOO_URL` | Yes | Base URL, e.g. `https://my-company.odoo.com`. |\n| `ODOO_DB` | Yes | Odoo database name. |\n| `ODOO_USERNAME` | Yes | Login username or email. |\n| `ODOO_API_KEY` | Yes | Odoo External API Key (recommended) or password. **Sensitive** — inject via your host's secret mechanism; never commit it. |\n\n`ODOO_URL`, `ODOO_DB`, and `ODOO_USERNAME` must all be present for the instance to\nregister; `ODOO_API_KEY` is resolved for the instance named by `ODOO_ALIAS`.\n\n**Path B — the `setup_instance` tool (first-run).** With no env vars set, call\n`setup_instance` from the client. It validates the credentials against Odoo, stores\nthe API key (see **Credential storage** below), and persists non-secret metadata.\nUse it to add further instances alongside an env-injected default, too.\n\nBoth paths work with no Gemini-specific step. The `mcp_config.json` template (§6)\nplus the `ODOO_*` variables is all a raw MCP host needs.\n\n### 6. Install on Antigravity / other MCP hosts (standard config)\n\nAny host that reads a standard MCP `mcpServers` config — **Antigravity**, or the\n`claude mcp add` fallback — launches the very same server. In Antigravity, open the\n`…` menu in the agent panel → **Manage MCP Servers → View raw config** (the raw file\nlives under `~/.gemini/`, e.g. `~/.gemini/config/mcp_config.json`; on Windows\n`~/.gemini/antigravity/mcp_config.json`). Add:\n\n```json\n{\n  \"mcpServers\": {\n    \"brass-monkey-odoo\": {\n      \"command\": \"node\",\n      \"args\": [\"/ABSOLUTE/PATH/TO/brass-monkey/dist/bundle/index.js\"],\n      \"env\": {\n        \"ODOO_URL\": \"https://my-company.odoo.com\",\n        \"ODOO_DB\": \"my-database\",\n        \"ODOO_USERNAME\": \"me@company.com\",\n        \"ODOO_API_KEY\": \"your-odoo-api-key\"\n      }\n    }\n  }\n}\n```\n\nUse an **absolute path** in `args` rather than relying on `cwd`. The `env` block is\n**Path A** (§5) — it populates a default instance on startup. Omit `env` entirely to\nconfigure later via the `setup_instance` tool (**Path B**). The repo-root\n`mcp_config.json` is the same template in `cwd` + relative-args form, for hosts that\nhonor `cwd`.\n\nPrefer the CLI? Claude Code (and any host with an equivalent) can add it in one line:\n\n```shell\nclaude mcp add brass-monkey-odoo \\\n  -e ODOO_URL=https://my-company.odoo.com \\\n  -e ODOO_DB=my-database \\\n  -e ODOO_USERNAME=me@company.com \\\n  -e ODOO_API_KEY=your-odoo-api-key \\\n  -- node /ABSOLUTE/PATH/TO/brass-monkey/dist/bundle/index.js\n```\n\n### ⬆️ Upgrading\n\nEach surface upgrades independently, all to the same server version:\n\n| Platform | Upgrade command |\n| :--- | :--- |\n| **Gemini CLI** | `gemini extensions update brass-monkey` |\n| **Claude Code** | `/plugin update brass-monkey@odoo-actinon` |\n| **Claude Desktop** | Download the newer `brass-monkey.mcpb` from the [latest release](https://github.com/actinon-com/brass-monkey/releases) and install it over the old one. |\n| **Antigravity / generic** | `git pull` your checkout, then `npm run build` to refresh `dist/bundle`. |\n\n---\n\n## 🛠️ Available Tools\n\n| Category | Tool | Description |\n| :--- | :--- | :--- |\n| **Discovery** | `list_models` | Search and list Odoo's technical models with pagination. |\n| | `inspect_model` | Perform a deep architectural audit of any Odoo model's fields, modules, and rules. |\n| | `get_environment` | \"World Map\" orientation — server, user, company, and app context. Recommended first call in a session. |\n| **UX & Navigation** | `get_menu` | Retrieve recursive, pruned JSON trees of menus (hierarchical drilling or semantic search). |\n| | `get_action` | Retrieve Window, Server, Client, or Report Action details with view-mode bindings. |\n| | `get_view` | Retrieve raw XML/definitions for Odoo form, tree, or kanban views. |\n| | `trace_ui_path` | Discover exactly how to reach a model through the UI (Menus → Actions → Views). |\n| **Safe CRUD** | `search_records` | Search Odoo records, returning a lightweight breadcrumbs-envelope and list totals. |\n| | `get_record` | Retrieve a 360-degree detailed dashboard of a single record, including lines and chatter. |\n| | `get_records` | Retrieve deep, multi-line detailed reports for multiple records in batch. |\n| | `create_record` | Create new records in a specified model with mandatory business justification. |\n| | `write_record` | Update existing records with field-level snapshot tracking. |\n| | `unlink_record` | Delete records from Odoo (highly audited). |\n| | `aggregate_records`| Server-side grouping and pivot-style aggregations with custom offset pagination. |\n| **Reports** | `list_reports` | List all available PDF reports (Invoices, Quotations, Packing Slips) for a model. |\n| | `download_report` | Generate and retrieve PDF report data. |\n| | `download_file` | Download any file or attachment from an Odoo database to the local workspace. |\n| **Workspace** | `setup_instance` | Add and authenticate new Odoo environments. |\n| | `list_instances` | List all configured environments. |\n| | `switch_instance` | Change the active environment. |\n| | `remove_instance` | Delete an instance configuration and its stored credentials. |\n| | `get_info` | Retrieve server version and configuration stats. |\n| | `get_audit_log` | Retrieve recent local audit log entries for transparency. |\n\n---\n\n## 💼 Domain Skills Catalog\n\nBrass-Monkey includes specialized guidance for the following Odoo areas:\n\n- **Foundation:** `relations` (Partners), `products`, `inventory`, `security`.\n- **Sales:** `crm`, `sales`, `purchasing`, `website`, `helpdesk`.\n- **Industrial:** `mrp` (Manufacturing), `plm` (Engineering).\n- **Projects:** `projects`, `timesheets`, `field-service`.\n- **Internal Ops:** `finance`, `hr`, `attendance`, `frontdesk`.\n- **Content:** `knowledge`, `documents`, `worksheets`.\n- **Intelligence:** `spreadsheets`, `dashboards`.\n\n---\n\n## 💻 Local Development & Isolated Testing\n\nFor developers working on this extension, you can run isolated tests against your live Odoo database without modifying your stable global installation.\n\n1. Create a local `.env` file in the root of the workspace (ignored by git):\n```env\nODOO_URL=\"https://my-company.odoo.com\"\nODOO_DB=\"my-database\"\nODOO_USERNAME=\"my-email@company.com\"\nODOO_API_KEY=\"my-api-key\"\n```\n\n2. Start the parallel MCP Inspectors using the helper script:\n```bash\n# Start all three inspectors (Production, Development, Python)\n./start-inspectors.sh --all\n\n# Start ONLY your local workspace development inspector (Port 6275, Proxy 6278)\n./start-inspectors.sh --dev\n```\n\n> **Manual / standard MCP config:** the repo-root `mcp_config.json` is a template\n> for hosts that consume a raw MCP server entry. For installing Brass-Monkey on\n> Antigravity or via `claude mcp add`, see **§6** above. Replace the\n> `/ABSOLUTE/PATH/TO/brass-monkey` placeholder with the absolute path to your\n> checkout. All hosts launch the same `node dist/bundle/index.js`.\n\n---\n\n## 🛡️ Security & Privacy\n\n- **Zero Cleartext Policy:** API keys are never stored in your project folder or logged to the console.\n- **Audit Trail:** All AI actions are attributed and logged within Odoo's `ir.logging` and record Chatter.\n- **Production Guard:** Writing to Odoo requires an explicit business `justification`.\n\n### Credential storage\n\nKeys are resolved in this order: **OS keychain → encrypted local file → environment variable.**\n\n- **Environment variable** (`ODOO_API_KEY`) — the primary path for Claude Desktop /\n  Claude Code and any host that manages secrets for you. Nothing is written to disk.\n- **Encrypted local file** — the guaranteed cross-platform baseline for the\n  `setup_instance` path, at `~/.gemini/brass-monkey/credentials.json` (mode `0600`).\n  Values are encrypted with **AES-256-GCM** using a key derived from the current OS\n  user and machine. This is *obfuscation-grade*: it protects against casual disk\n  reads, backups, and file sync, but **not** against an attacker already running as\n  your user (who can re-derive the same key). Legacy plaintext files from older\n  versions are read transparently and re-encrypted on the next save.\n- **OS keychain** (Windows Credential Vault, macOS Keychain, Linux libsecret) — used\n  automatically as a best-effort *enhancement* when the native `keytar` module loads.\n  Because `keytar` is a native binary that cannot be shipped for every OS in a single\n  bundle, it is treated as optional; the encrypted file above is the reliable baseline.\n\nSet `BRASS_MONKEY_NO_KEYCHAIN=1` to skip the native keychain and force the pure-JS\nencrypted-file path (useful on headless CI or in sandboxes).\n\n## 📄 License\n\nThis project is licensed under the MIT License.\n",
  "bytes": 14754,
  "sha": "012fb83096f690347f4f6eece6d896d16517bc1f68307eea452c0e5da02e26fd",
  "repo_slug": "actinon-com/brass-monkey",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_actinon_com_brass_monkey_e1da0586/readme"
}