thingery

Thingery

Thingery は、AI エージェントが中古品を出品、検索、取引するためのオープンなアイテムデータベース兼 MCP サーバーです。

AI アシスタントに「これを売って」と伝えると、アイテムを識別し、出品情報を作成し、価格を設定して公開します。「300 ユーロ以下の中古カメラを探して」と伝えると、すべての出品を検索し、最適なものを提案します。Thingery は、エージェントが利用する共有データベースと MCP ツールを提供します。

• 誰でも無料で利用できます。取引手数料やプラットフォームへのロックインはありません。
• オープンソース（Apache-2.0）です。すべてをセルフホストすることも、公式インスタンスを利用することもできます。
• エージェントネイティブです。すべての機能が MCP ツールとして提供され、あらゆる LLM から利用できます。
• セルフホスト可能です。Postgres + pgvector + Node 20 で動作します。

中国市場での名称：物坊（Wùfāng）。

MCP ツール

ツール	認証	目的
describe_category	公開	カテゴリーと、定義済みの属性フィールドを一覧表示します。エージェント向けの自己記述型スキーマです。定義済みフィールドは作成時に検証されます。未定義のキーも使用でき、検索可能です。また、実際に使用されているキーは undeclared_in_use を通じて確認できます
search_items	公開	価格、カテゴリー、状態、属性によるフィルター（定義済みかどうかを問わず、すべての属性キーに対応）を使った、セマンティック検索とキーワード検索のハイブリッド検索です
get_item	公開	ID で出品を 1 件取得します。保留中（写真なし）の出品も返され、needs_photo: true が含まれます
create_listing	出品者	アイテムを公開します。基本フィールドに加え、柔軟な attributes オブジェクトを使用できます（定義済みのキーは検証され、追加のキーはそのまま保持され、検索可能です）。写真が 1 枚以上追加されるまで、出品は検索結果に表示されません。画像 0 枚で作成しても処理は成功しますが、写真が追加されるまでは保留状態（結果に visible: false と next_steps が含まれる）になります
add_item_image	出品者	出品に写真を添付します（base64 を入力し、サーバー側に保存します。URL は不要です。デコード後の最大サイズは 5 MB）。最初の写真を追加すると保留中の出品が公開されます。公開状態は結果の visible で確認できます。画像は取り込み時に再エンコードされ、メタデータ（EXIF/GPS/XMP）が削除され、最大 2000 px に縮小されます。アニメーション GIF は静止画として保存されます。大きな PNG は拒否される場合があるため、JPEG をおすすめします
my_listings	出品者	ステータス別に自分の出品を表示します
update_listing	出品者	予約済み／販売済みへの変更、価格の調整、テキストや属性の編集を行います

注文フロー

ツール	認証	用途
get_payout_setup	seller	Stripe Express のオンボーディング URL とステータス — 任意。プラットフォーム決済を有効にします
create_order	account	商品を注文します — Stripe モードでは Stripe Checkout URL を返し、プラットフォーム外モードでは注文を追跡します
get_order	account	自分の注文（購入者または販売者側）：ステータス、追跡情報、期限
cancel_order	account	キャンセル可能な間にキャンセルします。支払い済みの注文は代わりに返金されます
record_tracking	seller	配送業者と追跡コードを記録します。EasyPost が設定されている場合は配送業者の追跡を自動で行います
confirm_payment	seller	プラットフォーム外での支払いを確定します（pending → sold）
confirm_receipt	buyer	配達を確認します — 異議申し立て期間が始まります
open_dispute	buyer	配達済みの注文に異議を申し立てます。販売者への支払いは保留されます
release_funds	buyer	異議申し立て期間を放棄し、販売者への支払いをただちに実行します

注文により、プラットフォーム上で取引を完了できます。Stripe モード（購入者保護：プラットフォームが購入者に請求し、資金を保留して、配達と異議申し立て期間の終了後に販売者へ支払います）は、デプロイ環境で Stripe が設定され、かつ販売者が支払いのオンボーディングを完了している場合に動作します。それ以外の場合、注文はプラットフォーム外モードで進行します — Thingery が状態と期限を追跡し、当事者間で直接決済します。状態：pending → sold → label_issued → in_transit → delivered → payout_pending → paid_out。途中で disputed／cancelled／refunded に移行する場合もあります。期限はサーバー側の定期処理によって適用されます（未払いは24時間後にキャンセル、異議申し立て期間は48時間、未発送の注文は72時間後に自動返金 — これらはデフォルト値で、環境変数で調整できます）。設計記録：ADR 0003。

販売者は OAuth（任意の MCP ホストからワンクリックでサインイン — 詳細は以下を参照）または thg_... API キー（Authorization: Bearer）で認証します。検索は匿名で利用できます。

購入者アラート

ツール	認証	用途
save_intent	seller	購入者アラートを保存します — 探している商品を自由記述のクエリや構造化フィルター（カテゴリ、状態、価格帯、配送区分、属性）で指定します。保存できるインテントは最大25件、1日の保存回数は50回です
my_intents	seller	保存したアラートを新しい順に表示します。各アラートの未読マッチ件数とミュート状態も確認できます
update_intent	seller	1件のアラートをミュートまたはミュート解除します — ミュートしたアラートには新しいマッチが追加されなくなります
delete_intent	seller	アラートとそのマッチ記録を削除します

保存したインテントは購入者アラートに反映されます。インテントに一致する新しい出品が公開されると、そのマッチが my_intents の未読件数に表示されます（専用の my_matches ビューは近日公開予定です）。

写真必須の出品

新しい出品を購入者に表示するには、少なくとも1枚の写真が必要です — 一覧表示、search_items、カテゴリ別件数では、写真のない出品はすべて除外されます（共通の派生述語を使用。設計記録：ADR 0005）。実際の動作は次のとおりです。

• 画像が0枚の状態で create_listing を実行しても成功します — 出品は作成されますが、保留中となり、フィードには表示されません。商品ページにはプレースホルダー画像が表示され、noindex になります。結果には photo_required、visible: false、および add_item_image（または所有者が2回タップするだけで写真を撮影できる商品ページ）を示す next_steps が含まれます。
• 最初の写真を追加すると出品が公開されます — 2回目の呼び出しは必要ありません。add_item_image は visible: true を返します。保留中の商品には、商品が返されるすべての場所（get_item、my_listings、…）で needs_photo: true が含まれます。
• 最後の写真を削除すると、出品は保留中（再び非表示）に戻ります。ロールアウト前の出品は既存のものとして扱われ、写真がなくても公開状態を維持します — thingery.dev では2026-10-27より前に作成された出品が対象です。セルフホスト可能なインスタンスでは、このバージョンを最初にデプロイした時点で存在する出品がすべて対象になります。
• 所有者は docs/item-images.md に記載されたセッションクッキールートを通じて、商品ページで写真のアップロード、削除、並べ替えを行います。

使い方は2通り

• 設定不要（すべてのユーザー向け）： どのデプロイ環境でも /chat.html を開いて、Thingery アシスタントと会話できます。売りたい、または探しているアイテムについて説明してください。検索にアカウントは不要です。出品には無料アカウントが必要です（/login.html、メールアドレス＋パスワード。登録後に MCP API キーが表示されます）。 チャットでは、サーバーで設定された LLM（LLM_* env vars）を使用します。キーはご自身で用意してください。OpenAI 互換のエンドポイントであれば使用できます。キーがない場合、チャットは無効になりますが、MCP と登録は引き続き利用できます。
• 独自のエージェントを使う（上級者向け）： 任意の MCP クライアントを /mcp に接続し、OAuth でサインインしてください。Claude Desktop、ChatGPT connectors、VS Code、Inspector はサインインのフローを自動で検出します（RFC 9728 リソースメタデータ＋RFC 7591 動的クライアント登録）。同意画面で一度承認すると、ホストにはローテーションする thgo_ トークンが発行されます。トークンはいつでも /apps で取り消せます。キーを使いたい場合は、手動の thg_... API キーも引き続き使用できます。セルフホストについては以下をご覧ください（stdio 経由の npx thingery）。

クイックスタート

まず利用モードを選んでください。ホスト型とセルフホスト型で公開される MCP ツールは同じですが、データは異なります。ホスト型サービスで作成した出品はすべてのユーザーに表示されます。セルフホスト型インスタンスの出品は、独自のデータベース内でのみ利用できます。

モード	エンドポイント	データ	おすすめの用途
ホスト型	https://thingery.dev/mcp	共有の公開マーケットプレイス	1分以内に使い始めたい場合。インストール不要
セルフホスト型	独自の /mcp、または stdio	独自の Postgres、独自のデータ	プライベートなデプロイ、完全な制御、開発

モード A — ホスト型：1分で検索

インストールは不要です。MCP クライアント（Claude Desktop、ChatGPT connectors、VS Code、Inspector。MCP クライアントの接続を参照）に https://thingery.dev/mcp をリモート HTTP サーバーとして追加し、OAuth でサインインしてください。または、/login.html で API キーを取得してください（無料アカウントが必要です。登録後に thg_... キーが表示されます）。検索にアカウントは一切不要です。curl で通信形式を確認できます。

curl -s https://thingery.dev/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call",
       "params":{"name":"search_items","arguments":{"q":"Air Max"}}}'

レスポンスは Server-Sent Events として返されます。JSON-RPC の結果は data: 行にあります。

モード B — セルフホスト型：npm パッケージ

thingery npm パッケージを使うと、独自の Postgres 上でサーバー全体を実行できます。git clone は不要です。

mkdir my-thingery && cd my-thingery
npm install thingery

# 1. a Postgres with the pgvector extension (Docker: `docker run -d -p 5432:5432 \
#    -e POSTGRES_PASSWORD=thingery pgvector/pgvector:pg16`; Homebrew: see below)
# 2. apply the shipped schema (idempotent, safe to re-run):
psql "postgres://postgres:thingery@localhost:5432/postgres" \
  -f node_modules/thingery/db/schema.sql

# 3. run it (DATABASE_URL is the only required env var):
DATABASE_URL="postgres://postgres:thingery@localhost:5432/postgres" \
PORT=3000 node node_modules/thingery/dist/index.js

サーバーは http://localhost:3000 で起動し、/mcp、/browse、/healthz、HTTP API を利用できます。/login.html を開いてアカウントを作成してください。登録直後に thg_... MCP キーが表示されます。（修正前の 0.1.2 リリースでは、パッケージングの不備によりページが 404 になりました。この問題はその後修正されています。このリリースでは API 経由でもアカウントを作成でき、キーは登録レスポンスで一度だけ返されます。）

curl -s -X POST http://localhost:3000/api/signup \
  -H 'content-type: application/json' \
  -d '{"email":"[email protected]","password":"at-least-8-chars"}'
# → {"seller":{"name":"you","email":"…","api_key":"thg_…"}}

その後、Authorization: Bearer thg_... を指定して任意の MCP クライアントを http://localhost:3000/mcp に接続するか、npx の設定を使って stdio 経由で起動してください。

注：npm パッケージはリリースのタイミングで公開されるため、thingery.dev の main より数日遅れる場合があります。/healthz で実行中のバージョンを確認できます。最新の機能が必要な場合は、代わりにソースからセルフホストしてください。

ソースからのセルフホスト（開発）

git clone https://github.com/thingery/thingery
cd thingery
npm install
docker compose up -d db          # Postgres 16 + pgvector
cp .env.example .env
npm run db:migrate
npm run db:seed                  # demo seller + 3 listings; prints an API key
npm run dev                      # http://localhost:3000

Docker を使わない場合：ローカルの Postgres

npm run db:migrate には vector 拡張機能を備えた Postgres が必要です。キーワードのみの検索モードでも、スキーマ作成時に必ず有効化されます。macOS では、Homebrew の pgvector ボトルは PostgreSQL 17 と 18 に対応しています（Docker の設定で使われるバージョンである 16 には対応していません。いずれのバージョンも Thingery で動作します）。

brew install postgresql@18 pgvector
brew services start postgresql@18
psql postgres -c "CREATE ROLE thingery LOGIN PASSWORD 'thingery';" \
              -c "CREATE DATABASE thingery OWNER thingery;"
psql -d thingery -c "CREATE EXTENSION vector;"   # run as the Postgres superuser

.env.example のデフォルトの DATABASE_URL は、すでにこの設定に合っています。それ以外の Postgres を使う場合は、スーパーユーザーとして同じ2つの SQL 文を実行し、DATABASE_URL をそのデータベースに設定してください。

MCP クライアントを接続する

ほとんどのホスト（Claude Desktop、ChatGPT コネクター、VS Code、Inspector）は OAuth でサインインできます。 https://thingery.dev/mcp（またはセルフホスト環境の URL）をリモート HTTP サーバーとして追加するだけです。ホストがサインインフローを検出し、承認を一度行えば、トークンは自動的にローテーションされます。thingery.dev では、/apps で接続済みアプリケーションを確認し、アクセスを取り消すことができます。

OAuth に対応していないホストでは、代わりに thg_... API キー（/login.html から取得）を静的なベアラートークンとして使用します。

{
  "mcpServers": {
    "thingery": {
      "type": "http",
      "url": "http://localhost:3000/mcp",
      "headers": { "Authorization": "Bearer thg_YOUR_KEY" }
    }
  }
}

購入者向けのみ（公開検索）で使用する場合は、Authorization ヘッダーを省略してください。公開読み取りツールへの匿名アクセスは常に利用できます。設計メモ：OAuth フローの決定記録はdocs/adr/0002-mcp-oauth-onboarding.mdにあります。OAuth ルートを完全に無効にするには OAUTH_DISABLED=1 を設定します（その場合、ホストはキーにフォールバックします）。

stdio でローカル実行する（npx）

ウェブサーバーを使わずにセルフホストできます。パッケージは npm 上の thingery で、独自の Postgres に接続するローカル stdio MCP サーバーとして実行されます。Claude Desktop などのクライアントから起動できます。

{
  "mcpServers": {
    "thingery": {
      "command": "npx",
      "args": ["-y", "thingery"],
      "env": {
        "DATABASE_URL": "postgres://thingery:thingery@localhost:5432/thingery",
        "THINGERY_API_KEY": "thg_YOUR_KEY"
      }
    }
  }
}

THINGERY_API_KEY は省略可能です。設定しない場合、サーバーは読み取り専用（検索＋取得）で実行されます。stdio サーバーには Mode B と同じ前提条件が必要です。スキーマを適用した Postgres（psql -f node_modules/thingery/db/schema.sql）と、書き込みツールを使用する場合は、そのデータベースに存在するキー（そのデプロイの /login.html または /api/signup から取得）が必要です。

トラブルシューティング

症状	原因	解決方法
search_items で「sneakers」のような一般的な単語を検索しても 0 件が返る	thingery.dev ではキーワードのみの検索が実行されます（エンベディングは設定されていません）。タイトルや説明に含まれる文字列と完全一致する単語を検索するため、「sneakers」という単語を含む掲載情報はありません	ブランド名や商品名（"Air Max"、"Samba"）で検索するか、代わりに category で絞り込んでください
create_listing が visible: false を返す	写真が必須の公開設定です。画像が 0 枚の掲載情報は保留状態になり、非表示のままです	add_item_image を呼び出してください。最初の写真を追加すると掲載情報が公開されます
HTTP 401 authentication required	認証情報なしで保護対象のツールが呼び出されました	OAuth でサインインするか、Authorization: Bearer thg_... を送信してください
/mcp から HTTP 406 が返る	MCP Streamable HTTP トランスポートには SSE の Accept ヘッダーが必要です	accept: application/json, text/event-stream を送信してください
インストール済みパッケージ内で npm run db:migrate が失敗する	scripts/ は公開されていません。スキーマは db/schema.sql として同梱されています	psql "$DATABASE_URL" -f node_modules/thingery/db/schema.sql
stdio の警告：THINGERY_API_KEY set but not found in the database	そのキーは別のデプロイのデータベースに属しています	このデプロイからキーを取得してください（/login.html または /api/signup）
セルフホスト環境の動作が thingery.dev と異なる	npm リリースは main より遅れている場合があります（例：写真による公開制限）	/healthz のバージョンを比較してください。現在の main からソースを使ってセルフホストしてください

curl で試す

# List tools (the Accept header is required by the MCP Streamable HTTP transport)
curl -s http://localhost:3000/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# Search (finds the seeded Nike Air Max: €85 is within the €100 filter)
curl -s http://localhost:3000/mcp \
  -H 'content-type: application/json' \
  -H 'accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
       "params":{"name":"search_items","arguments":{"q":"air max","max_price_cents":10000}}}'

レスポンスは Server-Sent Events として返されます。JSON-RPC の結果は data: 行にあります。

エージェントフレームワーク（LangChain、LlamaIndex、Composio）を使う

フレームワークのツールキットは、ストリーミング可能な HTTP 経由で同じ /mcp エンドポイントに接続します。検証済みのエンドツーエンドのツール呼び出しを含むクイックスタートは、examples/integrations/にあります。

設定

.env.example を .env にコピーします。主な変数は次のとおりです。

変数	用途
DATABASE_URL	Postgres の接続文字列
PORT / PUBLIC_BASE_URL	HTTP ポートと、アイテムリンクに使用するベース URL
EMBED_API_URL / EMBED_API_KEY / EMBED_MODEL	OpenAI 互換の埋め込みエンドポイント。キーワードのみで検索する場合は、キーを空にします
STRIPE_SECRET_KEY / STRIPE_WEBHOOK_SECRET	注文フローの決済（Stripe Connect）。キーが空の場合、プラットフォーム決済は無効になり、注文はプラットフォーム外で処理されます。Webhook シークレットなしでキーを設定すると、Webhook が設定されるまで決済は保留されます（フェイルクローズ）
EASYPOST_API_KEY / EASYPOST_WEBHOOK_SECRET	任意の配送業者追跡の自動化。設定しない場合、購入者／販売者が手動で配達を確認します
ADMIN_API_KEY	管理者向けの紛争解決ルート。32 文字以上でない限り無効です

注文フローの期間と不正利用の上限（PAYMENT_DEADLINE_HOURS、DISPUTE_WINDOW_HOURS、 PICKUP_AUTOCONFIRM_DAYS、MAX_PENDING_ORDERS_PER_BUYER、…）については、デフォルト値とともに .env.example 内に記載されています。

エージェントスキル

• skills/sell-item — 販売者のパイプライン：写真 → 特定されたアイテム → 価格設定済みの出品
• skills/find-item — 購入者のパイプライン：意図 → スコア付けされた候補 → 最適な提案 1 件

データ規約

• 価格はセント単位の整数です：12500 = EUR 125.00
• 状態：new、like_new、good、fair、poor
• 配送区分：locker（靴箱サイズ）、parcel（≤30kg）、bulky（家具）、local（受け取り）
• マシン向けの検出情報：llms.txt · agents.json

柔軟なスキーマ

スニーカー、カメラ、ソファに共通する固定のカラムセットはないため、Item Graph はハイブリッド方式です。

• すべてのアイテムに共通する項目のための固定コアカラム：識別情報、価格、状態、ステータス、カテゴリ、配送見積もり、埋め込み。これらはインデックス作成とビジネスロジックを支えます。
• attributes JSONB はカテゴリ固有の項目（size_eu、colorway、shutter_count、ISBN など）に使用します。包含フィルター（{"size_eu": 43}）用に GIN インデックスが付けられ、セマンティック埋め込みにもフラット化されるため、意味による検索にも利用できます。
• categories レジストリは、カテゴリごとに想定される属性定義を宣言します。create_listing は宣言済みのキー（型、必須項目、列挙値）を検証しますが、未知のキーはそのまま受け入れます。柔軟性を重視した設計であり、属性がインスタンス間で異なっていても同期を壊さないため、フェデレーションにも適しています。エージェントは describe_category からスキーマを自分で取得できます。
• sellers.profile JSONB はユーザー側の柔軟性（ロケール、通貨、通知設定、交渉に関する指示など）に使用します。今後の機能向けに確保されています。

拡張方法：ある属性が頻繁に使われるフィルターになった場合は、Postgres の生成カラムとインデックスに昇格させます。API の変更は必要ありません。

宣言されていないキーのうち、実際に使用されているものも確認できます。describe_category は undeclared_in_use を返します。これは、複数の販売者によるアクティブな出品で確認された未宣言の属性キーと、アイテム数および販売者のユニーク数です。これらのキーは検証されず（そのまま受け入れられるため）、契約ではなく検索のヒントとして扱ってください。これは、購入者が現在どの項目で絞り込めるかを示す情報です。

エージェント向けの undeclared_in_use の読み方：

• 表示されるキーは最大 20 件で、2 件以上のアクティブな出品に含まれ、かつ 2 人以上の販売者が使用しているキーに限られます。該当するキーがない場合、このフィールド自体が省略されます。
• 値は自由形式です。同じ未宣言のキーでも、出品ごとに異なる値（型が異なる場合もあります）を持つことがあります。search_items の属性フィルターにはキーを使用できます。宣言済みかどうかにかかわらず、任意のキーに一致します。ただし、ある出品の値をカテゴリ全体の契約として扱わないでください。
• create_listing と update_listing での書き込みには形式上の上限があります。属性エントリは最大 64 件、キーは最大 128 文字、文字列値は最大 500 文字です。上限を超えると、呼び出しは invalid_attributes で失敗します。

ロードマップ

1. 注文ステートマシン — リリース済み：Stripe Connect による支払い、配送業者の Webhook、異議申し立て、期限の定期チェックに対応した注文 (ADR 0003)。次の予定：法務および利用規約の承認後、Stripe の本番モードに移行します。
2. 販売者スキルのアップグレード — 写真撮影機能をリリース済み：商品ページで手軽に撮影でき、プレースホルダー画像を用意し、写真がある商品のみ公開できます (ADR 0005)。類似商品に基づく価格設定は、実際に比較対象となるほど出品数が増えるまで延期します。
3. 購入者アラート — 次の予定：「希望条件に新たに一致する商品があります」というイベントストリーム。
4. フェデレーションプロトコル — インスタンス間で同期し、誰でも Item Graph のノードをホストできるようにします。延期。
5. エージェント間交渉 — 購入者と販売者のエージェント間で、権限の範囲を限定して交渉します。延期。

フェデレーションと交渉については、実際に利用が定着してから再検討します。具体的には、2 週連続で週あたりの新規出品が 10 件を超えたとき、またはセルフホスト導入者から具体的な要望があったときです。

セキュリティ

確認済みの内容と未確認の内容については、docs/security-note.md をご覧ください。脆弱性を非公開で報告するには、SECURITY.md をご覧ください。

コントリビューション

エージェントチームが人間のアーキテクトとともに開発しています。作業規約については AGENTS.md をご覧ください。 プルリクエストを歓迎します。CI（型チェック、ビルド、テスト）がすべて成功する必要があります。初めての方は、 docs/community.md から始めてください。初めての方に適した課題、10 分以内でできる開発環境のセットアップ方法、 質問できる場所を紹介しています。

ライセンス

Apache-2.0