内容
# commerce-mcp
**适用于土耳其电商市场places的Model Context Protocol（MCP）服务器**。将服务器连接到Claude Desktop、Claude Code或ChatGPT，让卖家从聊天窗口运行他们的商店——列出订单、更新库存和价格、发货、回复客户问题和分析退货。
> **状态：正在进行，不 yet 生产就绪**。该仓库目前提供了一个完整的Trendyol工具界面（21个工具），由确定性的SQLite模拟适配器支持，以及一个为ChatGPT Apps开发者模式流程搭建的HTTP MCP服务器。真正的Trendyol HTTP适配器部分stubbed——大多数方法在API集成完成之前抛出`UpstreamError`。将此视为开发者预览。
## 为什么
土耳其的大多数市场places卖家仪表盘都很慢、多步骤且为桌面端设计。卖家花费大量时间在重复流程中：检查新订单、更新数千个SKU的价格和库存、发货、回答客户问题、处理退货。MCP服务器允许同一卖家用自然语言描述他们想要的（“son 7 gündeki iadeleri özetle ve sebepleri grupla”），并让LLM调用正确的工具——在进行任何更改之前进行显式确认。
该仓库是开源基础：
- **共享核心抽象** (`MarketplaceAdapter`)，使相同的聊天界面可以扩展到多个市场places。
- **每个市场places的软件包**，实现了适配器的两次——一次针对SQLite模拟器进行本地开发，一次针对真正的REST API。
- **stdio MCP服务器**，适用于Claude Desktop / Claude Code，以及**HTTP MCP服务器**，适用于ChatGPT Apps。
- **安全写入模型**——每个变异工具都分为`preview_*`（返回签名令牌）和`execute_*`（验证令牌），因此LLM无法在没有显式人为确认的第二步的情况下修改状态。
## 目标
- **一个工具界面，多个市场places**。目前：Trendyol。计划：Hepsiburada、n11、Pazarama。添加市场places意味着一个新的工作空间软件包——聊天端的体验保持不变。
- **模拟优先开发**。新贡献者可以克隆仓库，运行`npm run seed:trendyol`，在不到一分钟的时间内拥有一个功能齐全的MCP服务器，并带有现实数据，无需API凭证。
- **生产就绪安全**。预览/执行写入分离、OAuth感知HTTP传输、MCP工具注释（`readOnlyHint`、`destructiveHint`）、每个供应商的速率限制和stderr-only日志记录，保持MCP stdio框架清洁。
- **双语UX**。工具标题和描述以英语和土耳其语编写，以便LLM可以自然地理解两种语言。
## 软件包
| 软件包 | 描述 | 二进制文件 |
|---|---|---|
| `@commerce-mcp/core` | 平台无关的`MarketplaceAdapter`接口、MCP服务器工厂、预览令牌基元、错误类型、日志记录器、速率限制器 | — |
| `@commerce-mcp/trendyol` | Trendyol市场places适配器（模拟+HTTP）和工具注册表 | `trendyol-mcp`（stdio） |
| `@commerce-mcp/app-server` | ChatGPT Apps兼容的HTTP MCP服务器，带有OAuth资源元数据 | `commerce-mcp-app`（HTTP） |
计划：`@commerce-mcp/hepsiburada`、`@commerce-mcp/n11`、`@commerce-mcp/pazarama`。
## 快速入门（模拟模式，无凭证）
需要Node.js 20+。
```bash
git clone https://github.com/<your-org>/commerce-mcp.git
cd commerce-mcp
npm install
npm run build
npm run db:generate:trendyol # 一次性：发出Drizzle迁移SQL
npm run seed:trendyol # 用演示数据填充~/.commerce-mcp/trendyol.db
npm run inspect:trendyol # 用于手动工具调用的MCP检查员UI
```
`TRENDYOL_USE_MOCK=1`（ `.env.example`中的默认值）将所有内容路由到SQLite模拟器——无需API密钥。
## 从Claude Desktop / Claude Code使用
将以下内容添加到 `~/Library/Application Support/Claude/claude_desktop_config.json` （macOS）或 `%APPDATA%\Claude\claude_desktop_config.json` （Windows）：
```json
{
"mcpServers": {
"trendyol": {
"command": "node",
"args": ["/absolute/path/to/commerce-mcp/packages/trendyol/dist/bin/trendyol-mcp.js"],
"env": { "TRENDYOL_USE_MOCK": "1" }
}
}
}
```
一旦发布到npm，这将变为`"command": "npx", "args": ["-y", "@commerce-mcp/trendyol"]`。
## 从ChatGPT（开发者模式）使用
```bash
npm install
npm run build
npm run seed:trendyol
npm run dev:app
```
HTTP服务器暴露：
- `POST /mcp` — ChatGPT开发者模式的流式HTTP MCP端点。
- `GET /.well-known/oauth-protected-resource` — OAuth 2.1受保护资源元数据。
- `GET /healthz` — 本地健康检查。
对于本地开发者模式测试，通过HTTPS隧道（例如ngrok、cloudflared）公开`http://127.0.0.1:2091/mcp`，并将隧道后的`/mcp` URL粘贴到ChatGPT中。
对于生产提交，您还需要：
- 一个稳定的HTTPS源。
- `COMMERCE_MCP_AUTH_REQUIRED=1`和一个真正的OAuth 2.1授权服务器，支持动态客户端注册和PKCE（通过`COMMERCE_MCP_AUTH_ISSUER`设置）。
- 按用户存储Trendyol API凭证（目前在此仓库中不涉及）。
参见 `docs/submission/chatgpt-app-v1.md` 以获取完整的提交清单。
## Trendyol工具
| 工具 | 目的 |
|------|---------|
| `orders_list` | 列出具有状态/日期筛选的发货包裹 |
| `preview_order_ship` / `execute_order_ship` | 预览，然后确认发货包裹 + 附加跟踪号码 |
| `preview_order_cancel` / `execute_order_cancel` | 预览，然后确认取消发货项目 |
| `preview_order_status_update` / `execute_order_status_update` | 预览，然后确认将包裹移动到拣货 / 已开票 |
| `products_list` | 列出具有筛选的产品 |
| `product_get` | 通过条形码或productMainId获取产品详情 |
| `categories_list` | 浏览类别树 |
| `preview_inventory_update` / `execute_inventory_update` | 预览，然后确认批量库存和/或价格更新（返回batchId） |
| `batch_status` | 轮询批量操作结果 |
| `questions_list` | 列出客户问题（最多14天范围） |
| `draft_question_reply` / `send_question_reply` | 起草，然后确认客户问题回复 |
| `claims_list` | 列出退货/认领请求 |
| `shipment_providers_list` | 列出可用的货运提供商 |
| `analyze_store_performance` | 聚合订单、收入、退货、问答、低库存信号 |
| `analyze_returns` | 分组退货/认领原因和受影响的产品 |
| `analyze_product_health` | 标记低库存、审批和定价问题 |
## 架构
```
┌──────────────────────────┐
│ Claude / ChatGPT LLM │
└────────────┬─────────────┘
│ MCP（stdio或HTTP）
┌────────────────────┴────────────────────┐
│ │
┌───────▼──────────┐ ┌───────────▼────────────┐
│ trendyol-mcp │ │ commerce-mcp-app │
│ （stdio二进制） │ │ （Express，POST /mcp） │
└───────┬──────────┘ └───────────┬────────────┘
│ │
└───────────────────┬─────────────────────┘
│
┌─────────▼──────────┐
│ 工具注册表 │ （预览/执行对，读取-仅注释，
│ （21个工具） │ OAuth作用域元数据）
└─────────┬──────────┘
│
┌─────────▼──────────┐
│ MarketplaceAdapter │ ← @commerce-mcp/core接口
└─────────┬──────────┘
┌─────────────┴─────────────┐
│ │
┌──────────▼────────┐ ┌──────────▼─────────┐
│ TrendyolMock │ │ TrendyolHttp │
│ （SQLite + Drizzle）│ │ （axios，部分） │
└───────────────────┘ └────────────────────┘
```
`packages/core`定义了一个平台无关的`MarketplaceAdapter`接口（`orders`、`products`、`inventory`、`qna`、`claims`、`shipmentProviders`），具有统一的领域类型，如`UnifiedOrder`和`UnifiedProduct`。每个市场places软件包都实现了该接口两次——模拟和HTTP——并注册了相同的MCP工具。**添加新的市场places = 新的工作空间软件包；用户端的工具界面保持不变。**
### 安全写入模型
每个变异操作都是两个MCP工具：
1. `preview_<action>` — 只读，返回描述将发生什么的负载 + HMAC签名`previewToken`（10分钟TTL）。
2. `execute_<action>` — 验证令牌的签名、操作名称、过期时间，**以及**提供的参数与预览发出的参数字节匹配（规范稳定字符串后）。
这意味着LLM不能在单个回合中改变市场places状态——它必须显示预览，获得明确确认，然后使用相同的参数调用执行。 HMAC密钥来自`COMMERCE_MCP_CONFIRMATION_SECRET`。
## 配置
所有环境变量都位于`.env.example`中。亮点：
| 变量 | 目的 |
|---|---|
| `TRENDYOL_USE_MOCK` | `1`（默认）路由到SQLite模拟器；未设置/`0`路由到真正的Trendyol API |
| `TRENDYOL_SUPPLIER_ID`、`TRENDYOL_API_KEY`、`TRENDYOL_API_SECRET` | 模拟模式以外时必填（https://partner.trendyol.com） |
| `TRENDYOL_DB_PATH` | 覆盖SQLite模拟器路径（默认`~/.commerce-mcp/trendyol.db`） |
| `COMMERCE_MCP_HOST`、`COMMERCE_MCP_PORT` | HTTP服务器绑定地址（默认`127.0.0.1:2091`） |
| `COMMERCE_MCP_AUTH_REQUIRED` | 在托管环境中设置为`1`，对`/mcp`强制执行Bearer身份验证 |
| `COMMERCE_MCP_AUTH_ISSUER` | 受保护资源元数据的OAuth 2.1颁发者URL |
| `COMMERCE_MCP_CONFIRMATION_SECRET` | 预览令牌的HMAC密钥 - 在任何部署环境中更改此密钥 |
## 开发
```bash
npm run dev:trendyol # stdio二进制文件上的tsx监视
npm run dev:app # HTTP服务器上的tsx监视
npm test # vitest运行（15秒超时）
npm run typecheck # 跨所有软件包的tsc -b
npm run lint # biome检查。
npm run lint:fix # biome检查--write .
```
端到端烟雾脚本（需要`npm run build`）：
```bash
tsx scripts/smoke-test.ts # 直接使用模拟适配器
tsx scripts/mcp-stdio-smoke.ts # 启动stdio二进制文件，驱动JSON-RPC，检查stdout清洁度
```
参见 `CLAUDE.md` 以获取项目特定的约定（stdio纯度规则，drizzle迁移工作流，预览/执行不变式）。
## 路线图
- [ ] 完成Trendyol HTTP适配器（订单、产品、库存、问答、认领）。
- [ ] 一流的OAuth 2.1授权服务器集成（每个用户Trendyol凭证存储）。
- [ ] `@commerce-mcp/hepsiburada`软件包。
- [ ] `@commerce-mcp/n11`软件包。
- [ ] `@commerce-mcp/pazarama`软件包。
- [ ] 已发布的npm工件（`npx -y @commerce-mcp/trendyol`）。
- [ ] ChatGPT Apps提交的托管多租户部署。
## 贡献
欢迎贡献。目前最有价值的领域：
1. **真正的Trendyol HTTP适配器** — 在`packages/trendyol/src/adapter/trendyol-http.adapter.ts`中填写存根方法。
2. **额外的市场places** — 复制`packages/trendyol`，交换模式和API客户端，保持工具界面相同。
3. **模拟数据现实** — `packages/trendyol/src/db/seed.ts`中更好的种子数据使分析工具对演示和测试更有用。
在打开PR之前，请运行`npm run lint`和`npm test`。新的编写工具必须遵循预览/执行分离 - 请参阅`packages/trendyol/src/tools/orders/order-ship.ts`作为参考。
## 许可证
尚未指定。在第一个标记版本之前，将添加许可证文件。在此之前，如果您想在产品中使用此代码，请打开一个问题。
## 致谢
- [Model Context Protocol](https://modelcontextprotocol.io/) — 该服务器实现的开放标准。
- [Trendyol Partner API](https://developers.trendyol.com/) — 底层市场places API。
