Jobber Automation MCP

一个自托管的 MCP 服务器，让 ChatGPT 可以查看 Jobber 数据并管理受控的自动化。同一套 Docker Compose 栈可在 macOS、Linux 和 Raspberry Pi ARM64 上运行。

这是一个早期的单所有者构建版本，不适用于公共或多租户托管。

当前版本：v0.2.0

架构

flowchart LR
    C[ChatGPT] --> T[Secure MCP Tunnel]
    T --> M[Jobber Automation MCP]
    M --> J[Jobber GraphQL API]
    M --> D[(Private SQLite data)]
    M --> W[Automation worker]

MCP 服务器定义了 ChatGPT 可以调用的工具。工作进程即使在没有任何聊天打开时也会执行已保存的计划。操作目录是刻意受控的；自动化定义不能执行任意的操作系统命令。

当前能力

• Jobber OAuth 授权码流程和轮换刷新令牌支持

• Jobber 账户、客户和工单查询

• 只读 GraphQL 和已确认变更的逃生舱

• 使用 WAL 模式和私有数据库文件的 SQLite 持久化

• 自动化 create、list、get、update、activate、pause、preview、run-now、history 和 delete 工具

• 手动和重复间隔触发器

• Log、Jobber query 和 Jobber mutation 操作

• draft-on-create 和 draft-after-edit 审查生命周期

• 每次运行审批或明确预先批准的自动化策略

• 带运行和审计历史的后台调度器

• 与 macOS 开发和 Linux ARM64 Raspberry Pi 主机兼容的 Docker 打包

安全行为

• 新建和编辑的自动化都是草稿，不能运行。

• 激活需要精确短语 I APPROVE THIS AUTOMATION。

• 使用 always 审批的 Jobber 变更自动化不能从调度器执行变更。

• 其手动运行需要 I CONFIRM THIS AUTOMATION RUN。

• preapproved 变更自动化只有在完整定义被审查并激活后才能无人值守运行。

• 通用的一次性变更需要 I CONFIRM THIS JOBBER CHANGE。

• OAuth 状态是哈希的、单次使用的，并在十分钟后过期。

• 每次变更尝试和自动化结果都会被审计。

安装

从与任务匹配的文档开始：

• 安装和更新

• Raspberry Pi 部署和迁移

• 备份、恢复和回滚

• 安全策略

• 版本历史

快速本地开发设置需要 Node.js 22.5 或更高版本：

npm install
npm run build
npm start

数据库默认为 ./data/jobber-mcp.sqlite。

ChatGPT MCP 端点

本地 MCP 路径为：

http://localhost:8080/mcp/YOUR_MCP_PATH_TOKEN

附带的 Compose 文件与服务器一起运行 OpenAI Secure MCP Tunnel。两个已发布的端口仅绑定到主机回环地址；不要通过路由器端口转发暴露它们。

自动化定义示例

{
  "name": "Hourly account check",
  "description": "Verify that Jobber remains reachable.",
  "approvalPolicy": "always",
  "trigger": { "type": "interval", "everyMinutes": 60 },
  "actions": [
    {
      "type": "jobber.query",
      "query": "query Account { account { id name } }"
    }
  ]
}

MCP 工具将其创建为草稿。预览它，激活它，然后检查其历史。

开发

npm run check

测试套件涵盖 GraphQL 操作分离和本地自动化生命周期。

发布策略

版本使用 MAJOR.MINOR.PATCH 语义化版本控制。每个版本都会收到一个 Git 标签和相应的变更日志条目。在 v1.0 之前，次要版本可能包含需要查看迁移说明的重大更改。

计划工作

• 基于已认证模式的命名 Jobber 工具，而不是通用 GraphQL

• 日历/cron、Jobber 轮询和 webhook-relay 触发器

• 条件、模板、通知、重试和幂等键

• 嵌入式 MCP Apps 自动化仪表板

• 加密或操作系统支持的令牌存储

• 自动化备份验证和更简单的恢复命令

• 专用调度和访问管理工作流

重要限制

• 计划工作仅在主机处于唤醒状态且服务器运行时执行。

• Secure MCP Tunnel 将 ChatGPT 连接到 MCP；它不是通用的入站 Jobber webhook 端点。

• 在生产环境中使用之前，必须根据已认证模式和所选 API 版本验证 Jobber 字段和变更。

• 不要将本地端口直接暴露到公共互联网。

许可证

根据 MIT License 发布。