Kaseya Quote Manager

Kaseya Quote Manager MCP Server

一个 Model Context Protocol (MCP) 服务，为 AI 助手提供对 Kaseya Quote Manager （Datto Commerce）的只读访问权限，涵盖报价、销售订单、采购、产品目录和客户。

由 Wyre Technology 维护。

快速开始

Claude Desktop — 下载、打开即可：

1. 从最新版本下载 kaseya-quote-manager-mcp.mcpb
2. 打开文件（双击或拖入 Claude Desktop）
3. 按提示输入 Kaseya Quote Manager API Key

Claude Code（命令行）：

claude mcp add kaseya-quote-manager-mcp \
  -e KASEYA_QUOTE_MANAGER_API_KEY=your-api-key \
  -- npx -y github:WYRE-AI/kaseya-quote-manager-mcp

身份验证

Quote Manager 使用单个 API key 进行身份验证，该密钥通过 apiKey 请求头发送。在 Quote Manager 的 Settings → API 中生成密钥。

Stdio 和 AUTH_MODE=env 会读取 KASEYA_QUOTE_MANAGER_API_KEY。除非 CONDUIT_S2S_SECRET 是真实值，否则不会启动 HTTP 传输。已知占位符（changeme、change-me、secret、example、placeholder、replace-me、your-secret、your-s2s-secret、s2s-secret、replace-with-a-real-secret）都会被拒绝，即使设置了 MCP_ALLOW_INSECURE_DEV=1 也不例外。进程绝不会记录该密钥。

HTTP 身份验证

设置 MCP_TRANSPORT=http 并配置密钥后，每个 /mcp 请求都必须包含 X-Gateway-S2S：

X-Gateway-S2S: t=<unix seconds>,v1=<64 lowercase hex chars>

v1 是对精确 ASCII 字符串 t=<unix seconds>（与请求头中出现的前缀相同）计算的 HMAC-SHA256，以 CONDUIT_S2S_SECRET 为密钥，并编码为 64 个小写十六进制字符。时间戳与服务器时钟的偏差不得超过 300 秒。缺少请求头或请求头无效时会返回 401。

在 AUTH_MODE=gateway（容器镜像和 Compose 的默认设置）下，/mcp 还要求提供 X-Kaseya-Quote-Manager-Api-Key。该请求头是此请求的唯一凭证。未提供该请求头的请求会返回 401，且不会回退到 KASEYA_QUOTE_MANAGER_API_KEY。

/health 不需要身份验证，不要求提供 X-Gateway-S2S，也不会返回 API key。Stdio 传输不会使用 CONDUIT_S2S_SECRET。

配置

复制 .env.example。

变量	必填	说明
KASEYA_QUOTE_MANAGER_API_KEY	Stdio 和 AUTH_MODE=env 时必填	Quote Manager API key。网关模式不会读取此变量。
MCP_TRANSPORT	否	stdio（默认）或 http
AUTH_MODE	否	gateway（Docker 镜像和 Compose 的默认设置）或 env。网关模式要求每个 /mcp 请求都包含 X-Kaseya-Quote-Manager-Api-Key，且绝不会回退到环境变量。
CONDUIT_S2S_SECRET	使用 HTTP 时必填	服务间密钥。若该值为空或为已知占位符，HTTP 服务器会记录错误并以非零状态退出。未配置此变量时，Compose 不会启动。切勿提交真实值。
MCP_ALLOW_INSECURE_DEV	否	仅限本地开发时设为 1，以便在未配置 CONDUIT_S2S_SECRET 的情况下启动 HTTP。进程会记录警告，不会强制要求 X-Gateway-S2S，并且只绑定到 127.0.0.1。如果 MCP_HTTP_HOST 不是回环地址，则会被覆盖并记录日志。若密钥是占位符，仍会拒绝启动。
MCP_HTTP_HOST	否	配置密钥时使用的绑定地址。默认为 127.0.0.1。容器镜像设为 0.0.0.0。启用不安全开发绕过时，会忽略此设置并使用 127.0.0.1。
MCP_HTTP_PORT	否	HTTP 端口。默认为 8080。
LOG_LEVEL	否	debug、info、warn 或 error。默认为 info。

功能

• 从设计上只读 — Quote Manager API 仅提供 list/get；没有任何工具可以修改你的数据。
• 39 个实体工具，涵盖 5 个领域，另有 kqm_navigate / kqm_status 发现工具。
• 决策树导航 — 调用 kqm_navigate 探索某个领域的工具。
• 速率限制 — 遵守 API 每分钟 60 次请求的限制，并在遇到 429/5xx 时重试。
• 双传输方式 — stdio（本地）和 HTTP Streamable（网关/Docker）。
• MCPB 打包，支持一键安装到 Claude Desktop。

领域与工具

工具命名为 kqm_<entity>_list 和 kqm_<entity>_get。

领域	实体
sales	quote, quote_section, quote_line, sales_order, sales_order_line, sales_order_payment
procurement	purchase_order, purchase_order_line, purchase_order_cost, supplier, product_supplier
catalog	product, product_image（仅 list）, category, brand
crm	customer, customer_address, contact
org	employee, warehouse

list 工具接受 page、pageSize（最大值为 100），以及在支持时使用的 modifiedAfter，此外还支持实体专属筛选条件（例如 quoteNumber、customerID、purchaseOrderID）。

使用示例

kqm_navigate { "domain": "sales" }
kqm_quote_list { "page": 1, "pageSize": 50 }
kqm_quote_get { "id": 12345 }
kqm_quote_section_list { "quoteID": 12345 }

Docker

该镜像在容器内监听 0.0.0.0（MCP_HTTP_HOST），并默认使用 AUTH_MODE=gateway。将端口发布到 loopback 地址，并传入 S2S 密钥。在网关模式下，API 密钥会随每个请求通过 X-Kaseya-Quote-Manager-Api-Key 传入。它不会从环境变量中读取。

生成一次密钥并导出，然后将其同时用于服务端和请求签名。-e CONDUIT_S2S_SECRET（仅名称）会传入已导出的值，而不会将其放入 docker 命令行。

export CONDUIT_S2S_SECRET="$(openssl rand -hex 32)"
docker build -t kaseya-quote-manager-mcp .
docker run --rm \
  -e CONDUIT_S2S_SECRET \
  -p 127.0.0.1:8080:8080 \
  kaseya-quote-manager-mcp
# Health: curl localhost:8080/health

如果未设置 CONDUIT_S2S_SECRET，Compose 会拒绝启动；它会设置 AUTH_MODE=gateway，不会传入 KASEYA_QUOTE_MANAGER_API_KEY，并发布 127.0.0.1:8080:8080。项目的 .env 仅用于变量插值 — 网关服务没有 env_file。

# Reuses the CONDUIT_S2S_SECRET exported above.
docker compose up

单租户 HTTP（AUTH_MODE=env）仍需要 S2S 密钥，然后使用 KASEYA_QUOTE_MANAGER_API_KEY：

docker run --rm \
  -e CONDUIT_S2S_SECRET \
  -e AUTH_MODE=env \
  -e KASEYA_QUOTE_MANAGER_API_KEY=your-api-key \
  -e MCP_HTTP_HOST=0.0.0.0 \
  -p 127.0.0.1:8080:8080 \
  kaseya-quote-manager-mcp

不带密钥的本地 HTTP 仅供开发使用。它始终绑定到 127.0.0.1，并记录一条警告。如果 MCP_HTTP_HOST 设置为非 loopback 地址，则会被覆盖：

MCP_TRANSPORT=http MCP_ALLOW_INSECURE_DEV=1 npm run start:http

使用 X-Gateway-S2S 和 API 密钥标头对网关请求签名。先构建该标头：v1 是对精确 ASCII 字符串 t=<unix seconds>（末尾没有换行符）进行 HMAC-SHA256 计算所得的值，以 CONDUIT_S2S_SECRET 为密钥，并表示为 64 个小写十六进制字符。使用启动服务时导出的同一个 CONDUIT_S2S_SECRET。

openssl dgst -hmac 会将密钥作为进程参数，因此运行期间，同一台机器上的其他本地用户可以在进程列表中看到它。仅在可信的单用户机器上运行此示例；其他情况下，请使用从环境变量读取密钥的代码来为请求签名。

: "${CONDUIT_S2S_SECRET:?Set CONDUIT_S2S_SECRET to the server secret}"
: "${KASEYA_QUOTE_MANAGER_API_KEY:?Set KASEYA_QUOTE_MANAGER_API_KEY to the Quote Manager API key}"
timestamp="$(date +%s)"
digest="$(
  printf 't=%s' "$timestamp" |
    openssl dgst -sha256 -hmac "$CONDUIT_S2S_SECRET" |
    awk '{print $NF}' |
    tr '[:upper:]' '[:lower:]'
)"
X_GATEWAY_S2S="t=${timestamp},v1=${digest}"

curl -sS http://127.0.0.1:8080/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -H "x-gateway-s2s: ${X_GATEWAY_S2S}" \
  -H "x-kaseya-quote-manager-api-key: ${KASEYA_QUOTE_MANAGER_API_KEY}" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"kqm_status","arguments":{}}}'

开发

npm install
npm run build
npm test
npm run lint

许可证

Apache-2.0 © WYRE Technology