Scan to join WeChat grouparticle
README
🚀 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 等）
步骤
- 克隆或下载此仓库
- 安装依赖项：
npm install - 设置 SSH 访问：
- 将你的 SSH 公钥添加到 Odoo.sh（设置 → 协作者 → SSH 密钥）。
- 从 Odoo.sh 获取你的构建 ID 和主机名（格式：
BUILD_ID@project-name.dev.odoo.com）。 - 将你的私钥保存到安全位置。
- 构建项目：
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 代理可以：
- 创建目录结构：
my_custom_app/、my_custom_app/models/等。 - 创建
__init__.py、__manifest__.py文件。 - 使用 Python 代码创建模型文件。
- 创建 XML 视图文件。
- 使用
git add暂存所有文件。 - 使用描述性消息提交。
- 推送以触发 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 命令进行的优化。
贡献
欢迎贡献代码！请遵循以下步骤：
- 遵循现有的代码风格（使用
npm run format）。 - 为新功能添加测试。
- 更新文档（README、Runbook、DECISIONS.md）。
- 在 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