clearlist

ClearList MCP Server

AI リセールマネージャーである ClearList の AI エージェント向けインターフェースです。MCP 互換のエージェント（Claude、ChatGPT、Gemini、Manus、カスタムエージェント）は、ウェブ UI が使用するものと同じ API ルートを通じて、出品の作成、販売ページの公開、予約の管理を行えます。

ユーザーが clearlist.me にアクセスする必要はありません。 アカウント作成、写真の処理、出品情報の生成、公開はすべて、エージェントが会話を通じて行います。

クイックスタート

cd mcp-server
npm install
npm run build

CLI

このパッケージには、REST API に対して出品者の操作を直接スクリプトで実行できる clearlist コマンドラインツールも含まれています。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 Apps（インタラクティブ 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 にバンドルされます。

接続方法は 2 通り

オプション A：新規ユーザー（まだアカウントをお持ちでない場合）

API キーは不要です。エージェントが会話を通じてアカウントを作成します。

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

エージェントは send_verification_code と verify_code を使用して認証します。API キーは自動的に生成され、セッション中はメモリに保存されます。

オプション B：既存ユーザー（API キーをお持ちの場合）

前回のセッションでエージェントがすでにキーを取得している場合：

{
  "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	市区町村を指定して販売ページを公開し、共有可能な URL を取得します
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