Odoo Sh MCP Server

🚀 Odoo.sh MCP Server

SSHベースのOdoo.sh用モデルコンテキストプロトコルサーバー - Gitワークフローツールを使用してAI支援でカスタムアプリを構築

🚀 クイックスタート

# 1. 依存関係をインストールする
npm install

# 2. 環境を設定する
cp .env.example .env
# .envを編集し、ODOO_SH_API_TOKENを追加する

# 3. ビルドする
npm run build

# 4. MCPクライアントの設定に追加する（例：Claude Desktop）
# 以下の「設定」セクションを参照

✨ 主な機能

コア機能 (v1.0)

• 🔐 SSHベースのアクセス: SSHキーを使用した安全な接続（APIトークン不要）
• 🌿 ブランチ操作: ブランチの表示、現在のブランチの取得、コミット履歴の表示
• 🏗️ ビルド管理: ビルドのトリガー、ステータスの監視、ログの表示
• 💾 データベースアクセス: PostgreSQLデータベースとそのサイズの一覧表示
• 💻 システム監視: ホスト名、稼働時間、ディスク、メモリ、バージョンの表示
• 🐍 Odooシェル: Odoo環境でPythonコードを実行する

🆕 Gitワークフローとアプリ開発 (v1.0で追加)

• 📁 ファイル管理: base64エンコーディングを使用してファイルを作成、読み取り、更新する
• 📂 ディレクトリ操作: モジュール用のディレクトリ構造を作成する
• 📖 Gitステータス: 変更された、ステージングされた、追跡されていないファイルを確認する
• ➕ Git Add: コミットするためにファイルをステージングする（単一または複数）
• ✅ Git Commit: カスタムメッセージで変更をコミットする
• 🚀 Git Push: コミットをリモートのOdoo.shリポジトリにプッシュする
• 🌿 Git Checkout: ブランチを切り替えるか、新しい機能ブランチを作成する
• 🔄 Git Pull: リモートから変更を同期する
• 🛠️ AI支援開発: AIエージェントに完全なOdooモジュールを構築させる

📦 インストール

前提条件

• 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キーをコミットしないでください。絶対パスを使用し、安全なパーミッション（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ワークフローのサポートが含まれます:

プロンプト

一般的なタスクのためのガイド付きワークフロー:

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キーのパスが正しく、絶対パスであることを確認する
• キーのパーミッションを確認する: chmod 600 /path/to/key (Unix) または icacls (Windows)
• ホスト名の形式を確認する: BUILD_ID@project-name.dev.odoo.com
• 手動でテストする: ssh -i /path/to/key BUILD_ID@host

2. Warpで list_branches ツールが機能しない

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
• トランスポート: stdio

設計決定

主要なアーキテクチャの決定事項は、docs/DECISIONS.md と docs/SSH-MIGRATION.md に記載されています:

• dec-20251107T160000Z-ssh-over-api: REST APIではなくSSHベースのアクセス
• なぜNode.jsのssh2ライブラリではなくOpenSSHサブプロセスが選択されたのか
• Windowsの % エスケープ問題がどのように解決されたか
• パフォーマンスのためのGitコマンドの最適化

🔧 技術詳細

このサーバーは、Odoo.shの操作をSSHを介して行うためのものです。主な技術的な特徴は以下の通りです。

通信プロトコル

• Model Context Protocol (MCP): このサーバーはMCPを使用して、AIアシスタントとの通信を行います。MCPは、モデルコンテキストを共有するためのプロトコルであり、これによりAIアシスタントはOdoo.sh上のリソースを直接操作することができます。

セキュリティ

• SSHベースのアクセス: セキュリティを確保するために、SSHキーを使用したアクセス方式を採用しています。これにより、APIトークンを使用することなく、安全にOdoo.shのリソースにアクセスすることができます。

パフォーマンス

• Gitコマンドの最適化: カスタムアプリの開発において、Gitワークフローを効率的に行うために、Gitコマンドの最適化を行っています。これにより、ビルドやデプロイの処理時間を短縮することができます。

拡張性

• 新しいツールの追加: サーバーは、新しいツールを容易に追加することができるように設計されています。これにより、将来的にOdoo.shの機能拡張や新しいワークフローのサポートが容易になります。

🤝 コントリビュート

コントリビューションは大歓迎です！以下のことをお願いします:

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 Contributors
バージョン: 0.1.0