工时表管理服务器

Odoo工时记录MCP服务器

这个项目实施了一个 模型上下文协议 (MCP) 服务器，提供工具以便通过（某种方式）处理Odoo 16的时间表单 官方外部XML-RPC API。

服务器提供了以下MCP工具：

• 列出最近的工时记录条目（account.analytic.line）
• 更新现有的工时表
• 创建一个新的工时记录条目

所有响应均包含结构化的JSON输出和文本表示形式，因此MCP客户端可以轻松地使用这些数据或将其显示给用户。

先决条件

• Node.js 18+（已测试过v24版本）
• 一个可访问且已启用XML-RPC的Odoo 16实例
• 具有读取/创建/写入权限的凭据 account.analytic.line 记录

入门指南

npm install

创建一个 .env 使用您的Odoo连接详情保存（或导出变量）文件：

ODOO_BASE_URL=https://your-odoo-host.example.com
ODOO_DATABASE=your_database
ODOO_USERNAME=api.user@example.com
ODOO_PASSWORD=your_api_password

可用的环境变量：

提示：Odoo将API密钥视为RPC调用的密码，因此请设置其中之一 ODOO_PASSWORD 或者 ODOO_API_KEY 使用您的密钥——无需更改代码。

发展

以监视/开发模式运行服务器，使用 tsx：

npm run dev

对于生产构建：

npm run build
npm start

服务器通过标准输入输出（stdio）进行通信，因此您可以将其连接到任何兼容MCP的主机上。服务器启动时会注册三个工具：

传输模式（stdio 与 SSE）

默认情况下，服务器通过标准输入输出（stdio）运行，这适用于大多数基于命令行界面（CLI）的MCP主机。某些平台（如n8n）期望使用传统的HTTP加服务器发送事件（SSE）传输方式。您可以通过环境变量启用该模式：

MCP_TRANSPORT=sse npm start

SSE 模式使用以下设置启动一个 HTTP 服务器（可通过环境变量覆盖）：

在SSE模式下运行时：

• 客户端在（某个地方）打开一个GET流 /sse （例如。 GET http://host:3333/sse）。 为了向后兼容， /mcp 也被接受。
• 服务器发出一个 endpoint 包含POST URL的事件 + sessionId。
• 客户端向事件中返回的POST端点发送JSON-RPC请求（默认 /messages?sessionId=...）。

支持多个会话；每个传入的GET连接都会获得一个独立的MCP服务器实例。

使用curl进行快速SSE测试

启动容器（或本地进程）使用 MCP_TRANSPORT=sse 然后：

# 1. Start an SSE stream and capture the endpoint event
curl -N http://127.0.0.1:3333/sse

# 2. In another terminal, post an initialize request to the returned session endpoint
curl -X POST \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":"1","method":"initialize","params":{"clientInfo":{"name":"curl-test","version":"0.0.1"},"capabilities":{},"protocolVersion":"0.5"}}' \
  "http://127.0.0.1:3333/messages?sessionId=<session-from-step-1>"

你应该会收到一封 Accepted 响应以及SSE（服务器发送事件）流将发出 initialize 包含服务器元数据和功能的结果有效载荷。

在Docker中运行

如果您需要在多台机器上部署MCP服务器（例如您的家庭工作站或n8n主机），可以使用提供的Docker资源。

1. 确保您的 .env （或选择的环境文件）包含上述描述的Odoo凭据/URL。

2. 通过辅助脚本构建并运行容器：

   复制

   ./scripts/docker-run.sh
   

   该脚本将：

   • 构建 odoo-mcp-server 图像（用以下内容覆盖 IMAGE_NAME=my-image ./scripts/docker-run.sh)
   • 启动容器时附加stdin/stdout，以便MCP主机可以通过标准输入/输出进行通信
   • 从（指定位置）加载环境变量 .env (用...覆盖 ENV_FILE=/path/to/env）

手动管理容器：

docker build -t odoo-mcp-server .
docker run --rm -i --env-file .env odoo-mcp-server

因为MCP依赖于stdio，所以请保持 -i 标志（flag）设置使得容器保持附加到调用进程。当与n8n等平台集成时，配置进程步骤以启动 docker run --rm -i ... 并根据您的工作流程要求将标准输入输出重定向到管道。

SSE注： 如果你想让容器使用HTTP + SSE而不是stdio，添加传输变量：
docker run --rm -i -p 3333:3333 --env-file .env -e MCP_TRANSPORT=sse odoo-mcp-server

除了工具之外，服务器还提供了有用的MCP资源：

• resource://odoo-mcp/docs/readme – 这份README文件供客户端内部快速参考。
• resource://odoo-mcp/config/environment – 环境变量核对清单（密钥值已隐藏）。
• resource://odoo-mcp/docs/timesheet-fields – 摘要/总结 account.analytic.line 工具所使用的字段。

每个工具都使用（某种方法）对输入进行验证 zod 并通过XML-RPC端点与Odoo进行交互/xmlrpc/2/common 用于认证和 /xmlrpc/2/object 用于RPC调用）。

Odoo模型备注

工时表存储在 account.analytic.line服务器读取和写入以下字段：

• name （描述）
• date
• unit_amount （小时）
• employee_id
• project_id
• task_id

如果你需要自定义行为（添加额外字段、不同的默认值等），请扩展辅助函数 src/odooClient.ts。

MCP 集成技巧

• 确保您的MCP主机将此服务器作为stdio子进程启动。
• 所有工具的响应均包含两者 structuredContent (JSON) 和一个可读的文本有效载荷。
• 身份验证失败或RPC错误会作为工具错误显示，错误信息前会加上工具名称作为上下文提示。

有用链接

• Odoo 16 外部API参考
• 模型上下文协议 - 构建服务器