使用说明

OrderDesk MCP 服务器

一个用于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 构建	✅ 通过	多阶段构建成功

查看结果： GitHub Actions

质量指标：

🎯（靶心，目标） 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端点

📋 环境变量

变量	描述	默认值	是否必需
项目	描述	类型	数量
编号	`MCP_KMS_KEY`
Base64编码的加密密钥（32+字节）	-	是	`DATABASE_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客户端连接池响应时间

<50毫秒（缓存），<2秒（非缓存）见生产部署指南

以获取完整的安装说明。

🏗️ 建筑学

双接口设计 服务器提供 两个接口

为了实现最大灵活性：

1. MCP协议（AI助手接口）
原生stdio通信
13款已注册的人工智能助手工具
安全的订单更新（获取-合并-更新）

全面的错误处理

2. WebUI（人工管理员界面）
基于浏览器的管理仪表板
视觉店铺管理
交互式API测试控制台

响应式移动设计

核心组件认证
主密钥 + JWT 会话存储
带有加密凭证的 SQLite/PostgreSQL缓存
多后端支持，支持选择性失效HTTP 客户端
自动重试，采用指数退避策略监测

Prometheus指标 + 健康检查

📖 使用指南

开始使用OrderDesk首先，添加您的OrderDesk店铺
```
"Add my OrderDesk store with ID 42174 and API key abc123"
```
**：**列出您的店铺以进行验证
```
"Show me all my OrderDesk stores"
```

**:**浏览您的订单

"List my recent orders from OrderDesk"
"Show me pending orders"
"Get orders from folder 123"

:

常见用例

"Get details for order 12345"
"Update order 12345 status to shipped with tracking number 1Z999AA1234567890"
"Move order 12345 to the 'Shipped' folder"
"Add a note to order 12345: 'Customer requested expedited shipping'"

订单管理

"List all products in my store"
"Search for products containing 'widget'"
"Get details for product ID 5678"

产品运营

"List all customers"
"Search for customer 'john@example.com'"
"Get customer details for ID 999"

客户管理

"List all order folders"
"Create a new folder called 'Priority Orders'"
"Move order 12345 to the 'Priority Orders' folder"

文件夹整理

高级操作

安全订单更新

服务器自动处理安全的订单更新：
获取完整的当前订单数据
将您的更改与现有数据合并
将完整更新后的订单发送回OrderDesk

防止部分更新导致的数据丢失

"List the last 100 orders"
"Show me all orders from the last 30 days"
"Get all pending orders in folder 456"

批处理操作

🔧 MCP 工具参考

店铺管理

{
  "tool": "create_store",
  "arguments": {
    "store_id": "your-store-id",
    "api_key": "your-api-key",
    "name": "My Store"
  }
}

创建商店

{
  "tool": "list_stores",
  "arguments": {}
}

列出商店

订单操作

{
  "tool": "list_orders",
  "arguments": {
    "store_id": "your-store-id",
    "api_key": "your-api-key",
    "limit": 50,
    "offset": 0,
    "status": "pending",
    "folder_id": 123
  }
}

列出订单

{
  "tool": "get_order",
  "arguments": {
    "store_id": "your-store-id",
    "api_key": "your-api-key",
    "order_id": 12345
  }
}

获取订单

{
  "tool": "update_order",
  "arguments": {
    "store_id": "your-store-id",
    "api_key": "your-api-key",
    "order_id": 12345,
    "order_data": {
      "status": "shipped",
      "tracking_number": "1Z999AA1234567890"
    }
  }
}

更新订单（安全）

🚀 最新更新

关键修复（最新版本） **✅**JSON 响应格式化
修复了Claude解析错误，使用了正确的JSON格式 **✅ 表示“正确”或“对”的意思。**安全订单更新
实现了获取-合并-更新的工作流程以防止数据丢失 **✅**简化架构
简化了租户复杂性，采用直接的store_id + api_key认证方式 **✅**原生MCP协议

完整的MCP服务器实现，用于AI助手集成

主要改进 **🔧 修理工具或扳手的符号，常用于表示需要修理或维护的物品或情境。**错误处理
带有适当JSON结构的全面错误响应 **🔧（扳手或修理工具的符号，常用于表示维修、修理或技术相关的含义）**工具注册
所有OrderDesk操作均可作为MCP工具使用 🔧 修理工具或螺丝刀的象征数据库持久化
使用挂载卷实现数据持久化的SQLite **🔧 修理工具或螺丝刀的符号，常用于表示修理、维护或需要工具操作的情境。**Docker 优化

使用适当缓存的多阶段构建

📚 文档API 文档 /docs 可在以下位置获取
在API模式下运行时MCP 工具
所有工具均附有适当的架构说明和示例文档配置
环境变量和设置说明Docker

实现带卷支持的完整容器化

🤝 贡献（或：参与贡献）
为仓库创建分支（或：克隆仓库）
创建一个特性分支
进行你的更改
添加测试

提交一个拉取请求

📄 许可证 MIT 许可证 - 请参阅许可证

文件中有详细信息。

🔧 故障排除

常见问题

# Check if Docker is running
docker --version

# Verify the image was built correctly
docker images | grep orderdesk-mcp

# Check container logs
docker logs <container_id>

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

数据持久性问题

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

验证您的OrderDesk帐户和API凭据

🆘 支持问题 :
**GitHub Issues（GitHub问题）**文档
这个README文件和内联代码注释MCP 集成
参见上面的工具模式和示例订单台API ：

订单台API文档

做出贡献

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

提交一个拉取请求

许可证这个项目遵循MIT许可证授权——详见许可证

使用说明

OrderDesk MCP 服务器

🚀 功能特点

核心MCP特性

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

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

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

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

订单操作（5种工具）

产品运营（2种工具）

将在未来阶段推出

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

🚀 快速入门

先决条件

步骤1：克隆并构建

步骤2：生成加密密钥

步骤3：运行MCP服务器

步骤4：配置您的AI助手

对于Claude Desktop

对于LM Studio

步骤5：测试连接

🎨 WebUI 快速入门

访问Web管理界面

步骤1：配置WebUI

步骤2：启动服务器

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

WebUI 截图

🔧 关键特性

安全订单更新

JSON 响应格式化

直接订单台集成

📋 环境变量

| 编号/序号 |

🏭 生产特点

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

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

全面的活动追踪

以获取完整的安装说明。

🏗️ 建筑学

响应式移动设计

Prometheus指标 + 健康检查

📖 使用指南

:

常见用例

订单管理

产品运营

客户管理

文件夹整理

高级操作

防止部分更新导致的数据丢失

批处理操作

🔧 MCP 工具参考

店铺管理

创建商店

列出商店

订单操作

列出订单

获取订单

更新订单（安全）

🚀 最新更新

完整的MCP服务器实现，用于AI助手集成

使用适当缓存的多阶段构建

实现带卷支持的完整容器化

提交一个拉取请求

文件中有详细信息。

🔧 故障排除

常见问题

Docker 连接问题

MCP服务器无法启动

检查OrderDesk服务状态

数据持久性问题

验证您的OrderDesk帐户和API凭据

订单台API文档

提交一个拉取请求

相关 MCP

小红书MCP服务

Figma MCP集成工具

MCP 协议测试服务器

Flomo笔记服务

Unity编辑器AI集成插件