Photo Marketplace Listing Assistant

スマートフォンで商品写真を撮り、AIでタイトル・説明・状態・価格候補・確認事項を生成するWebアプリです。メルカリShopsは公式GraphQL APIで非公開/公開出品まで行えます。個人版メルカリとYahoo!オークションは、公式の一般向け出品APIが確認できない、または自動出品が制限されるため、確認用原稿とCSVを生成します。

AIは写真に写っていない型番、真贋、動作、傷を保証しません。出品者が必ず最終確認してください。

できること

• スマホのカメラ撮影、最大4枚の写真選択、ブラウザ内画像圧縮
• OpenAI Responses APIの画像入力とStructured Outputsによる日本語出品原稿
• メルカリShops公式APIの createProduct、productCategories、states
• Cloudflare R2へ画像保存し、公式APIが取得できるHTTPS URLを発行
• 個人版メルカリ/Yahoo!オークション向けコピー・CSV
• stdio MCPサーバー（写真解析、公式API出品、原稿整形）
• Cloudflare Pages、GitHub Actions、Codespaces/devcontainer

アーキテクチャと処理の流れ

flowchart LR
    U[スマートフォンのカメラ] --> P[React / Vite Web UI]
    P -->|data URL + 補足| A[Pages Function /api/analyze]
    A --> O[OpenAI Responses API]
    O --> A --> P
    P -->|画像| I[Pages Function /api/images]
    I --> R[(Cloudflare R2)]
    R --> H[公開HTTPS画像URL]
    P -->|確認済み商品データ| M[Pages Function /api/mercari/publish]
    H --> M
    M -->|Bearer + User-Agent| S[Mercari Shops GraphQL API]
    P --> E[個人版向けコピー / CSV]
    C[AIクライアント] --> X[stdio MCP Server]
    X --> O
    X --> S
    G[GitHub Actions] --> T[Typecheck / Test / Build]
    G --> D[dist artifact]

詳細設計は docs/architecture.md、初期設定は docs/setup.md を参照してください。

最短セットアップ

1. Cloudflare PagesのSettings → Variables and Secretsへ OPENAI_API_KEY をSecretとして登録。
2. R2 bucketを作り、Pagesプロジェクトに LISTING_IMAGES というbinding名で接続。
3. PUBLIC_BASE_URL にPages本番URLを登録。
4. メルカリShopsでAPI利用契約・Personal API Access Tokenを取得し、MERCARI_SHOPS_TOKEN と MERCARI_SHOPS_USER_AGENT をSecret登録。
5. まずSandboxと UNOPENED（非公開）でテスト。

メルカリShops APIはアクセストークンと正しいUser-Agentを要求します。また契約・環境によって日本国内の登録済み固定IPが必要です。Cloudflare Pagesの送信元を登録できない場合は固定IP relayを用意し、MERCARI_API_PROXY_URL に設定します。

MCP

npm install
OPENAI_API_KEY=... npm run mcp

MCPクライアント設定例:

{
  "mcpServers": {
    "photo-listing": {
      "command": "npm",
      "args": ["run", "mcp"],
      "cwd": "/absolute/path/to/photo-marketplace-listing-assistant",
      "env": {
        "OPENAI_API_KEY": "${OPENAI_API_KEY}",
        "MERCARI_SHOPS_TOKEN": "${MERCARI_SHOPS_TOKEN}",
        "MERCARI_SHOPS_USER_AGENT": "${MERCARI_SHOPS_USER_AGENT}"
      }
    }
  }
}

公開tools:

• analyze_listing_photos
• publish_mercari_shops
• export_marketplace_draft

開発・検証

npm install
npm run dev
npm run typecheck
npm test
npm run build

公式資料と採用判断

• Mercari Shops GraphQL API: https://api.mercari-shops.com/docs/index.html
• Production: https://api.mercari-shops.com/v1/graphql
• Sandbox: https://api.mercari-shops-sandbox.com/v1/graphql
• Yahoo!オークション旧Web API終了案内: https://developer.yahoo.co.jp/changelog/2020-01-24-auction.html

非公式スクレイピング、ログインCookie共有、CAPTCHA回避、個人アカウントへの無許可ブラウザ自動出品は採用していません。