OrderDesk MCP 服务器

![CI](https://github.com/ebabcock80/orderdesk-mcp/actions) ![Tests](https://github.com/ebabcock80/orderdesk-mcp/actions) ![Coverage](https://github.com/ebabcock80/orderdesk-mcp/actions) ![Python](https://www.python.org/downloads/) ![License](LICENSE)

一个用于OrderDesk与Claude和LM Studio等AI助手集成的原生模型上下文协议（MCP）服务器。它具备专业的网页管理员界面用于店铺管理、一个交互式的API控制台用于测试，以及全面的生产监控功能。

状态： ✅ 配备WebUI，即刻投入生产 | CI：（通常指）企业识别系统/公司形象 🟢 翻译为中文是：绿勾（或绿对勾），通常用作表示正确、通过或批准的符号。 所有检查均通过 | 测试： 76/76（100%）

🚀 功能特点

核心MCP特性

原生MCP协议与Claude、LM Studio及其他MCP兼容的AI助手直接集成
安全订单更新获取 → 合并 → 更新工作流程，防止数据丢失
直接订单台集成使用store_id + api_key进行身份验证的简化架构
全面的API覆盖订单、产品、客户、文件夹、网络钩子（或Webhooks）和报告
JSON 响应格式化为AI助手解析设计的格式正确的回复
Docker 准备就绪使用健康检查的多阶段Docker构建
持久化存储带有卷挂载以实现数据持久化的SQLite数据库

🎨 WebUI 管理员界面（第5阶段）⭐

专业仪表盘店铺、API状态和快速操作的视觉概览
店铺管理为OrderDesk商店注册提供完整的CRUD（创建、读取、更新、删除）操作
交互式API控制台直接在您的浏览器中测试所有13种MCP工具
安全认证使用主密钥登录的JWT会话
移动响应式（或：适配移动设备）可在台式机、平板电脑和移动设备上使用
实时反馈即时响应显示，带语法高亮
请求历史追踪您最近的10次API请求
设置页面查看配置和系统信息

👥 新增：用户管理 + 可选公开注册（阶段6）⭐

用户管理主钥匙持有者可以查看和管理所有用户
活动追踪监控用户登录、活动及存储使用情况
级联删除删除用户及其所有数据（存储、审计日志、会话）
可选的公开注册启用/禁用公开注册功能 ENABLE_PUBLIC_SIGNUP
电子邮件验证使用魔法链接验证的安全注册流程
主密钥生成加密安全密钥（64个字符，URL安全）
一次性展示主密钥显示一次，并提供复制/下载选项
速率限制每小时每个IP地址可注册3次（可配置）
自助服务用户可以注册、验证邮箱，并自动获取他们的主密钥

访问Web用户界面： 设定；一套；一组 ENABLE_WEBUI=true 在 .env 并且参观 http://localhost:8000/webui

🛠️ 实施了MCP工具（共13个）

v0.1.0-alpha（版本0.1.0测试版） 包含13个功能齐全的MCP工具：

租户与店铺管理（6种工具）

tenant.use_master_key - 使用主密钥进行身份验证（支持自动配置）
stores.register - 使用加密凭证注册OrderDesk商店
stores.list - 列出已认证租户的所有商店
stores.use_store - 为会话设置活动商店
stores.delete - 取消商店注册
stores.resolve - 店铺查询调试工具

订单操作（5种工具）

orders.get - 根据ID获取单个订单（15秒缓存）
orders.list - 列出订单，并支持分页和过滤（15秒缓存）
orders.create - 在OrderDesk中创建新订单
orders.update - 使用安全合并工作流更新订单（冲突时重试5次）
orders.delete - 从OrderDesk中删除订单

产品运营（2种工具）

products.get - 通过ID获取单个产品（60秒缓存）
products.list - 列出产品，并支持搜索和分页功能（缓存60秒）

将在未来阶段推出

客户运营（第7阶段及以后）
Webhook管理（第5阶段+）
文件夹操作（阶段7+）
报告（第7阶段+）

✅ 持续集成/持续交付（CI/CD）状态

所有GitHub Actions检查均通过： 🟢 翻译为中文是：绿对勾（或绿勾号），通常表示成功、正确或允许。

检查	状态	详情
“Lint & Format”可以翻译为“检查并格式化”或“代码检查与格式调整”，具体取决于上下文，但通常指的是对代码进行语法检查和格式调整的过程	✅ 通过	ruff + black（0个错误）
类型检查	✅ 通过	mypy（0个错误，3条信息提示）
单元测试	✅ 通过	76/76项测试（100%）
覆盖范围	✅ 及格	58.5%（及格线：55%）
Docker 构建	✅ 通过	多阶段构建成功

查看结果：

质量指标：

🎯（靶心，目标） 100%测试通过率 （76/76项测试有效）
🎯（靶心符号，常用于表示目标或焦点） 0 个代码风格检查错误 （粗糙+黑色）
🎯（目标、瞄准） 0个类型错误 (mypy)
🎯（瞄准目标） 0 个 Pydantic 警告 （V2准备就绪）
🎯 目标（或瞄准、射中目标） 58.5%的代码覆盖率 （核心功能经过充分测试）
🎯 目标 可投入生产的（状态） 带有WebUI管理界面

🚀 快速入门

先决条件

Docker安装 Docker Desktop 或 Docker 引擎
OrderDesk 账户拥有API访问权限的活跃OrderDesk账户
人工智能助手Claude Desktop、LM Studio或其他兼容MCP的客户端

步骤1：克隆并构建

# Clone the repository
git clone https://github.com/ebabcock80/orderdesk-mcp.git
cd orderdesk-mcp

# Build the Docker image
docker build -t orderdesk-mcp:latest .

步骤2：生成加密密钥

# Generate a secure encryption key
python -c "import secrets; print(secrets.token_urlsafe(32))"
# Copy the output - you'll need this for MCP_KMS_KEY

步骤3：运行MCP服务器

# Create data directory for persistent storage
mkdir -p data

# Run the MCP server with persistent data
docker run --rm -i \
  -v $(pwd)/data:/app/data \
  -e SERVER_MODE=mcp \
  -e MCP_KMS_KEY="YOUR_GENERATED_KEY_HERE" \
  -e DATABASE_URL="sqlite:///./data/app.db" \
  -e LOG_LEVEL=info \
  orderdesk-mcp:latest

步骤4：配置您的AI助手

对于Claude Desktop

添加到您的 claude_desktop_config.json：

{
  "mcpServers": {
    "orderdesk": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "/path/to/your/data:/app/data",
        "-e", "SERVER_MODE=mcp",
        "-e", "MCP_KMS_KEY=YOUR_GENERATED_KEY_HERE",
        "-e", "DATABASE_URL=sqlite:///./data/app.db",
        "-e", "LOG_LEVEL=info",
        "orderdesk-mcp:latest"
      ]
    }
  }
}

对于LM Studio

创建一个配置文件：

{
  "mcpServers": {
    "orderdesk": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-v", "/path/to/your/data:/app/data",
        "-e", "SERVER_MODE=mcp",
        "-e", "MCP_KMS_KEY=YOUR_GENERATED_KEY_HERE",
        "-e", "DATABASE_URL=sqlite:///./data/app.db",
        "-e", "LOG_LEVEL=info",
        "orderdesk-mcp:latest"
      ]
    }
  }
}

步骤5：测试连接

配置完成后，您的AI助手应该能够使用OrderDesk工具。试着询问：

“列出我的OrderDesk店铺”
“给我看看最近的订单”
“创建一个新的订单文件夹”

______________________________________________________________________

🎨 WebUI 快速入门

访问Web管理界面

OrderDesk MCP服务器包含一个可选的专业网页管理界面，用于管理商店、测试API以及监控系统。

步骤1：配置WebUI

编辑你的 .env 文件：

# Enable WebUI
ENABLE_WEBUI=true

# Set JWT secret (generate with: openssl rand -base64 48)
JWT_SECRET_KEY=your-secure-random-64-char-key-here

# Session settings
SESSION_TIMEOUT=3600
SESSION_COOKIE_SECURE=true
SESSION_COOKIE_SAMESITE=strict

# Phase 6: User Management + Optional Public Signup
ENABLE_PUBLIC_SIGNUP=false  # Set to true for public/SaaS deployments
REQUIRE_EMAIL_VERIFICATION=true

# Email Configuration (for public signup)
EMAIL_PROVIDER=console  # Use 'smtp' for production
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USERNAME=your-email@gmail.com
SMTP_PASSWORD=your-app-password
SMTP_USE_TLS=true
SMTP_FROM_EMAIL=noreply@yourdomain.com

# Signup Rate Limiting
SIGNUP_RATE_LIMIT_PER_HOUR=3
SIGNUP_VERIFICATION_EXPIRY=900  # 15 minutes

步骤2：启动服务器

# Using Docker Compose (recommended for production)
docker-compose -f docker-compose.production.yml up -d

# Or run locally with uvicorn
uvicorn mcp_server.main:app --host 0.0.0.0 --port 8000

步骤3：访问Web用户界面（WebUI）

导航至： http://localhost:8000/webui

特点：

🔐 使用您的主密钥登录
📊 带有店铺概览的仪表板
🏪 管理店铺（添加、编辑、删除、测试连接）
🧪 交互式API控制台（测试所有13个MCP工具）
⚙️ 设置和配置显示

WebUI 截图

仪表盘：

商店数量和快速操作
最近的活动
API状态指示器

API 控制台：

选择任意一种13种MCP工具中的任意一种
动态表单生成
即时显示JSON响应
请求历史追踪

🔧 关键特性

安全订单更新

服务器实现了订单更新的关键安全功能：

获取获取当前完整的订单数据
合并将您的更改应用到现有数据中
更新将完整更新后的订单发送回OrderDesk

这可以防止在部分更新过程中可能发生的数数据丢失。

JSON 响应格式化

所有MCP工具的响应均以有效的JSON格式正确呈现，AI助手能够解析并理解这些响应，从而避免了解析错误。

直接订单台集成

使用简化的身份验证 store_id + api_key
无需复杂的租户管理
直接访问所有OrderDesk API端点

📋 环境变量

变量	描述	默认值	是否必需
项目	描述	类型	数量	`SERVER_MODE`	`mcp`	服务器模式： `api` 或者 `mcp`
编号	`MCP_KMS_KEY`
Base64编码的加密密钥（32+字节）	-	是	`DATABASE_URL`	`sqlite:///./data/app.db`	SQLite 数据库 URL
不（或“否”）	`LOG_LEVEL`	`info`	日志级别
序号	`TRUST_PROXY`	`false`	信任代理头信息
序号	`AUTO_PROVISION_TENANT`	`true`	自动创建租户

| 编号/序号 |

🏭 生产特点

监控与可观测性Prometheus 指标
15+项生产指标（请求延迟、缓存命中率、错误追踪）健康检查/health4个端点（ /health/live， /health/ready， /health/detailed，
）结构化日志记录
带有相关ID和敏感信息遮蔽的JSON日志审计轨迹/审计路径

记录所有MCP工具调用的完整日志

部署选项Docker Compose
单服务器部署，使用nginx + PostgreSQL + RedisKubernetes（中文常译为“K8s”，但“Kubernetes”本身也是被广泛接受的译名）
包含健康检查和自动扩展功能的完整清单多实例
带自动故障转移的负载均衡SSL/TLS

Let's Encrypt、自签名或Cloudflare集成

安全A+安全评级
符合OWASP Top 10标准加密
使用AES-256-GCM进行凭证加密，使用HKDF进行密钥派生认证
bcrypt 主密钥，JWT 会话，CSRF 保护速率限制
令牌桶算法，每个租户的限制审计日志记录

全面的活动追踪

演出智能缓存
多后端（内存/SQLite/Redis）支持，可配置TTL（生存时间）冲突解决
自动重试，采用指数退避策略连接池
高效的数据库和HTTP客户端连接池响应时间


#### Docker 连接问题

Verify environment variables

echo $MCP_KMS_KEY echo $DATABASE_URL

Check data directory permissions

ls -la data/

Test with verbose logging

docker run --rm -i \ -v $(pwd)/data:/app/data \ -e SERVER_MODE=mcp \ -e MCP_KMS_KEY="your-key" \ -e LOG_LEVEL=debug \ orderdesk-mcp:latest


#### MCP服务器无法启动

- **订单台API错误**401 未授权 `store_id` 检查你的 `api_key`
- **和**404 未找到
- **验证端点是否存在于OrderDesk API v2中**500 服务器错误

#### 检查OrderDesk服务状态

Ensure data directory exists and is writable

mkdir -p data chmod 755 data

Check database file

ls -la data/app.db


### 数据持久性问题

1. **寻求帮助**检查日志
1. **在Docker容器日志中查找错误消息**验证配置
1. **确保所有环境变量都已正确设置**测试连接性 `health_check`
1. **尝试使用一个简单的工具调用，比如**检查OrderDesk（或：查看订单台）

## 验证您的OrderDesk帐户和API凭据

- **🆘 支持**问题 [:](https://github.com/ebabcock80/orderdesk-mcp/issues)
- **GitHub Issues（GitHub问题）**文档
- **这个README文件和内联代码注释**MCP 集成
- **参见上面的工具模式和示例**订单台API [：](https://app.orderdesk.me/api-docs)

### 订单台API文档

做出贡献

1. 发现了一个错误或想要添加一个功能？我们欢迎贡献！
1. 克隆该仓库 `git checkout -b feature/amazing-feature`
1. 创建一个特性分支：
1. 进行你的更改并测试它们 `git commit -m 'Add amazing feature'`
1. 提交您的更改： `git push origin feature/amazing-feature`
1. 推送到分支：

### 提交一个拉取请求

许可证 [这个项目遵循MIT许可证授权——详见](LICENSE) 许可证

Orderdesk MCP

快速接入

详细介绍