Odoo Sh MCP Server

🚀 Odoo.sh MCP Server

Odoo.sh MCP Server 是一個基於 SSH 的模型上下文協議服務器，藉助 Git 工作流工具，可在 AI 輔助下構建自定義應用程序，為 Odoo.sh 開發提供便利。

✨ 主要特性

核心操作（v1.0）

• 🔐 基於 SSH 的訪問：通過 SSH 密鑰實現安全連接，無需 API 令牌。
• 🌿 分支操作：查看分支、獲取當前分支以及提交歷史。
• 🏗️ 構建管理：觸發構建、監控狀態並查看日誌。
• 💾 數據庫訪問：列出 PostgreSQL 數據庫及其大小。
• 💻 系統監控：查看主機名、正常運行時間、磁盤、內存和版本信息。
• 🐍 Odoo Shell：在 Odoo 環境中執行 Python 代碼。

🆕 Git 工作流與應用開發（v1.0 新增）

• 📁 文件管理：使用 base64 編碼創建、讀取和更新文件。
• 📂 目錄操作：為模塊創建目錄結構。
• 📖 Git 狀態：檢查已修改、暫存和未跟蹤的文件。
• ➕ Git Add：將文件暫存以進行提交（單個或多個）。
• ✅ Git Commit：使用自定義消息提交更改。
• 🚀 Git Push：將提交推送到遠程 Odoo.sh 倉庫。
• 🌿 Git Checkout：切換分支或創建新的功能分支。
• 🔄 Git Pull：從遠程同步更改。
• 🛠️ AI 輔助開發：讓 AI 代理構建完整的 Odoo 模塊。

🚀 快速開始

# 1. 安裝依賴項
npm install

# 2. 配置環境
cp .env.example .env
# 編輯 .env 並添加你的 ODOO_SH_API_TOKEN

# 3. 構建項目
npm run build

# 4. 添加到你的 MCP 客戶端配置（例如，Claude Desktop）
# 請參閱下面的配置部分

📦 安裝指南

前提條件

• Node.js >= 18.0.0
• npm（隨 Node.js 一起提供）
• 具有 SSH 訪問權限的 Odoo.sh 賬戶
• 已安裝的 OpenSSH 客戶端（Windows 10+、macOS、Linux 中包含）
• MCP 客戶端（Warp、Claude Desktop、Cline、Continue 等）

步驟

1. 克隆或下載此倉庫
2. 安裝依賴項：

   npm install
   

3. 設置 SSH 訪問：
   • 將你的 SSH 公鑰添加到 Odoo.sh（設置 → 協作者 → SSH 密鑰）。
   • 從 Odoo.sh 獲取你的構建 ID 和主機名（格式：BUILD_ID@project-name.dev.odoo.com）。
   • 將你的私鑰保存到安全位置。
4. 構建項目：

   npm run build
   

📚 詳細文檔

配置

環境變量

創建一個 .env 文件或設置環境變量：

ODOO_SH_SSH_HOST=project-name.dev.odoo.com
ODOO_SH_SSH_USER=BUILD_ID              # 例如，25357858
ODOO_SH_SSH_KEY_PATH=/path/to/ssh/key  # 私鑰的絕對路徑
ODOO_SH_SSH_PORT=22                    # 可選：默認為 22
ODOO_SH_SSH_PASSPHRASE=                # 可選：如果密鑰有密碼
SSH_TIMEOUT=30000                      # 可選：毫秒
LOG_LEVEL=info                         # 可選：debug、info、warn、error

⚠️ 重要提示

切勿提交你的 SSH 私鑰。使用絕對路徑並設置安全權限（Unix 系統使用 chmod 600）。

MCP 客戶端配置

Claude Desktop

編輯 claude_desktop_config.json：

{
  "mcpServers": {
    "odoo-sh": {
      "command": "node",
      "args": [
        "/absolute/path/to/Odoo.sh MCP/dist/index.js"
      ],
      "env": {
        "ODOO_SH_SSH_HOST": "project-name.dev.odoo.com",
        "ODOO_SH_SSH_USER": "BUILD_ID",
        "ODOO_SH_SSH_KEY_PATH": "/absolute/path/to/ssh/key"
      }
    }
  }
}

Cline (VSCode)

添加到 VSCode 設置：

{
  "cline.mcpServers": {
    "odoo-sh": {
      "command": "node",
      "args": ["/absolute/path/to/Odoo.sh MCP/dist/index.js"],
      "env": {
        "ODOO_SH_SSH_HOST": "${env:ODOO_SH_SSH_HOST}",
        "ODOO_SH_SSH_USER": "${env:ODOO_SH_SSH_USER}",
        "ODOO_SH_SSH_KEY_PATH": "${env:ODOO_SH_SSH_KEY_PATH}"
      }
    }
  }
}

⚠️ 重要提示

請使用 dist/index.js 的絕對路徑。

使用方法

配置完成後，你的 AI 助手可以直接使用 Odoo.sh 工具：

示例交互

基本操作

檢查項目信息：

"Show me my Odoo.sh project information"

檢查構建狀態：

"What's the status of recent builds?"

查看構建日誌：

"Show me the recent Odoo logs"

構建自定義應用（新增）

創建新的 Odoo 模塊：

"Create a new custom Odoo module called 'my_custom_app' with the basic structure"

AI 代理可以：

1. 創建目錄結構：my_custom_app/、my_custom_app/models/ 等。
2. 創建 __init__.py、__manifest__.py 文件。
3. 使用 Python 代碼創建模型文件。
4. 創建 XML 視圖文件。
5. 使用 git add 暫存所有文件。
6. 使用描述性消息提交。
7. 推送以觸發 Odoo.sh 構建。

修改現有模塊：

"Add a new field 'phone' to the Partner model in my_custom_app"

完整開發工作流示例：

"I want to build a customer feedback module:
1. Create module structure for 'customer_feedback'
2. Add a Feedback model with fields: customer_id, rating, comment, date
3. Create list and form views
4. Add menu items
5. Commit and push to main branch"

可用工具

服務器通過 SSH 為 Odoo.sh 操作提供 19 種工具，包括用於構建自定義應用的完整 Git 工作流支持：

項目與分支

• get_project_info：獲取項目信息，包括分支列表。
  • 返回：項目名稱、倉庫和分支列表。
  • 💡 建議使用此工具列出分支（推薦使用，而非 list_branches）。
• get_current_branch：獲取當前檢出的分支。
  • 返回：當前分支名稱。
• list_branches：列出帶有提交信息的分支。
  • 返回：帶有最後提交哈希和消息的分支名稱。
  • ⚠️ 已知問題：在某些 MCP 客戶端中可能無法正常工作（建議使用 get_project_info）。

構建

• get_build_history：獲取分支的提交/構建歷史。
  • 參數：branch（例如，"main"），limit（默認：10）。
  • 返回：提交哈希、作者、日期和消息。
• trigger_build：通過創建空提交觸發新的構建。
  • 參數：branch。
  • 返回：git push 輸出。

數據庫

• list_databases：列出所有 PostgreSQL 數據庫。
  • 返回：數據庫名稱和大小。

日誌與 Shell

• get_logs：從服務器獲取 Odoo 日誌。
  • 參數：log_type（"odoo"、"install"、"pip"），lines（默認：100）。
  • 返回：帶有時間戳的日誌條目。
• execute_odoo_shell：在 Odoo shell 中執行 Python 代碼。
  • 參數：python_code。
  • 返回：shell 輸出。

系統

• get_system_info：獲取系統信息。
  • 返回：主機名、正常運行時間、磁盤使用情況、內存、Python 版本和 Odoo 版本。

Git 工作流與文件管理（新增 - 用於構建自定義應用）

• git_status：獲取 git 狀態，顯示已修改、暫存和未跟蹤的文件。
  • 返回：git 狀態輸出。
• write_file：使用給定內容創建或更新文件。
  • 參數：filePath（相對於 ~/src/user），content。
  • 返回：成功消息。
  • 💡 使用 base64 編碼 以通過 SSH 安全傳輸文件內容。
• read_file：讀取文件內容。
  • 參數：filePath（相對於 ~/src/user）。
  • 返回：文件內容。
• list_files：列出路徑中的文件和目錄。
  • 參數：dirPath（可選，默認：.，相對於 ~/src/user）。
  • 返回：ls -la 輸出。
• create_directory：創建目錄（包括父目錄）。
  • 參數：dirPath（相對於 ~/src/user）。
  • 返回：成功消息。
• git_add：將文件暫存以進行提交。
  • 參數：files（文件路徑數組或 . 表示所有文件）。
  • 返回：git add 輸出。
• git_commit：提交暫存的更改。
  • 參數：message。
  • 返回：git 提交輸出。
• git_push：將提交推送到遠程倉庫。
  • 參數：branch（可選，默認為當前分支）。
  • 返回：git push 輸出。
• git_checkout：切換到分支或創建新分支。
  • 參數：branch，createNew（可選，默認：false）。
  • 返回：git checkout 輸出。
• git_pull：從遠程倉庫拉取更改。
  • 返回：git pull 輸出。

提示信息

常見任務的引導式工作流：

check_build_status

對項目進行全面的構建狀態檢查：

• 列出所有分支。
• 顯示最近的構建。
• 突出顯示失敗情況。
• 顯示構建趨勢。

使用方法：使用 project_id 調用 check_build_status。

deploy_workflow

逐步進行部署指導：

• 檢查當前分支狀態。
• 驗證待處理的構建。
• 驗證數據庫備份。
• 指導完成部署。
• 提供驗證步驟。

使用方法：使用 project_id 和 environment 調用 deploy_workflow。

開發

腳本

# 構建 TypeScript
npm run build

# 開發模式（自動重建）
npm run dev

# 運行測試
npm test

# 監控測試
npm test:watch

# 代碼檢查
npm run lint

# 代碼格式化
npm run format

項目結構

odoo-mcp-server/
├── src/
│   ├── index.ts          # MCP 服務器實現
│   └── odoo-client.ts    # Odoo.sh API 客戶端
├── tests/                # 測試文件（待添加）
├── docs/
│   ├── Runbook.md        # 設置和使用指南
│   ├── DECISIONS.md      # 架構決策
│   ├── Troubleshooting.md # 已知問題
│   └── Docs-Index.md     # 外部參考
├── dist/                 # 編譯後的 JavaScript（自動生成）
├── package.json
├── tsconfig.json
└── .env.example

測試

測試文件位於 tests/ 目錄中。使用以下命令運行測試：

npm test

故障排除

常見問題

1. SSH 連接失敗

Error: SSH connection error

解決方案：

• 驗證 SSH 密鑰路徑是否正確且為絕對路徑。
• 檢查密鑰權限：Unix 系統使用 chmod 600 /path/to/key，Windows 系統使用 icacls。
• 驗證主機名格式：BUILD_ID@project-name.dev.odoo.com。
• 手動測試：ssh -i /path/to/key BUILD_ID@host。

2. list_branches 工具在 Warp 中無法工作

Empty response from list_branches

解決方案：使用 get_project_info 替代，它可以返回分支列表，並且在所有 MCP 客戶端中都能可靠工作。

3. 殺毒軟件阻止 SSH 命令（Windows）

Bitdefender: Malicious command line detected

解決方案：在殺毒軟件設置中，將 SSH 命令或項目目錄列入白名單。

4. 服務器未顯示

• 驗證 MCP 客戶端配置中的 JSON 語法。
• 檢查 dist/index.js 的絕對路徑。
• 驗證環境變量是否已設置。
• 重啟 MCP 客戶端。

5. 模塊未找到

Error: Cannot find module '@modelcontextprotocol/sdk/server/index.js'

解決方案：運行 npm install 和 npm run build。

更多問題和解決方案請參閱 docs/Troubleshooting.md。

架構

技術棧

• 運行時：Node.js >= 18.0.0
• 語言：TypeScript 5.3
• 協議：模型上下文協議（MCP）
• SSH 客戶端：OpenSSH（子進程）
• 驗證：Zod
• 傳輸：標準輸入輸出

設計決策

關鍵架構決策記錄在 docs/DECISIONS.md 和 docs/SSH-MIGRATION.md 中：

• dec-20251107T160000Z-ssh-over-api：基於 SSH 的訪問而非 REST API。
• 選擇 OpenSSH 子進程而非 Node.js ssh2 庫的原因。
• 如何解決 Windows % 轉義問題。
• 為提高性能對 Git 命令進行的優化。

貢獻

歡迎貢獻代碼！請遵循以下步驟：

1. 遵循現有的代碼風格（使用 npm run format）。
2. 為新功能添加測試。
3. 更新文檔（README、Runbook、DECISIONS.md）。
4. 在 Troubleshooting.md 中記錄問題。

📄 許可證

本項目採用 MIT 許可證，詳情請參閱 LICENSE 文件。

鏈接

• Odoo.sh 文檔：https://www.odoo.com/documentation/17.0/administration/odoo_sh.html
• MCP 規範：https://spec.modelcontextprotocol.io/
• MCP TypeScript SDK：https://github.com/modelcontextprotocol/typescript-sdk

---

維護者：Odoo MCP Server 貢獻者
版本：0.1.0