clearlist

ClearList MCP 服务

ClearList（一款 AI 转售管理工具）的 AI Agent 接口。任何兼容 MCP 的 Agent（Claude、ChatGPT、Gemini、Manus、自定义 Agent）都可以通过与网页界面相同的 API 路由创建商品信息、发布销售页面并管理预留。

用户永远不需要访问 clearlist.me。 Agent 会完全通过对话处理账户创建、照片处理、商品信息生成和发布。

快速开始

cd mcp-server
npm install
npm run build

命令行工具

此软件包还提供 clearlist 命令行工具，可直接通过 REST API 编写卖家操作脚本——无需 MCP 宿主：

npm install -g @clearlist/mcp-server

clearlist login [email protected]        # send a 6-digit sign-in code
clearlist verify [email protected] 123456  # store the API key in ~/.clearlist/config.json
clearlist items                        # list your listings
clearlist publish --city "Austin"      # publish the sale page, get the URL
clearlist reservations                 # who reserved what
clearlist reply <conversationId> "Yes, still available"
clearlist picked-up <itemId>           # mark an item sold
clearlist status                       # plan, capacity, expiry

每条命令都会输出 JSON（可通过管道传给 jq 编写脚本）。CLEARLIST_API_KEY 会覆盖已存储的密钥；CLEARLIST_API_URL 会覆盖默认值 https://clearlist.me。运行 clearlist help 查看完整参考。

MCP 应用（交互式 UI）

get_listings、publish_page 和 get_reservations 通过 _meta.ui.resourceUri 声明 MCP Apps 视图 （ui://clearlist/app.html）。可渲染 MCP Apps 的宿主（ChatGPT、Claude.ai）会内嵌显示商品图库、发布成功卡片或 预留摘要；不支持 UI 的宿主会忽略元数据，并照常获取相同的 JSON。视图源文件位于 src/ui/views/，并通过 npm run build:ui 打包到 src/ui/generated-views.ts。

两种连接方式

选项 A：新用户（尚无账户）

无需 API 密钥。Agent 会通过对话创建账户：

{
  "mcpServers": {
    "clearlist": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/dist/index.js"],
      "env": {
        "CLEARLIST_API_URL": "https://clearlist.me"
      }
    }
  }
}

Agent 使用 send_verification_code + verify_code 进行身份验证。系统会自动生成 API 密钥，并在会话期间将其保存在内存中。

选项 B：回访用户（已有 API 密钥）

如果 Agent 已有先前会话中使用的密钥：

{
  "mcpServers": {
    "clearlist": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-server/dist/index.js"],
      "env": {
        "CLEARLIST_API_URL": "https://clearlist.me",
        "CLEARLIST_API_KEY": "cl_your_api_key_here"
      }
    }
  }
}

所有工具都可以立即使用——无需引导流程。

工作原理（奶奶流程）

Grandma → ChatGPT: "I'm moving, help me sell my stuff"
ChatGPT: "Sure! What's your email?"
Grandma: "[email protected]"

    [agent calls send_verification_code({ email: "[email protected]" })]

ChatGPT: "I sent you a 6-digit code. Check your email."
Grandma: "482019"

    [agent calls verify_code({ email: "[email protected]", code: "482019" })]
    → account created, API key returned, all tools unlocked

ChatGPT: "Account created! Now send me photos of everything you want to sell."
Grandma: [sends 20 photos]

    [agent calls bulk_create_listings({ photos: [...20 photos] })]
    → AI groups by item, generates listings, researches prices, validates

ChatGPT: "I found 12 items. Here's what I got:
          1. IKEA Kallax Shelf — $45 (Good condition)
          2. KitchenAid Mixer — $120 (Like New)
          ...
          Want me to publish your sale page?"

Grandma: "Yes! I'm in Austin."

    [agent calls publish_page({ city: "Austin", state: "TX" })]

ChatGPT: "Done! Your sale page is live at clearlist.me/grandmas-sale
          Share this link on Facebook or Nextdoor."

奶奶从未访问过网站，从未生成过 API 密钥，也从未手动创建过账户。

可用工具（24 个）

引导工具（2 个）——无需 API 密钥

工具	描述
send_verification_code	向电子邮箱地址发送 6 位验证码
verify_code	验证验证码；如果是新用户则创建账户，并获取 API 密钥

卖家工具（19 个）

工具	描述
create_listing	发送 1-5 张照片 → AI 生成商品信息 → 保存到账户
bulk_create_listings	发送最多 50 张照片 → AI 分组、生成信息、定价并进行质量检查 → 全部保存
edit_listing	更新商品信息的任意字段
delete_listing	永久删除商品信息
publish_page	添加城市信息并发布销售页面，获取可分享的网址
unpublish_page	下线销售页面
get_listings	列出所有商品及其状态、价格和排队数量
get_reservations	查看买家预留、消息和计时器状态
get_conversation	获取与特定买家的完整消息对话
reply_to_buyer	向买家发送消息
mark_picked_up	将商品标记为已售出
confirm_pickup	确认已安排的取货
get_page_stats	页面浏览量、商品数量和预留统计
prepare_crosspost	生成用于 Craigslist/Facebook 的交叉发布内容
set_availability	配置取货时间段
get_profile	获取账户资料和套餐信息
check_tier_status	查看订阅套餐和限额
generate_payment_link	为升级套餐生成 Stripe 付款链接

发现工具（3 个）——第 14 阶段

工具	描述
search_items	按关键词、城市、类别和价格搜索所有销售中的商品
get_sales_near	查找某个位置附近正在进行的销售
get_city_sales	浏览某个城市的所有销售

架构

User (via any AI agent)
  │
  ▼
Agent (ChatGPT, Claude, Gemini, Manus, etc.)
  │
  ▼
ClearList MCP Server (this package)
  │  stdio transport
  │
  ▼
ClearList API Routes (/api/*)
  │  HTTP + X-ClearList-API-Key header
  │
  ▼
Firebase (Firestore, Auth, Storage) + Gemini AI

MCP 服务是一个轻量级协议适配器。不包含任何业务逻辑——所有内容都在 API 路由中。

身份验证流程

                    ┌─────────────────────────────────┐
                    │   Agent starts (no API key)      │
                    └─────────────┬───────────────────┘
                                  │
                    ┌─────────────▼───────────────────┐
                    │  send_verification_code          │
                    │  POST /api/auth/send-code        │
                    │  { email: "[email protected]" }     │
                    └─────────────┬───────────────────┘
                                  │  ← email sent with 6-digit code
                    ┌─────────────▼───────────────────┐
                    │  verify_code                     │
                    │  POST /api/auth/verify-code      │
                    │  { email, code, agent: true }    │
                    └─────────────┬───────────────────┘
                                  │  ← creates account + returns API key
                    ┌─────────────▼───────────────────┐
                    │  API key stored in memory        │
                    │  All subsequent calls use it     │
                    │  X-ClearList-API-Key: cl_xxx     │
                    └─────────────────────────────────┘

开发

# Type-check
npm run type-check

# Build
npm run build

# Run directly (for testing)
CLEARLIST_API_URL=http://localhost:3000 npm run dev