零售MCP服务器
一种模型上下文协议（MCP）服务器，它将零售后台API作为AI助手的工具公开。使用Node.js、TypeScript和官方MCP SDK构建。
先决条件
- Node.js 18或更高版本
- npm 9或更高版本
安装
npm install
配置
复制 .env.example 到 .env 并填写您的值：
cp .env.example .env
| 变量 | 描述 | 默认值 |
|---|
BASE_URL | 零售后台API的基本URL | http://172.168.168.36:8006 |
ACCESS_TOKEN | 用于身份验证请求的JWT访问令牌 | _（空）_ |
REFRESH_TOKEN | JWT刷新令牌用于自动令牌续订 | _（空）_ |
TENANT_DOMAIN | 默认租户域作为 client 头球 _（空）_ |
SECRET_KEY | 默认密钥以以下方式发送 X-SECRET-KEY 头球 _（空）_ |
PORT | MCP服务器的HTTP端口 | 3000 |
跑步
发展 （带ts节点）：
npm run dev
生产 （先编译，然后运行）：
npm run build
npm start
连接MCP客户端
使用SSE端点连接任何兼容MCP的客户端：
http://localhost:3000/sse
示例：Claude桌面配置
{
"mcpServers": {
"retail": {
"url": "http://localhost:3000/sse"
}
}
}
健康检查
GET http://localhost:3000/health
可用工具
认证
| 工具 | 说明 |
|---|
auth_admin_login | 管理员登录--POST /tenants/login/ （无客户端标头） |
auth_tenant_login | 租户登录--POST /tenants/login/ （带客户端标头） |
auth_client_login | 客户端登录--POST /api/auth/login/ （带客户端标头） |
auth_refresh_token | 刷新JWT访问令牌--POST /api/auth/token/refresh/ |
租户管理
| 工具 | 说明 |
|---|
tenant_onboard | 加入新租户——POST /tenants/onboard/ |
tenant_create_admin | 创建租户管理员用户--POST /tenants/create-admin/ |
tenant_offboard | 删除租户--Delete /tenants/offboarding/ (破坏性的，要求 confirm: true) |
目录
| 工具 | 说明 |
|---|
catalog_settings_bulk_create | 批量创建目录设置--POST /api/catalog/settings/bulk-create/ |
catalog_settings_active_fields | 获取活动目录字段--Get /api/catalog/settings/fields/active/ |
catalog_settings_search_fields_active | 获取活动搜索字段--Get /api/catalog/settings/search-fields/active/ |
catalog_settings_create_search_fields | 创建搜索字段--POST /api/catalog/settings/search-fields/ |
catalog_sync_status | 获取目录同步状态--Get /api/catalog/sync/ |
catalog_sync_trigger | 触发目录同步--POST /api/catalog/sync/ |
catalog_upload | 上传目录文件（多部分）--POST /tenants/catalog/upload/ |
搜索
| 工具 | 说明 |
|---|
search_query | 全文目录搜索--GET /api/search/ |
ai_agent_search | 基于人工智能的代理搜索——GET /ai/agent_search/ |
ai_agent_suggestions | AI搜索建议--GET /ai/agent_suggestions/ |
ai_purge | 清除AI搜索缓存--POST /ai/purge/ (破坏性的，要求 confirm: true) |
频道
| 工具 | 说明 |
|---|
channels_search | 搜索频道--GET /api/channels/search/ |
channels_brands | 获取渠道品牌--Get /api/channels/brands/ |
channels_synonyms | 获取频道同义词--Get /api/channels/synonyms/ |
AI搜索
| 工具 | 说明 |
|---|
ai_search | 基于人工智能的搜索——GET /api/ai/ai_search/ |
气流
| 工具 | 说明 |
|---|
airflow_trigger_dag | 触发气流DAG-POST /api/airflow/trigger-dag/ |
分析
| 工具 | 说明 |
|---|
analytics_search_performance | 搜索性能报告--GET /analytics/search_performance/ |
analytics_track_event | 跟踪分析事件——POST /analytics/events/ |
analytics_funnel_search | 漏斗搜索分析——GET /analytics/funnel_search/ |
安全说明
- 永不承诺
.env --它列在 .gitignore. - 破坏性工具 (
tenant_offboard, ai_purge)要求明确 confirm: true 防止意外数据丢失的论点。 - 访问令牌仅存储在内存中；此服务器从不将它们记录或持久化到磁盘。
- 服务器不会在自己的端点上强制进行身份验证——在生产环境中部署在具有TLS和访问控制的反向代理后面。
- 旋转
SECRET_KEY 定期使用令牌，并使用具有刷新令牌轮换的短期JWT访问令牌。
