odoosh-mcp-server 0.1.4__tar.gz

odoosh_mcp_server-0.1.4/.gitignore

@@ -0,0 +1,11 @@
+__pycache__/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+htmlcov/
+coverage.xml
+.coverage
+*.egg-info/
+dist/
+build/
+.venv/

odoosh_mcp_server-0.1.4/CHANGELOG.md

@@ -0,0 +1,86 @@
+# Changelog
+
+All notable changes to this project are documented here.
+Format loosely follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## [Unreleased]
+
+## [0.1.4] - 2026-09-08
+
+First release published to PyPI, and the first under the distribution name
+**`odoosh-mcp-server`**.
+
+### Changed
+
+- The published name is now `odoosh-mcp-server`. PyPI refused `odoosh-mcp` with
+  `400 The name 'odoosh-mcp' is too similar to an existing project`: it compares names with
+  every separator removed, and `odoo-sh-mcp` -- an unrelated tool that reads ORM metadata over
+  XML-RPC, published since April 2026 -- collapses to the same string. TestPyPI accepted all
+  four earlier uploads because it is a separate index with its own namespace, so no amount of
+  testing there could have surfaced this. The importable module (`odoosh_mcp`) and the command
+  (`odoosh-mcp`) are unchanged; only what follows `pip install` differs.
+
+## [0.1.3] - 2026-09-08
+
+Published to TestPyPI only, as `odoosh-mcp`, and superseded by 0.1.4.
+
+Every fix below was found by installing a TestPyPI build into an empty virtualenv and using it
+against a live odoo.sh project, rather than by the test suite.
+
+### Fixed
+
+- `auth login --from-browser` now finds the session in any browser profile, not only the
+  default one. `browser_cookie3` opens a single profile -- Chrome's `Default`, Firefox's
+  default-marked one -- and a browser with several profiles is ordinary. Observed live: Chrome's
+  `Default` store had last been written four months earlier and held nothing for odoo.sh while
+  `Profile 1` held the live session, so a user who was logged in was told to log in. Each
+  browser is now tried the library's way first, then once per profile store found on disk, most
+  recently written first.
+
+## [0.1.2] - 2026-09-08
+
+Published to TestPyPI only, and superseded by 0.1.3.
+
+### Fixed
+
+- The MCP handshake reported the SDK's version instead of this package's. FastMCP takes no
+  `version` and forwards none to the low-level server, so `serverInfo` answered `1.30.0` -- a
+  number that moved when the SDK was upgraded and never when this server changed. A client
+  asking which odoosh-mcp it is talking to now gets the package version.
+
+## [0.1.1] - 2026-09-08
+
+Published to TestPyPI only, and superseded by 0.1.2.
+
+### Fixed
+
+- `auth login --from-browser` no longer fails on a machine that has more than one browser
+  installed. `--browser auto` used `browser_cookie3.load()`, which walks every known browser and
+  aborts the whole call on the first unusable store, so an unreadable store hid a perfectly
+  readable one (observed live: `TypeError: expected str, bytes or os.PathLike object, not
+  NoneType`, while Chrome and Firefox were both readable on their own). Each supported store is
+  now tried in turn, and the error distinguishes "no store could be read" (paste `--session-id`)
+  from "a store was read and holds no odoo.sh cookie" (log in first).
+
+## [0.1.0] - 2026-09-06
+
+First published release.
+
+### Added
+
+- Repository scaffold, package layout, and v0.0 design spec
+  (`docs/superpowers/specs/2026-09-04-odoosh-mcp-v0-design.md`).
+- Full v0.0 implementation: profile/auth management, HTTP client (control+worker planes), SSH
+  wrapper, 52 MCP tools covering projects, branches/stagings, builds, backups, collaborators,
+  submodules, code profiling, logs, and SSH-only operations (restart, raw logs, SQL), and a
+  `odoosh-mcp` CLI (`profile`, `auth`, `serve`, `run`) sharing the server's permission gate.
+- Write confirmation via three verified strategies (audited, re-verified, SSH-evidenced) — see
+  docs/03-spikes.md §7.
+- Opt-in integration test suite against a live odoo.sh project.
+- Embedded authentication (v0.1): `auth login --from-browser` imports the odoo.sh `session_id`
+  cookie from Chrome or Firefox (optional `browser` extra), `auth status` reports session health,
+  age, provenance and whether odoo.sh's GitHub grant covers the repository routes, and
+  `authorize_github` turns odoo.sh's `InsufficientScopeError` into a one-command fix. Auth failures
+  now carry a machine-readable `remediation` object naming the action that resolves them.
+- Authorization management from the CLI: `profile scope` and `profile permissions`, so the two
+  controls the safety model rests on are no longer hand-edited JSON.

odoosh_mcp_server-0.1.4/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hugo Adan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

odoosh_mcp_server-0.1.4/PKG-INFO

@@ -0,0 +1,292 @@
+Metadata-Version: 2.5
+Name: odoosh-mcp-server
+Version: 0.1.4
+Summary: MCP server to administer odoo.sh projects agentically — stagings, backups, settings, builds, logs, SSH
+Project-URL: Homepage, https://git.vauxoo.com/hugho-ad/odoo-sh-mcp
+Project-URL: Repository, https://git.vauxoo.com/hugho-ad/odoo-sh-mcp
+Project-URL: Documentation, https://git.vauxoo.com/hugho-ad/odoo-sh-mcp/-/blob/main/README.md
+Project-URL: Issue Tracker, https://git.vauxoo.com/hugho-ad/odoo-sh-mcp/-/issues
+Author-email: Hugo Adan <hugo@vauxoo.com>
+Maintainer-email: Hugo Adan <hugo@vauxoo.com>
+License: MIT
+License-File: LICENSE
+Keywords: agentic,ai,ai-tools,claude,claude-desktop,cursor,erp,json-rpc,llm,mcp,mcp-server,model-context-protocol,odoo,odoo-mcp,odoo-sh,odoosh,ssh,vscode
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Internet
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.10
+Requires-Dist: click>=8.0.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp[cli]<2.0.0,>=1.0.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: browser
+Requires-Dist: browser-cookie3>=0.19.1; extra == 'browser'
+Provides-Extra: dev
+Requires-Dist: build>=1.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.30.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: python-dotenv>=1.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Requires-Dist: twine>=5.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# odoosh-mcp
+
+MCP server to administer [odoo.sh](https://www.odoo.sh) projects agentically: create stagings,
+download backups, manage settings/collaborators/submodules, run code profiling (flamegraphs),
+read metadata (production DB size, worker count, staging slots), consume audit logs, manage
+builds, tail logs, and reach the SSH-only operations (restart, raw logs, SQL) — all through one
+permission-gated tool surface, inspired by the structure of
+[odoo-mcp-multi](https://git.vauxoo.com/nhomar/mcp.odoo).
+
+> **Status:** v0.0 in active development. See
+> `docs/superpowers/specs/2026-09-04-odoosh-mcp-v0-design.md` for the full design and
+> `docs/superpowers/plans/` for the task-by-task implementation plan.
+
+## Why this exists
+
+The odoo.sh web UI has no public API. Every route this server calls was reverse-engineered from
+the platform's own OWL frontend bundle and verified live against a disposable trial project. Full
+methodology and the 58-route catalog live in `docs/00-discovery.md` and `docs/01-api-surface.md`.
+
+Three facts shape the whole design (details in `docs/02-write-operations.md` and
+`docs/03-spikes.md`):
+
+1. **Two HTTP planes, two credentials** — the control plane (`www.odoo.sh/app/*`, cookie auth)
+   and the worker plane (`<build.worker_url>/paas/*`, per-project access-token auth) do not share
+   credentials.
+2. **Writes lie about success, and there is no single way to confirm one.** A write can return
+   HTTP 200 with a `null` body while the change never applied — but live spikes proved the audit
+   log does not cover every route either (docs/03-spikes.md §7). This server uses three
+   confirmation strategies, matched per operation family: settings and branch-lifecycle writes
+   are confirmed against `audit_logs` growth; backup, submodule, profiler and collaborator writes
+   are re-verified by re-reading the affected resource's own listing (the project's `backups`,
+   `get_settings().submodules`, `flamegraph/list`, `get_settings().users`) — for submodules and
+   the profiler because live spikes proved there is no audit trace, for backups because the
+   listing is direct evidence the dump exists, and for collaborators because audit coverage was
+   never verified either way and an unverified assumption is not a confirmation; SSH-plane
+   operations (`restart_build`, `tail_log`, `search_log`, `run_sql`, `ssh_exec`) can only be
+   confirmed by the SSH command's own stdout and exit code, since `audit_logs` records nothing
+   more specific than "a shell was opened."
+
+   **A write that its strategy could not confirm is returned as `success: false`**, with the
+   evidence gathered so far under `data`. An unconfirmed write did not happen, whatever the HTTP
+   200 said, so it is never reported as a success with a flag buried inside it.
+3. **Restart and raw log tailing have no HTTP route; SQL needs no special access route either.**
+   odoo.sh's own UI tells you to run `odoosh-restart` in the webshell for the former. For SQL,
+   `odoosh-sql-access` turned out to be for external BI-tool access on dedicated servers only
+   (docs/03-spikes.md §4) — the build's own shell already exports `PGDATABASE`/`PGUSER`/
+   `PGPASSWORD`/`PGHOST`, so `run_sql` simply runs `psql -c "<sql>"` over the same SSH session on
+   any project tier.
+
+## Safety model
+
+- **`write_scope`** — each profile carries an allow-list of project names it is permitted to
+  write to (see `odoosh_mcp/config.py`). A write against a project outside that scope fails
+  before any HTTP request is made.
+- **Risk tiers** — every tool is registered in `TOOL_REGISTRY` with one of `read`, `write_safe`
+  (reversible, no side effect outside the project), `write_external` (touches something outside
+  odoo.sh itself, e.g. GitHub, a subscription, another person's access), `destructive`
+  (irreversible), or `ssh_exec` (unrestricted shell access). See the tool catalog below for each
+  tool's tier.
+- **`confirm=True`** — every `write_external`, `destructive`, and `ssh_exec` tool refuses to run
+  without an explicit `confirm=True` parameter; omitting it always fails safely with no side
+  effect. `run_sql` is the one exception worth calling out: it is registered `write_safe` (opening
+  a psql session on a build is a write-tier capability, and both paths are `write_scope`-gated),
+  it defaults to read-only by running psql with `PGOPTIONS=-c default_transaction_read_only=on`
+  so the *connection* is read-only, and it only requires `confirm=True` when called with
+  `read_only=False`. That guard is best-effort, not a sandbox — SQL that resets the GUC itself
+  escapes it, which is exactly why the tool is scope-gated as well.
+- **Account-level tools take no `project`, so `write_scope` cannot restrain them.** `add_ssh_key`
+  is therefore `write_external` and requires `confirm=True`: the key it registers grants SSH on
+  the build of every project the account can reach, including projects deliberately left out of
+  the profile's `write_scope`, and the grant outlives the session.
+- **Nothing here is anonymous.** Every action taken through this server is also audited on
+  odoo.sh itself under the human account that owns the configured `session_id` cookie — an agent
+  operating this MCP signs with that person's name on the platform's own audit log
+  (docs/03-spikes.md §6), whether or not that particular write happens to show up in
+  `get_audit_logs`.
+
+`write_scope` and `permissions` are managed with `odoosh-mcp profile scope` and
+`odoosh-mcp profile permissions`; run either with no flags to see the current value. Clearing a
+scope grants writes on every project the session can reach, so it requires an explicit `--yes`.
+
+## Installation
+
+```bash
+pip install odoosh-mcp-server
+```
+
+The distribution is `odoosh-mcp-server`; the command it installs is `odoosh-mcp`, and the
+importable module is `odoosh_mcp`. PyPI already hosts an unrelated `odoo-sh-mcp` -- a different
+tool, which reads ORM metadata over XML-RPC rather than administering the platform -- and PyPI
+treats the two names as the same once separators are stripped, so this one carries the suffix.
+
+Importing the session cookie from a local browser needs one extra dependency, declared as the
+optional `browser` extra:
+
+```bash
+pip install "odoosh-mcp-server[browser]"
+```
+
+Everything else works without it. To install an unreleased revision instead:
+
+```bash
+pip install "git+ssh://git@git.vauxoo.com/hugho-ad/odoo-sh-mcp.git@main"
+```
+
+## Configuration
+
+```bash
+odoosh-mcp profile add --name my-account --session-id <paste from the browser cookie>
+odoosh-mcp auth login --profile my-account --from-browser   # needs the browser extra
+odoosh-mcp auth status --profile my-account
+```
+
+odoo.sh issues no API token: signing in is GitHub OAuth against odoo.sh's own OAuth application,
+and the credential it produces is a session cookie. The callback lands on odoo.sh rather than on a
+port this server could listen on, so there is no way for the server to run the login itself. What
+it can do is read that one cookie back from the browser that already holds it (`--from-browser`
+reads only the `session_id` cookie, only for the odoo.sh host), and tell you when it has gone
+stale.
+
+`auth status` reports whether the session is alive, how old it is, where it came from, and whether
+odoo.sh's GitHub grant covers the repository routes. It never prints the cookie — only a
+six-character fingerprint, which is enough to confirm that a re-login actually replaced it.
+
+Profiles are stored in `~/.config/odoosh-mcp/profiles.json` (directory mode 700, file mode 600).
+
+### When a tool answers with a remediation
+
+An expired session and an insufficient GitHub grant both come back as an ordinary error envelope
+carrying a `remediation` object that names the fix:
+
+```json
+{"success": false, "error": "The token does not provide the required scope ...",
+ "route": "/app/branch/5118230/fork",
+ "remediation": {"action": "authorize_github",
+                 "url": "https://github.com/login/oauth/authorize?...",
+                 "scopes": ["read:user", "user:email", "repo"],
+                 "hint": "call authorize_github, then retry"}}
+```
+
+`create_staging`, `merge_branch` and `add_submodule` need GitHub scopes that a plain odoo.sh login
+does not request, and the scope set differs per route, so the URL always comes from odoo.sh's own
+error rather than from a constant in this package. Run:
+
+```bash
+odoosh-mcp auth authorize-github --profile my-account
+```
+
+It prints the scopes odoo.sh is asking GitHub for, opens the authorization page after you confirm,
+and then polls until the grant lands. The MCP tool of the same name never opens a browser unless
+it is called with `open_browser=true` — an agent gets the URL to hand to a human, not control of
+somebody's desktop.
+
+## Usage
+
+As an MCP server (stdio):
+
+```bash
+odoosh-mcp serve
+```
+
+From the command line directly:
+
+```bash
+odoosh-mcp run get_project --param project=my-project
+odoosh-mcp run list_branches --param project=my-project --json
+```
+
+## Tool catalog
+
+Generated from `TOOL_REGISTRY` by `scripts/render_tool_catalog.py` — re-run that script and paste
+its output here whenever a tool is added, renamed, or has its tier/confirm gate changed, so this
+table cannot drift from what the server actually registers.
+
+One side effect worth knowing before calling `download_backup` on a storage-constrained project:
+triggering a dump also leaves a `manual` backup entry on odoo.sh (observed live 2026-09-05), which
+counts against storage until it expires on its own — there is no route to delete it.
+
+| Tool | Tier | Confirm | Description |
+|---|---|---|---|
+| `add_collaborator` | write_external | yes | Invite GitHub user `github_username` to the project at `access_level`. Requires confirm=True. |
+| `add_ssh_key` | write_external | yes | Register `public_key` as an SSH key on the account. Requires confirm=True. |
+| `add_submodule` | write_external | yes | Add submodule `submodule_url` (branch `submodule_branch`) at `path` on `branch_id`. Requires confirm=True. |
+| `auth_status` | read | no | Report whether this profile can talk to odoo.sh right now, and with what authority. |
+| `authorize_github` | read | no | Check odoo.sh's GitHub grant and return the URL that widens it when it is insufficient. |
+| `check_auth` | always_allowed | no | Verify the profile's session_id cookie is still live against odoo.sh. |
+| `clean_flamegraphs` | destructive | yes | Delete every captured flamegraph file for `build_id`. Requires confirm=True. |
+| `create_backup` | write_safe | no | Trigger a manual backup of `branch`'s current build and wait for it to appear. |
+| `create_staging` | write_external | yes | Fork `from_branch` into a new branch `name` at the given `stage`. Requires confirm=True. |
+| `create_submodule_deploy_key` | write_safe | no | Create a deploy key for `submodule_url` so the project's repo can pull that private submodule. |
+| `delete_branch` | destructive | yes | Permanently delete `branch_id` from the project. Requires confirm=True. |
+| `delete_ssh_key` | destructive | yes | Remove SSH key `key_id` from the account. Requires confirm=True. |
+| `delete_submodule_deploy_key` | destructive | yes | Delete submodule deploy key `submodule_id` (from `create_submodule_deploy_key`'s `key.id`). |
+| `dismiss_notification` | write_safe | no | Dismiss notification `notification_id` on the project. |
+| `download_backup` | write_safe | no | Trigger a downloadable dump of `branch`'s build and save it to `dest_dir`. |
+| `download_flamegraph` | read | no | Download flamegraph `name` (from `list_flamegraphs`) for `build_id` into `dest_dir`. |
+| `get_account_profile` | read | no | Fetch the odoo.sh account profile (name, SSH keys on file, etc.) for the signed-in user. |
+| `get_audit_logs` | read | no | List the project's audit log, newest entries first, capped at `limit`. |
+| `get_branch` | read | no | Fetch one branch's record by id, looked up from the full `list_branches` listing. |
+| `get_branch_history` | read | no | Fetch a branch's build/commit history. |
+| `get_branch_settings` | read | no | Fetch a branch's settings as odoo.sh reports them right now. |
+| `get_build` | read | no | Fetch one build's record plus its install/runtime errors, by id. |
+| `get_monitoring` | read | no | Uptime/status plus the URL of odoo.sh's own HTML monitoring page. |
+| `get_project` | read | no | Fetch one project's identity plus storage/worker/staging-slot metadata. |
+| `get_project_settings` | read | no | Fetch the project's full settings dict, including its `repository`, `submodules` and `users` sections. |
+| `get_project_status` | read | no | Fetch the project's current status (the data odoo.sh's own status/monitoring page reads). |
+| `import_github_ssh_keys` | write_safe | no | Import the account's GitHub-registered SSH public keys into odoo.sh. |
+| `list_available_profiles` | always_allowed | no | List the profiles configured locally via `odoosh-mcp profile add` (names and settings only). |
+| `list_backups` | read | no | List the project's backups (daily, remote, manual, update, restore, import, upgrade, other). |
+| `list_branches` | read | no | List the project's branches, optionally filtered to one stage (production/staging/dev). |
+| `list_builds` | read | no | List builds grouped per branch, optionally filtered to one branch, newest builds first. |
+| `list_collaborators` | read | no | List the project's GitHub-linked collaborators, from `get_settings().users`. |
+| `list_database_users` | read | no | List the Odoo database users on `branch_build_id`'s own database (worker-plane HTTP). |
+| `list_flamegraphs` | read | no | List the flamegraph files already captured on `build_id` (worker-plane HTTP). |
+| `list_logs` | read | no | List the log files available on `branch`'s current build (worker-plane HTTP, no SSH). |
+| `list_notifications` | read | no | List the project's current notifications (e.g. "Database dump ready" download prompts). |
+| `list_projects` | read | no | List every project (repo) visible to this account. |
+| `list_submodules` | read | no | List the project's submodules and their deploy keys, from `get_settings().submodules`. |
+| `merge_branch` | write_external | yes | Merge `source_branch_id` into `target_branch` (optionally rebasing). Requires confirm=True. |
+| `rebuild_branch` | write_safe | no | Trigger a fresh build of `branch_id` from its current commit. |
+| `restart_build` | write_external | yes | Restart `service` ("http" or "cron") on `branch`'s build via `odoosh-restart` over SSH. Requires confirm=True. |
+| `restore_backup` | destructive | yes | Restore `target_branch_id` (production or staging only) to a prior backup. Requires confirm=True. |
+| `revoke_collaborator` | destructive | yes | Revoke collaborator `user_access_id`'s access. Requires confirm=True. |
+| `run_sql` | write_safe | no | Run arbitrary SQL on the build's Postgres via `psql -c` over SSH. |
+| `search_log` | read | no | Grep `pattern` in log `name` over SSH, returning the last `lines` matches. |
+| `set_branch_settings` | write_safe | no | Write one or more settings (e.g. `push_behavior`, `test_tags`, `modules`) on `branch`. |
+| `set_branch_stage` | write_external | yes | Move a branch to a new stage (dev/staging/production). Requires confirm=True. |
+| `set_collaborator_access` | write_external | yes | Change collaborator `user_access_id`'s access level to `access_level`. Requires confirm=True. |
+| `set_project_settings` | write_external | yes | Write project-level settings (e.g. worker/storage limits, staging slot count). Requires confirm=True. |
+| `ssh_exec` | ssh_exec | yes | Run an arbitrary shell `command` on `branch`'s build over SSH. Requires confirm=True. |
+| `start_profiler` | write_safe | no | Start flamegraph profiling on `build_id`. |
+| `stop_profiler` | write_safe | no | Stop flamegraph profiling on `build_id`, producing a downloadable flamegraph file. |
+| `tail_log` | read | no | Tail the last `lines` of log `name` (e.g. "odoo", "install") over SSH. |
+| `wait_for_build` | read | no | Block, polling, until `branch`'s current build reaches a terminal status. |
+
+## Development
+
+```bash
+pyenv virtualenv 3.12 odoosh-mcp
+pyenv activate odoosh-mcp
+pip install -e ".[dev]"
+pytest
+ruff check odoosh_mcp/
+```
+
+Integration tests that hit a live odoo.sh project are opt-in and read-only by default — see
+`tests/integration/` and the design spec §10. `tests/integration/test_live_auth.py` checks the
+authentication surface without writing anything or opening a browser.