Shopmonkey MCP Server

Shopmonkey MCP服务器


A. 模型上下文协议（MCP） 包装的服务器 Shopmonkey REST API（v3），使AI代理和LLM能够与商店管理数据进行交互——工作订单、客户、车辆、库存、预约、付款、劳动力、罐装服务、webhooks等。

特性

• 64工具 涵盖Shopmonkey API的11个资源组
• 双重运输 --stdio用于本地/桌面使用，Streamable HTTP用于云部署
• Shopmonkey API密钥认证（承载令牌到Shopmonkey REST API）
• 自动重试，速率限制（429）和服务器错误（5xx）呈指数回退
• 请求并发控制（最多5次同时调用API）
• 每次呼叫请求超时30秒
• 通过以下方式提供多位置支持 SHOPMONKEY_LOCATION_ID 或根据请求 locationId
• 出现Shopmonkey错误代码和消息的描述性错误消息
• HTTP传输包括承载身份验证、健康检查端点和优雅关闭
• 适用于Claude Desktop、Cursor、Claude Code、Claude.ai和任何兼容MCP的客户端

快速开始

git clone https://github.com/AbbottDevelopments/shopmonkey-mcp-server.git
cd shopmonkey-mcp-server
npm install
npm run build

复制 .env.example 到 .env 并添加您的Shopmonkey API密钥：

cp .env.example .env
# Edit .env — set SHOPMONKEY_API_KEY to your key

启动服务器：

# stdio (local use with Claude Desktop, Cursor, Claude Code)
npm start

# HTTP (cloud deployment, Claude.ai)
npm run start:http

运输

服务器提供两个入口点，共享一个工具注册表——使用与部署目标匹配的入口点。

stdio（本地使用）

node dist/index.js
# or: npm start

您的MCP客户端直接生成此进程。由Claude Desktop、Cursor和Claude Code使用。看 MCP客户端配置 在......下面

流式HTTP（云部署）

PORT=3000 node dist/http.js
# or: npm run start:http

HTTP服务器侦听 PORT （默认值 3000)并处理MCP请求 /。用于云部署（铁路、渲染）和连接到Claude.ai。

HTTP功能：

• 认证 --设置 MCP_AUTH_TOKEN 要求 Authorization: Bearer 在所有MCP请求上。未设置时开放访问（本地开发）。
• 健康检查 — GET /health 和 GET / 返回 {"status":"ok"} 用于负载均衡器探头。
• 优雅关闭 --SIGTERM/SIGINT上的干净退出，超时5秒。

有关云部署说明，请参阅 文档/部署.md.

工具参考

工单（4个工具）

Shopmonkey API不支持订单删除。看 docs/LIMITIONS.md 了解详情。

客户（6工具）

电子邮件和电话是Shopmonkey的子资源。创建客户后，使用 POST /v3/customer/:id/email 和 /phone_number 附上联系方式。看 docs/LIMITIONS.md.

车辆（7工具）

库存和零件（4个工具）

预约（4个工具）

付款（3种工具）

所有货币值都使用整数分 *Cents 命名。切勿发送十进制美元金额。

技术人员和劳动力（4个工具）

服务和罐装服务（22种工具）

罐装服务项目 --5种类型（费用、人工、零件、分包、轮胎），具有添加/更新/删除操作：

Webhooks（5个工具）

支持的触发器： Appointment, Customer, Inspection, Inventory, Message, Order, Payment, PurchaseOrder, User, Vehicle, Vendor

报告--综合（3个工具）

报告由列表端点合成（每份报告最多100条记录）。对大型商店使用更严格的日期范围。

工作流程和位置（2个工具）

MCP客户端配置

克劳德桌面版

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "shopmonkey": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/path/to/shopmonkey-mcp-server",
      "env": {
        "SHOPMONKEY_API_KEY": "your_api_key_here"
      }
    }
  }
}

光标

添加到光标MCP设置中：

{
  "mcpServers": {
    "shopmonkey": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/path/to/shopmonkey-mcp-server",
      "env": {
        "SHOPMONKEY_API_KEY": "your_api_key_here"
      }
    }
  }
}

克劳德代码

claude mcp add shopmonkey -e SHOPMONKEY_API_KEY=your_api_key_here -- node /path/to/shopmonkey-mcp-server/dist/index.js

Claude.ai（HTTP传输）

部署 dist/http.js 铁路或渲染 SHOPMONKEY_API_KEY 和 MCP_AUTH_TOKEN 设置为环境变量。看 文档/部署.md 完整的指南。

文档

环境变量

服务器自动加载 .env 通过 Dotenv。 如果存在。您还可以通过shell或MCP客户端配置传递变量。

发展

npm run build        # Compile TypeScript
npm run dev          # Watch mode (tsc --watch)
npm start            # Start stdio server
npm run start:http   # Start HTTP server
npm test             # Run test suite (requires build first)

测试套件包括9个测试文件中的186个测试，包括模拟API行为、MCP协议符合性、错误路径和传输验证。

错误处理

服务器处理常见的API场景：

• 缺少API密钥 --设置说明中的描述性错误
• 速率限制（429） --具有指数回退的自动重试（最多3次尝试），尊重 Retry-After 头球
• 服务器错误（500502503504） --带回退功能的自动重试
• 请求超时 --30秒中止，并显示明确的错误消息
• 网络故障 --使用回退、可读的错误消息重试
• API错误 --表面Shopmonkey错误代码(API-xxxxx, ORM-xxxxx)人类可读 message 领域

API 参考

• Shopmonkey API文档
• Shopmonkey API基础URL
• 模型上下文协议

许可证

麻省理工学院